@fineorg/mcp 1.0.0

package/README.md

@@ -0,0 +1,354 @@
+# @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

package/dist/index-http.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node