phinix MCP 服务器

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

功能特性

🔍 组件列表查询 (get_component_list)

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

🔧 组件定义获取 (get_component_define)

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

📄 组件源码获取 (get_component_source)

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

📖 组件文档获取 (get_component_readme)

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

🎯 组件示例获取 (get_component_demos)

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

🔍 对接后端接口 (get_api_definition)

• 对接后端接口。当您需要对接后端接口时，这个工具将很符合你。您必须提供 url 来标识特定的接口,并且url必须以 /api 开头。此工具将直接返回接口的使用React代码供开发者直接使用。此工具还会返回生成代码时必须遵循的规则。
• 返回接口的使用示例
• 返回生成代码时必须遵循的规则

安装和使用

环境要求

• 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": {
    "phinix": {
      "command": "npx",
      "args": [
        "phinix",
        "/Users/wuzixuan/code-lib/dataphin" // 修改此处为你的dataphin项目地址
      ],
      "cwd": "/Users/wuzixuan/code-lib/phinix",
      "env": {
        "ANALYTICS_ENABLED": "true",
        "ANALYTICS_REPORT_URL": "https://your-analytics-server.com/api/track",
        "AUTHOR": "your-name"
      }
    }
  }
}

埋点统计配置（可选）

埋点功能已默认启用并配置为上报到线上服务。

默认域名（自动切换）：

• 主域名：https://giti.lydaas.com/api/mcp/analytics/report
• 备用域名：https://giti.alibaba.net/api/mcp/analytics/report（主域名不可用时自动切换）

如果需要修改配置，可以在 env 字段中设置：

• ANALYTICS_ENABLED: 是否启用埋点（默认：true）
• ANALYTICS_REPORT_URL: 自定义上报地址（可选，设置后将替代默认域名）
• ANALYTICS_BATCH_SIZE: 批量上报大小（默认：10，最大：100）
• ANALYTICS_RETRY_TIMES: 失败重试次数（默认：3）
• AUTHOR: 作者信息（默认：unknown）

快速禁用埋点：

{
  "env": {
    "ANALYTICS_ENABLED": "false"
  }
}

MCP 工具说明

1. get_component_list

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

参数：

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

返回：

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

示例：

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

2. get_component_define

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

参数：

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

返回：

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

示例：

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

3. get_component_source

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

参数：

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

返回：

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

示例：

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

4. get_component_readme

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

参数：

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

返回：

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

示例：

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

5. 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": "组件的使用场景描述"
    }
  ]
}

组件文件结构

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

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. 组件结构: 推荐按照标准目录结构组织组件文件，以获得最佳体验

plugin注册说明

1. 插件目录结构

将插件文件夹放在 src/plugins/ 目录下，每个插件应包含以下结构：

src/plugins/YourPlugin/
├── index.ts              # 插件入口文件，导出 registerPlugin 方法
├── tools/               # 工具函数目录
│   ├── index.ts         # 工具注册入口
│   ├── tool1.ts         # 具体工具实现
│   └── tool2.ts         # 具体工具实现
├── utils/               # 工具函数
├── examples/            # 示例代码
└── know/               # 知识库文件

2. 插件入口文件 (index.ts)

插件的 index.ts 文件必须导出 registerPlugin 方法：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import registerTools from "./tools/index.js";
import { registerPluginDesc } from "../../pluginUtils/registerPluginDesc.js";

async function registerPlugin(server: McpServer) {
  // 注册插件描述，会注入到组件的描述中
  registerPluginDesc(
    "YourPlugin",
    `YourPlugin可用工具介绍：
    1. your-tool-1：工具1的描述
    2. your-tool-2：工具2的描述
    `
  );
  
  // 注册插件工具
  return registerTools(server);
}

export default registerPlugin;

3. 工具注册 (tools/index.ts)

在 tools/index.ts 中注册所有工具：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import yourTool1 from './your-tool-1.js';
import yourTool2 from './your-tool-2.js';

export default function registryTools(server: McpServer) {
  [yourTool1, yourTool2].forEach((registryFn) => {
    registryFn(server);
  });
}

4. 具体工具实现

每个工具文件应按以下模式实现：

import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const registryTool = (server: McpServer) => {
  server.tool(
    "your_tool_name",           // 工具名称
    "工具描述和使用说明",        // 工具描述
    {
      // Zod schema 定义参数
      param1: z.string().describe("参数1描述"),
      param2: z.number().describe("参数2描述"),
    },
    async ({ param1, param2 }) => {
      // 工具逻辑实现
      const result = processYourLogic(param1, param2);
      
      return {
        content: [
          {
            type: "text",
            description: "返回结果描述",
            text: result,
          },
        ],
      };
    }
  );
};

export default registryTool;

5. 插件描述注册

使用 registerPluginDesc 方法注册插件描述：

• pluginName: 插件名称，应与插件文件夹名称一致
• description: 插件描述，会注入到组件描述中，帮助大模型在合适时机调用对应工具

6. 自动加载机制

服务器启动时会自动扫描 src/plugins/ 目录下的所有插件文件夹，并调用每个插件的 registerPlugin 方法进行注册。

7. 最佳实践

• 工具名称使用下划线命名法 (snake_case)
• 提供详细的工具描述和参数说明
• 使用 Zod 进行参数验证
• 返回结构化的结果数据
• 在插件描述中清晰说明工具的适用场景

许可证

MIT License