phinpilot MCP 服务器

phinpilot 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 模型提供项目内组件的查询和详情获取功能。

功能特性

🧠 项目知识获取 (get_project_knowledge)

• 【必须首先调用】 获取项目背景知识和开发规范
• 包含技术栈、样式规范、组件使用指南和代码示例
• 在进行任何代码开发前，必须先调用此工具了解项目规范

🔍 组件列表查询 (get_component_list)

• 获取项目内所有可用的组件列表
• 支持按关键词搜索组件名称或使用场景
• 支持限制返回结果数量
• 提供组件的基本信息（名称和使用场景）

🔧 组件定义获取 (get_component_define)

• 获取组件的TypeScript接口定义和属性说明
• 返回组件的类型定义和接口文档
• 支持内容长度限制，防止过长内容

📄 组件源码获取 (get_component_source)

• 获取组件的完整实现代码
• 用于学习和参考组件的具体实现
• 支持多种文件格式和目录结构
• 支持内容截取，避免过长输出

📖 组件文档获取 (get_component_readme)

• 获取组件的使用文档和说明信息
• 返回组件的README文档内容
• 包含组件的使用指南和注意事项

🎯 组件示例获取 (get_component_demos)

• 获取组件的使用示例代码和演示效果
• 支持获取多个示例文件
• 可配置返回的示例数量和内容长度
• 可选择是否包含示例文件内容

安装和使用

环境要求

• Node.js 18+
• npm 或 yarn

安装依赖

npm install

启动服务器

方式1：直接启动（使用当前目录作为项目根目录）

npm start

方式2：指定项目根目录

# 使用环境变量
PROJECT_ROOT=/path/to/your/project npm start

# 或者使用命令行参数
node src/index.js /path/to/your/project

在 cursor 中配置

在 cursor 的配置文件中添加以下配置：

{
  "mcpServers": {
    "phinpilot": {
      "command": "npx",
      "args": [
        "phinpilot",
        "/Users/wuzixuan/code-lib/dataphin" // 修改此处为你的dataphin项目地址
      ],
      "cwd": "/Users/wuzixuan/code-lib/phinpilot" 
    }
  }
}

MCP 工具说明

1. get_project_knowledge

【必须首先调用】 获取项目背景知识和开发规范。

参数：

• 无需参数

返回：

• 项目技术栈信息
• 样式规范和设计指南
• 组件使用规范
• 代码示例和最佳实践

示例：

工具：get_project_knowledge
参数：{}

2. get_component_list

获取项目内所有可用的组件列表。

参数：

• search (可选): 搜索关键词，可以匹配组件名称或使用场景
• limit (可选): 返回结果的最大数量，默认为50

返回：

• 组件列表和基本信息
• 匹配的组件数量
• 搜索关键词（如果有）

示例：

工具：get_component_list
参数：{"search": "table", "limit": 5}

3. get_component_define

获取组件的TypeScript接口定义和属性说明。

参数：

• componentName (必需): 要获取定义的组件名称
• maxContentLength (可选): 内容的最大长度（字符数），超过会被截取，默认为5000

返回：

• 组件的TypeScript类型定义
• 接口属性说明
• 类型约束信息

示例：

工具：get_component_define
参数：{"componentName": "DPTable", "maxContentLength": 3000}

4. get_component_source

获取组件的完整实现代码。

参数：

• componentName (必需): 要获取源码的组件名称
• maxContentLength (可选): 内容的最大长度（字符数），超过会被截取，默认为8000

返回：

• 组件的完整源代码
• 文件路径信息
• 代码实现细节

示例：

工具：get_component_source
参数：{"componentName": "DPButton", "maxContentLength": 5000}

5. get_component_readme

获取组件的使用文档和说明信息。

参数：

• componentName (必需): 要获取文档的组件名称
• maxContentLength (可选): 内容的最大长度（字符数），超过会被截取，默认为10000

返回：

• 组件的README文档内容
• 使用指南和说明
• 注意事项和最佳实践

示例：

工具：get_component_readme
参数：{"componentName": "DPForm"}

6. get_component_demos

获取组件的使用示例代码和演示效果。

参数：

• componentName (必需): 要获取示例的组件名称
• maxDemoCount (可选): 最多返回的demo示例数量，默认为5
• maxContentLength (可选): 单个demo文件内容的最大长度（字符数），超过会被截取，默认为3000
• includeContent (可选): 是否包含demo文件内容，false时只返回文件列表，默认为true

返回：

• 组件的示例代码
• 演示效果说明
• 使用场景示例

示例：

工具：get_component_demos
参数：{"componentName": "DPChart", "maxDemoCount": 3, "includeContent": true}

项目结构要求

必需的资源文件

1. 组件信息文件

服务器需要 src/resources/components-info.json 文件，包含组件的基本信息：

{
  "timestamp": "2025-07-04T07:48:06.884Z",
  "totalCount": 82,
  "components": [
    {
      "name": "ComponentName",
      "whenToUse": "组件的使用场景描述"
    }
  ]
}

2. 项目知识文件

服务器需要 src/resources/project-knowledge.md 文件，包含项目的背景知识和开发规范：

• 技术栈信息
• 样式规范和设计指南
• 组件使用规范
• 代码示例和最佳实践

组件文件结构

对于每个组件，推荐的目录结构为：

src/components/ComponentName/
├── ComponentName.tsx          # 主要实现文件
├── index.tsx                  # 导出文件
├── define.ts                  # TypeScript类型定义
├── README.md                  # 组件文档
└── demos/                     # 示例目录
    ├── basic.tsx              # 基础示例
    ├── advanced.tsx           # 高级示例
    └── ...

组件文件查找

服务器会在以下目录中查找组件实现文件：

• src/components/
• components/
• src/
• lib/components/
• packages/

支持的文件格式：

• 主要实现：ComponentName.tsx, ComponentName.ts, index.tsx, index.ts
• 类型定义：define.ts
• 文档文件：README.md
• 示例文件：demos/ 目录下的各种格式文件

开发和测试

运行测试

# 测试组件列表功能
node quick-test.js

# 测试组件详情功能
node test-component-details.js

# 使用调试客户端测试所有功能
node debug-client.js

开发模式

npm run dev

测试MCP连接

# 使用测试脚本验证MCP服务器
./test-mcp.sh

技术栈

• MCP SDK: @modelcontextprotocol/sdk
• Schema验证: Zod
• Transport: STDIO (标准输入输出)
• 文件系统: Node.js fs/promises

错误处理

• 自动处理文件路径问题，支持多种部署环境
• 提供详细的错误信息和建议
• 当组件不存在时提供可用组件的提示

注意事项

1. 项目根目录设置: 确保正确设置项目根目录，这影响组件文件的查找
2. 文件权限: 确保服务器有权限读取项目目录中的文件
3. 组件信息同步: 保持 components-info.json 文件与实际组件的同步
4. 项目知识文件: 确保 src/resources/project-knowledge.md 文件存在且内容完整
5. 首次使用: 在使用其他工具前，务必先调用 get_project_knowledge 获取项目规范
6. 组件结构: 推荐按照标准目录结构组织组件文件，以获得最佳体验

许可证

MIT License