飞书项目MCP服务
基于Model Context Protocol (MCP)的智能研发流程管理系统，实现端到端的需求管理与开发流程自动化。
功能特点
- 需求读取与完整性分析：从飞书项目系统中提取需求文档，进行深度分析并评估需求完整性
- 需求完善反馈循环：对不完整需求，生成精准的澄清问题清单，并更新需求状态
- 架构设计与技术方案：基于完整需求，生成全面技术方案，包括项目影响分析与架构决策
- 代码实现与质量控制：转入代码实现模式，依据技术方案高质量实现功能
- 自动化代码提交：调用 Gitlab MCP，实现代码自动提交与版本控制
- 任务状态更新与通知：完成后自动更新飞书项目状态并添加PR评论
系统架构
系统采用模块化设计，主要包括以下组件：
- 核心服务器：基于Express实现的HTTP服务器，提供健康检查和MCP工具接口
- 飞书集成器：负责与飞书API交互，获取项目、需求和缺陷信息
- 任务管理器：负责管理系统内部任务，包括创建、查询、更新和删除
- 健康检查器：负责监控系统各组件的健康状态
详细的架构设计请参考设计文档。
快速开始
前置条件
- Node.js 18+
- 飞书项目系统账号和API凭证
安装
# 克隆仓库
git clone https://github.com/yourusername/feishu-project-mcp.git
cd feishu-project-mcp
# 安装依赖
npm install配置
创建.env文件，配置以下环境变量：
# Feishu API Configuration
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
FEISHU_API_URL=https://project.feishu.cn/open_api
# Service Configuration
CHECK_INTERVAL=5000
STORAGE_DIR=./storage
LOG_DIR=./logs
LOG_LEVEL=info
MAX_CONCURRENT_TASKS=5
# Server Configuration
PORT=3000
HOST=localhost运行
# 开发模式
npm run dev
# 生产模式
npm run build
npm start使用npx调用
本项目支持通过npx调用，但目前尚未发布到npm注册表。在发布之前，你可以通过以下方式使用npx调用：
从本地项目调用
在项目目录中运行：
# 先构建项目
npm run build
# 使用npx调用本地包
npx . [参数]或者使用完整路径：
npx /path/to/feishu-project-mcp [参数]传递参数
你可以向npx命令传递参数：
npx . --port 3001 --host 0.0.0.0发布后使用
当项目发布到npm注册表后，你可以直接使用：
npx feishu-project-mcp [参数]并且可以指定版本：
npx feishu-project-mcp@1.0.0 [参数]使用Docker
# 构建镜像
docker build -t feishu-project-mcp .
# 运行容器
docker run -p 3000:3000 --env-file .env feishu-project-mcp在Cline中配置MCP服务
要在Cline的MCP设置文件中配置飞书项目MCP服务，请按照以下步骤操作：
- 打开MCP设置文件：
cline_mcp_settings.json - 在
mcpServers对象中添加一个新条目，如下所示：
"feishu-project-mcp": {
"command": "node",
"args": [
"/path/to/feishu-project-mcp/dist/index.js"
],
"env": {
"FEISHU_APP_ID": "your_app_id",
"FEISHU_APP_SECRET": "your_app_secret",
"FEISHU_API_URL": "https://project.feishu.cn/open_api"
},
"disabled": false,
"alwaysAllow": [
"health",
"health.components",
"health.integrations",
"health.tasks",
"health.memory",
"feishu.projects",
"feishu.requirements",
"feishu.bugs",
"task.create",
"task.get",
"mode.analyze",
"mode.implement"
]
}- 保存文件并重启Cline
使用npx在Cline中配置
当项目发布到npm注册表后，你可以使用npx在Cline中配置MCP服务：
"feishu-project-mcp": {
"command": "npx",
"args": [
"feishu-project-mcp"
],
"env": {
"FEISHU_APP_ID": "your_app_id",
"FEISHU_APP_SECRET": "your_app_secret",
"FEISHU_API_URL": "https://project.feishu.cn/open_api"
},
"disabled": false,
"alwaysAllow": [
"health",
"health.components",
"health.integrations",
"health.tasks",
"health.memory",
"feishu.projects",
"feishu.requirements",
"feishu.bugs",
"task.create",
"task.get",
"mode.analyze",
"mode.implement"
]
}在发布之前，你应该使用完整路径：
"feishu-project-mcp": {
"command": "npx",
"args": [
"/absolute/path/to/feishu-project-mcp"
],
"env": {
"FEISHU_APP_ID": "your_app_id",
"FEISHU_APP_SECRET": "your_app_secret",
"FEISHU_API_URL": "https://project.feishu.cn/open_api"
},
"disabled": false,
"alwaysAllow": [
"health",
"health.components",
"health.integrations",
"health.tasks",
"health.memory",
"feishu.projects",
"feishu.requirements",
"feishu.bugs",
"task.create",
"task.get",
"mode.analyze",
"mode.implement"
]
}发布到npm注册表
要将项目发布到npm注册表，请按照以下步骤操作：
准备工作
- 创建npm账号：如果你还没有npm账号，请先在注册一个账号。
- 登录npm：在本地终端登录npm：
npm login按照提示输入用户名、密码和邮箱。
- 检查package.json：确保package.json文件包含以下必要字段：
{
"name": "feishu-project-mcp",
"version": "1.0.0",
"description": "Feishu Project MCP Service for end-to-end requirement management and development automation",
"type": "module",
"main": "dist/index.js",
"bin": {
"feishu-project-mcp": "dist/cli.js"
},
"files": ["dist", "LICENSE", "README.md"],
"keywords": [
"feishu",
"mcp",
"project-management",
"automation",
"requirements",
"development"
],
"author": "Your Name ",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/yourusername/feishu-project-mcp.git"
},
"bugs": {
"url": "https://github.com/yourusername/feishu-project-mcp/issues"
},
"homepage": "https://github.com/yourusername/feishu-project-mcp#readme"
}- 创建.npmignore文件：创建.npmignore文件，指定不包含在npm包中的文件：
.git
.github
.husky
.vscode
node_modules
src
tests
.editorconfig
.env*
.eslintrc*
.gitignore
.lintstagedrc*
.prettierrc
commitlint.config.cjs
docker-compose*
Dockerfile*
jest.config.cjs
nodemon.json
tsconfig.json手动发布
- 构建项目：
npm run build- 测试包：在发布前，可以使用npm pack命令创建一个tarball，但不实际发布：
npm pack这将创建一个名为feishu-project-mcp-1.0.0.tgz的文件。你可以在另一个目录中安装这个包进行测试：
npm install /path/to/feishu-project-mcp-1.0.0.tgz- 发布包：确认一切正常后，发布包：
npm publish如果是第一次发布，可能需要添加--access=public参数：
npm publish --access=public使用GitHub Actions自动发布
- 创建npm访问令牌：
- 登录npm网站 - 点击右上角的头像，选择"Access Tokens" - 点击"Generate New Token"，选择"Automation"类型 - 复制生成的令牌
- 添加GitHub Secrets：
- 在GitHub仓库页面，点击"Settings" - 点击"Secrets and variables" > "Actions" - 点击"New repository secret" - 添加名为NPM_TOKEN的secret，值为刚才复制的npm令牌
- 创建GitHub Actions工作流：在仓库中创建
.github/workflows/npm-publish.yml文件：
name: Publish to npm
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18.x'
registry-url: 'https://registry.npmjs.org/'
- run: npm ci
- run: npm run build
- run: npm test
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}- 创建GitHub Release：
- 在GitHub仓库页面，点击"Releases" - 点击"Create a new release" - 输入版本号（例如v1.0.0） - 添加发布说明 - 点击"Publish release"
GitHub Actions将自动运行工作流，将包发布到npm。
使用语义化发布
如果你想更进一步自动化发布过程，可以使用semantic-release：
- 安装semantic-release：
npm install --save-dev semantic-release @semantic-release/git @semantic-release/github @semantic-release/npm @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/release-notes-generator- 配置semantic-release：创建
.releaserc.json文件：
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/github",
"@semantic-release/git"
]
}- 创建GitHub Actions工作流：创建
.github/workflows/semantic-release.yml文件：
name: Semantic Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- uses: actions/setup-node@v3
with:
node-version: '18.x'
registry-url: 'https://registry.npmjs.org/'
- run: npm ci
- run: npm run build
- run: npm test
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}版本更新
- 手动更新版本：使用npm version命令更新版本号：
# 补丁版本更新 (1.0.0 -> 1.0.1)
npm version patch
# 次要版本更新 (1.0.0 -> 1.1.0)
npm version minor
# 主要版本更新 (1.0.0 -> 2.0.0)
npm version major然后推送到GitHub并发布：
git push --follow-tags
npm publish- 使用semantic-release自动更新版本：如果你使用semantic-release，只需按照Conventional Commits规范提交代码，semantic-release会自动确定版本号：
- fix: 提交会触发补丁版本更新 - feat: 提交会触发次要版本更新 - 包含BREAKING CHANGE:的提交会触发主要版本更新
发布后的验证
发布成功后，你可以通过以下方式验证：
- 在npm网站上搜索你的包名
- 使用npx安装并运行你的包：
npx feishu-project-mcpAPI文档
HTTP接口
健康检查接口
GET /health返回系统健康状态信息，包括组件状态、集成状态、任务状态和内存使用情况。
MCP工具接口
POST /mcp请求体格式：
{
"tool": "工具名称",
"params": {
"参数1": "值1",
"参数2": "值2"
}
}MCP工具
健康检查工具
- health: 获取完整的健康状态
- health.components: 获取组件健康状态
- health.integrations: 获取集成健康状态
- health.tasks: 获取任务健康状态
- health.memory: 获取内存使用情况
飞书集成工具
- feishu.projects: 获取飞书项目列表
- feishu.requirements: 获取项目需求列表
- feishu.bugs: 获取项目缺陷列表
任务管理工具
- task.create: 创建任务
- task.get: 获取任务详情
模式工具
- mode.analyze: 分析需求或缺陷
- mode.implement: 实现需求或修复缺陷
工作流程示例
需求分析流程
- 获取项目列表：
curl -X POST -H "Content-Type: application/json" -d '{"tool":"feishu.projects"}' http://localhost:3000/mcp- 获取需求列表：
curl -X POST -H "Content-Type: application/json" -d '{"tool":"feishu.requirements","params":{"projectId":"project1"}}' http://localhost:3000/mcp- 分析需求：
curl -X POST -H "Content-Type: application/json" -d '{"tool":"mode.analyze","params":{"itemId":"requirement1","itemType":"requirement"}}' http://localhost:3000/mcp- 获取任务状态：
curl -X POST -H "Content-Type: application/json" -d '{"tool":"task.get","params":{"taskId":"task1"}}' http://localhost:3000/mcp开发指南
提交消息规范
本项目使用Conventional Commits规范来格式化提交消息。每个提交消息都应该遵循以下格式：
():
其中：
- type: 表示提交的类型，如feat、fix、docs等
- scope: （可选）表示提交影响的范围，如core、server等
- subject: 简短描述提交的内容
- body: （可选）详细描述提交的内容
- footer: （可选）包含重大变更或关闭issue的信息
示例：
feat(server): add health check endpoint
Add a new endpoint to check the health of the server and its components.
Closes #123项目中已经配置了commitlint和husky，会在提交前自动检查提交消息是否符合规范。你可以使用.github/commit-template.txt作为提交消息的模板。
代码风格
本项目使用ESLint和Prettier来保持代码风格的一致性。在提交代码前，会自动运行lint-staged来检查和修复代码风格问题。
贡献指南
欢迎贡献代码、报告问题或提出改进建议。请遵循以下步骤：
- Fork仓库
- 创建功能分支：
git checkout -b feature/your-feature - 提交更改：
git commit -am 'feat: add some feature' - 推送到分支：
git push origin feature/your-feature - 提交Pull Request
许可证
本项目采用MIT许可证，详情请参阅LICENSE文件。
联系方式
如有问题或建议，请通过以下方式联系我们：
- 提交Issue
- 发送邮件至：dreambt@gmail.com
提示
在包发布到npm注册表之前，请使用本地路径来调用这个包，而不是尝试从npm注册表安装。这样可以避免出现"package was not found"的警告和连接关闭的错误。