@fineorg/mcp

v1.0.0

Published

2 months ago

MCP Server for platform integrations (Bitbucket, Jira, Confluence, Feishu)

0High
0Medium
0Low

frankqcc

mcp model-context-protocol bitbucket jira confluence feishu

@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 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 Settings → MCP → New MCP Server，使用上方配置。

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

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

按照 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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@fineorg/mcp

功能特性

快速开始

标准配置

可用工具

Bitbucket

Jira

Confluence

飞书开放平台

飞书项目

平台配置

Bitbucket

Jira

Confluence

飞书开放平台

飞书项目

认证配置

传输模式

Stdio（默认）

HTTP（推荐远程部署）

Docker 部署（推荐）

本地运行

端点说明

测试连接

SSE（已弃用）

本地开发

发布

项目结构

许可证