@fineorg/mcp

@fineorg/mcp

MCP (Model Context Protocol) 服务器，为 AI 编程工具提供 Bitbucket、Jira、Confluence 和飞书平台集成。

通过 MCP 客户端（如 Claude Code、Cursor、Gemini CLI）调用工具，获取这些平台的数据。

功能特性

• Bitbucket 集成: 获取 PR 详情、Diff
• Jira 集成: 获取任务详情
• Confluence 集成: 获取页面内容、子页面列表、页面评论
• 飞书开放平台集成: 获取文档内容和评论、创建和更新云文档
• 飞书项目集成: 获取工作项详情
• 按需启用: 仅配置凭证的平台会被注册，无需全部配置

快速开始

标准配置

{
  "mcpServers": {
    "fine-mcp": {
      "command": "npx",
      "args": ["-y", "@fineorg/mcp@latest"],
      "env": {
        "JIRA_HOST": "https://jira.example.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_TOKEN": "your-token"
      }
    }
  }
}

env 中填写你需要的平台凭证，仅配置了凭证的平台会被启用。完整变量列表见 平台配置。

Claude Code

使用 Claude Code CLI 添加 MCP 服务器：

claude mcp add fine-mcp \
  -e JIRA_HOST=https://jira.example.com \
  -e JIRA_USERNAME=your-username \
  -e JIRA_TOKEN=your-token \
  -- npx -y @fineorg/mcp@latest

Cursor

点击安装：

或手动安装：

进入 Cursor Settings → MCP → New MCP Server，使用上方配置。

Gemini CLI

# 项目级别
gemini mcp add fine-mcp npx @fineorg/mcp@latest

# 全局
gemini mcp add -s user fine-mcp npx @fineorg/mcp@latest

VS Code

按照 VS Code MCP 安装指南 使用上方标准配置。

可用工具

Bitbucket

工具名称	描述	所需配置
get_pull_request	获取 PR 详情	BITBUCKET_HOST + 认证
get_diff	获取 PR Diff	BITBUCKET_HOST + 认证

Jira

工具名称	描述	所需配置
get_jira_issue	获取 Jira 任务	JIRA_HOST + 认证

Confluence

工具名称	描述	所需配置
get_confluence_page	获取 Confluence 页面	CONFLUENCE_HOST + CONFLUENCE_TOKEN
get_confluence_child_pages	获取子页面列表	CONFLUENCE_HOST + CONFLUENCE_TOKEN
get_confluence_page_comments	获取页面评论	CONFLUENCE_HOST + CONFLUENCE_TOKEN

飞书开放平台

工具名称	描述	所需配置
get_feishu_document	获取文档内容和评论	FEISHU_OPEN_APP_ID + FEISHU_OPEN_APP_SECRET
create_feishu_document	创建云文档	FEISHU_OPEN_APP_ID + FEISHU_OPEN_APP_SECRET
update_feishu_document	更新云文档内容	FEISHU_OPEN_APP_ID + FEISHU_OPEN_APP_SECRET

飞书项目

工具名称	描述	所需配置
get_feishu_work_item	获取飞书项目工作项	FEISHU_PROJECT_KEY + 插件认证

平台配置

通过环境变量配置各平台凭证，仅配置了凭证的平台会被启用。

Bitbucket

环境变量	描述
BITBUCKET_HOST	Bitbucket 服务器地址
BITBUCKET_TOKEN	API Token（Bearer Token 认证）
BITBUCKET_USERNAME	用户名（Basic Auth，与密码配合使用）
BITBUCKET_PASSWORD	密码（Basic Auth，与用户名配合使用）

Token 和 Username/Password 二选一，优先使用 Token。

Jira

环境变量	描述
JIRA_HOST	Jira 服务器地址
JIRA_USERNAME	用户名
JIRA_TOKEN	API Token

Confluence

环境变量	描述
CONFLUENCE_HOST	Confluence 服务器地址
CONFLUENCE_TOKEN	个人访问令牌（PAT，Bearer Token 认证）

飞书开放平台

环境变量	描述
FEISHU_OPEN_APP_ID	自建应用 App ID
FEISHU_OPEN_APP_SECRET	自建应用 App Secret

需在飞书开放平台为自建应用开通以下权限（均为高级权限，需管理员审批）：

• docx:document:readonly（查看新版文档）— 读取文档内容时必需
• docx:document（创建及编辑新版文档）— 创建/更新文档时必需
• wiki:wiki:readonly（查看知识库）— 读取 Wiki 页面时必需
• docs:document.comment:read（读取文档评论）— 读取文档评论时必需（可选）

飞书项目

环境变量	描述
FEISHU_PROJECT_KEY	飞书项目 Key
FEISHU_PROJECT_PLUGIN_ID	插件 ID
FEISHU_PROJECT_PLUGIN_SECRET	插件密钥
FEISHU_PROJECT_USE_VIRTUAL_TOKEN	使用虚拟 Token（默认 false）
FEISHU_PROJECT_USER_KEY	用户 Key（虚拟 Token 时必须）

认证配置

MCP 服务器支持可选的 Token 认证，主要用于 HTTP 模式远程部署。Stdio 模式通过进程隔离保证安全，通常无需启用。

环境变量	描述	默认值
MCP_AUTH_ENABLED	是否启用认证	true
MCP_AUTH_TOKEN	认证令牌（使用 openssl rand -hex 32 生成）	—
MCP_ALLOWED_CLIENTS	允许的客户端名称，逗号分隔	—

当认证启用时，工具调用需要提供 authToken 参数。本地 Stdio 模式可设置 MCP_AUTH_ENABLED=false 禁用。

传输模式

支持三种传输模式：Stdio（默认）、HTTP（推荐远程部署）、SSE（已弃用）。

Stdio（默认）

标准输入输出模式，MCP 客户端直接通过进程通信调用。适用于本地开发，无需额外配置。

npx -y @fineorg/mcp@latest

HTTP（推荐远程部署）

HTTP 传输模式，适用于远程连接场景。

环境变量	描述	默认值
MCP_HTTP_PORT	HTTP 服务端口	3040
MCP_HTTP_HOST	监听地址	127.0.0.1
MCP_TRUST_PROXY	信任反向代理（从 X-Forwarded-For 获取真实 IP）	false
MCP_RATE_LIMIT_WINDOW	速率限制窗口（毫秒）	60000
MCP_RATE_LIMIT_MAX	窗口内最大请求数	60

Docker 部署（推荐）

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置各平台的认证信息

# 使用 Docker Compose 启动
docker compose up -d fine-mcp-http

# 查看日志
docker compose logs -f fine-mcp-http

# 停止服务
docker compose down

也可以直接使用 Docker 命令：

# 构建镜像
docker build -t fine-mcp .

# 运行容器
docker run -d \
  --name fine-mcp-http \
  -p 3040:3040 \
  --env-file .env \
  fine-mcp

本地运行

bun run dev:http
# 或生产模式
bun run build && bun run start:http

端点说明

端点	方法	描述
/mcp	POST	MCP 协议端点（JSON-RPC 请求）
/mcp	GET	SSE 消息流（需已有会话）
/mcp	DELETE	关闭会话
/health	GET	健康检查

测试连接

# 健康检查
curl http://localhost:3040/health

# 初始化会话
curl -X POST http://localhost:3040/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}},"id":1}'

SSE（已弃用）

SSE 传输已弃用，请使用 HTTP 传输模式替代。

SSE 模式默认运行在端口 3041，仅用于向后兼容：

bun run dev:sse      # 开发模式
bun run start:sse    # 生产模式

本地开发

# 安装依赖
bun install

# 配置环境
cp .env.example .env

# 开发模式（热重载）
bun run dev          # Stdio
bun run dev:http     # HTTP（推荐）

# 测试与 Lint
bun run test:run     # 运行测试
bun run test:coverage # 测试覆盖率
bun run lint         # ESLint 检查
bun run type-check   # TypeScript 类型检查

发布

项目通过 CI/CD 自动发布。推送 v* tag 时自动触发：

• CI 检查（lint → type-check → test → build）
• 发布到 npm（使用 OIDC Trusted Publishing + provenance 签名）
• 创建 GitHub Release（从 CHANGELOG.md 提取版本说明）

# 手动发布流程（仅供参考）
bun run build
npm publish --dry-run  # 预览发布内容
npm publish --access public --provenance

项目结构

src/
├── index.ts              # MCP 服务器入口（Stdio）
├── index-http.ts         # HTTP 传输入口
├── index-sse.ts          # SSE 传输入口（已弃用）
├── mcp/
│   ├── mcpAuth.ts        # 认证模块
│   ├── server-factory.ts # MCP 服务器工厂
│   └── startup.ts        # 启动和关闭共享逻辑
├── services/
│   ├── mcpService.ts     # MCP 服务层
│   └── platforms/        # 平台客户端
│       ├── BasePlatformClient.ts
│       ├── BitbucketClient.ts
│       ├── ConfluenceClient.ts
│       ├── FeishuClient.ts      # 飞书项目（插件 API）
│       ├── FeishuOpenClient.ts   # 飞书开放平台（官方 SDK）
│       └── JiraClient.ts
├── utils/
│   └── logger.ts         # 日志工具（自动脱敏）
├── config/
│   └── index.ts          # 配置管理（Zod 校验）
└── types/
    ├── feishu.ts         # 飞书项目 API 类型
    ├── result.ts         # Result 类型定义
    └── schemas.ts        # MCP 工具输出 Schema（SSoT）

许可证

MIT