npm package: @fineorg/mcp
Description: MCP Server for platform integrations (Bitbucket, Jira, Confluence, Feishu)
Latest version: 1.0.0

# @fineorg/mcp

[![CI](https://github.com/congqiu/fine-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/congqiu/fine-mcp/actions/workflows/ci.yml)
[![npm @fineorg/mcp package](https://img.shields.io/npm/v/@fineorg/mcp.svg)](https://npmjs.org/package/@fineorg/mcp)

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

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

## 功能特性

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

## 快速开始

### 标准配置

```json
{
  "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` 中填写你需要的平台凭证，仅配置了凭证的平台会被启用。完整变量列表见 [平台配置](#平台配置)。

<details>
  <summary>Claude Code</summary>

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

```bash
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
```

</details>

<details>
  <summary>Cursor</summary>

**点击安装：**

[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=%40fineorg%2Fmcp&config=eyJjb21tYW5kIjoibnB4IC15IEBmaW5lb3JnL21jcEBsYXRlc3QifQ%3D%3D)

**或手动安装：**

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

</details>

<details>
  <summary>Gemini CLI</summary>

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

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

</details>

<details>
  <summary>VS Code</summary>

按照 [VS Code MCP 安装指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) 使用上方标准配置。

</details>

## 可用工具

### 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 客户端直接通过进程通信调用。适用于本地开发，无需额外配置。

```bash
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 部署（推荐）

```bash
# 配置环境变量
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 命令：

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

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

#### 本地运行

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

#### 端点说明

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

#### 测试连接

```bash
# 健康检查
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，仅用于向后兼容：

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

## 本地开发

```bash
# 安装依赖
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 时自动触发：

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

```bash
# 手动发布流程（仅供参考）
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