phinix_experience MCP 服务器

phinix_experience 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 模型提供项目开发经验检索功能，帮助开发者在编码前查阅相关踩坑经验，避免重复犯错。

功能特性

🔍 通过语义检索有关的项目开发经验 (search_experience_list)

• 根据自然语言描述检索项目开发经验库
• 入参 queries 为检索问题列表，结果以 query 为唯一标识返回数组
• 每项返回匹配的经验数组（含 id 与 text 概述）

📄 通过经验 ID 查询经验详情 (search_experience_detail)

• 根据经验 ID 获取完整详情
• 入参 ids 为经验 ID 列表，结果以 id 为唯一标识返回数组
• 返回详细的问题描述、解决方案和注意事项

安装和使用

环境要求

• Node.js 18+
• npm 或 yarn

安装依赖

npm install

环境变量

| 变量名 | 必需 | 说明 | | -------- | ---- | ------------------------- | | APP_ID | 是 | RAG 应用 ID，用于经验检索 |

启动服务器

npm start

在 IDE 中配置 MCP

{
  "mcpServers": {
    "phinix_experience": {
      "command": "npx",
      // 线上
      "args": ["phinix_experience"],
      // 本地测试
      // "args": ["tsx", "/Users/wenmu/project/ai_experience/src/index.js"],
      "env": {
        "APP_ID": "dataphin"
      }
    },
  }
}

MCP 工具说明

1. search_experience_list

通过语义检索有关的项目开发经验。

参数：

| 参数 | 类型 | 必需 | 说明 | | --------- | -------- | ---- | --------------------------------- | | queries | string[] | 是 | 检索问题列表，每个问题用自然语言描述 |

每个 query 写成自然语言短句，结构为 适用范围/对象 + 当前操作或触发场景 + 已知问题/约束/异常，一个 query 只说一个操作、风险或异常。

返回：

JSON 数组，每项以 query 作为唯一标识：

• query: 本项对应的查询词
• nodes: 匹配的经验数组（含 id 与 text 概述）
• message: 无命中时的说明
• error: 该 query 检索失败的原因（其他 query 不受影响）

示例：

{ "queries": ["AutoTable 配置批量操作时 batchAction 的使用限制", "dataphin-gts-mdc 使用 JUnit5 时 mvn test 未执行用例"] }

2. search_experience_detail

通过经验 ID 查询经验详情。

参数：

| 参数 | 类型 | 必需 | 说明 | | ----- | -------- | ---- | ---------------- | | ids | number[] | 是 | 经验 ID 列表 |

单个 ID 也需传只有一项的数组，不支持 id 单值写法。

返回：

JSON 数组，每项以 id 作为唯一标识：

• id: 本项对应的经验 ID
• detail: 经验完整详情；获取失败或不存在时为 null
• message: 经验不存在时的说明
• error: 该 id 获取失败的原因（其他 id 不受影响）

示例：

{ "ids": [123, 456] }

推荐使用流程

search_experience_list(queries=["...", "..."]) → 获取经验列表 → search_experience_detail(ids=[123, 456]) → 批量获取详情

项目结构

src/
├── index.js                # 入口文件
├── server.js               # MCP 服务器核心，注册工具
└── tools/
    ├── index.js            # 工具导出入口
    └── searchExperience.js # 经验检索工具实现

技术栈

• MCP SDK: @modelcontextprotocol/sdk
• Schema 验证: Zod
• Transport: STDIO（标准输入输出）
• 运行时: tsx

开发

# 开发模式（监听文件变化自动重启）
npm run dev

# 使用 MCP Inspector 调试
npm run serve

许可证

MIT License