✨ Plane.so MCP 服务器 ✨

<!-- Replace YOUR_PACKAGE_NAME if published --> <!-- Replace YOUR_PACKAGE_NAME if published -->

一个 模型上下文协议 (MCP) 服务器，充当 Plane.so API 的桥梁。🚀

此服务器允许 MCP 客户端（如 AI 助手或其他工具）通过定义的工具与 Plane.so 资源（最初是 Issues）进行交互。

📚 目录

• 面向用户
  • 可用工具
  • 先决条件
  • 安装
  • 配置
  • 使用
  • 示例
  • 安全注意事项
• 面向开发者
  • 开发
  • 项目结构
  • 验证和错误处理
  • 添加新工具
  • 测试
  • 代码检查和格式化
  • 贡献
  • 行为准则
• 许可证

👤 面向用户

本节为希望安装和运行 Plane.so MCP 服务器以将其与 MCP 客户端（例如，Cursor、Claude App）连接的用户提供信息。

⭐ 可用工具

服务器公开以下工具以与 Plane.so API 交互。 工具名称使用下划线（例如，plane_get_issue）。

plane_get_issue

检索特定 issue 的详细信息。

参数：

• project_id (字符串，必需): 包含 issue 的项目的 ID。
• issue_id (字符串，必需): 要检索的 issue 的 ID。

示例：

{
  "project_id": "your_project_id_here",
  "issue_id": "your_issue_id_here"
}

plane_create_issue

在指定的项目中创建一个新的 issue。

参数：

• project_id (字符串，必需): 应在其中创建 issue 的项目的 ID。
• name (字符串，必需): issue 的标题。
• description_html (字符串，可选): issue 的 HTML 描述（Plane API 通常需要此格式）。
• priority (字符串，可选): issue 的优先级（“urgent”、“high”、“medium”、“low”、“none”）。
• state_id (字符串，可选): 此 issue 的状态 ID。
• assignees (字符串数组，可选): 要分配给此 issue 的用户 ID 数组。

示例：

{
  "project_id": "your_project_id_here",
  "name": "New Feature Request",
  "description_html": "<p>Details about the new feature.</p>",
  "priority": "medium"
}

plane_update_issue

更新项目中现有的 issue。

参数：

• project_id (字符串，必需): 包含 issue 的项目的 ID。
• issue_id (字符串，必需): 要更新的 issue 的 ID。
• name (字符串，可选): issue 的更新标题。
• description_html (字符串，可选): issue 的更新 HTML 描述。
• priority (字符串，可选): issue 的更新优先级。
• state_id (字符串，可选): issue 的更新状态 ID。
• assignees (字符串数组，可选): 分配给此 issue 的更新用户 ID 数组。

示例：

{
  "project_id": "your_project_id_here",
  "issue_id": "your_issue_id_here",
  "priority": "high",
  "assignees": ["user_id_1"]
}

✅ 先决条件

• Node.js (建议 v20 或更高版本)
• npm
• 一个 Plane.so 帐户和一个 API 密钥 -> 工作区图标（左上角）-> 设置 -> API 令牌 -> 添加 API 令牌
• Plane.so 工作区 slug -> https://app.plane.so/{workspace_slug}/ (将 {workspace_slug} 替换为您的实际工作区 slug)

🛠️ 安装

npm install

🚀 使用

服务器将启动并侦听其标准输入 (stdin) 上的请求，并将响应发送到其标准输出 (stdout)。 您需要配置您的 MCP 客户端（如 Cursor、Claude App 等）以在需要时启动此服务器进程。

有关模型上下文协议的更多详细信息，请访问 modelcontextprotocol.io。

✨ 示例

以下是一些您可以提供给 AI 助手的示例提示（一旦在其中配置了服务器）：

• “获取 WebApp 项目中 issue BUG-123 的详细信息。”
• “在 API 项目中创建一个新的高优先级 issue，标题为 '重构身份验证模块'，描述为 '需要更新 auth 库'。”
• “更新 Design 项目中的 issue FEAT-45 并将其分配给 user_abc。”

您的助手将使用适当的工具（plane_get_issue、plane_create_issue、plane_update_issue），并且可能会在进行更改之前要求您确认。

🛡️ 安全注意事项

• API 密钥安全： 存储在 .env 文件中的 PLANE_API_KEY 授予对您的 Plane.so 工作区的访问权限。 确保此文件安全，并且永远不要将其提交到版本控制。
• 权限： 确保使用的 API 密钥在 Plane.so 中具有执行工具所需操作的必要权限（例如，读取 issue、创建 issue、更新 issue）。
• 用户批准： 大多数 MCP 客户端在执行修改数据的操作（如创建或更新 issue）之前，都需要您的明确批准，从而提供安全层。

---

🧑‍💻 面向开发者

本节适用于希望为项目做出贡献、运行测试或使用开发环境的开发人员。

开发 🧑‍💻

npm run dev

项目结构 📂

该项目遵循领域驱动的组织结构：

src/
├── configs/         # 环境和配置
├── plane-client.js  # API 客户端包装器
├── schemas/         # Zod 验证模式
│   ├── tools.schema.ts    # 通用工具模式和实用程序
│   ├── project.schema.ts  # 项目特定模式
│   └── issue.schema.ts    # Issue 特定模式
├── services/        # API 交互的服务层
│   ├── project.service.ts
│   └── issue.service.ts
├── tools/           # MCP 工具定义和处理程序
│   ├── index.ts           # 工具注册
│   ├── project.tools.ts   # 项目工具定义
│   └── issue.tools.ts     # Issue 工具定义
└── types/           # TypeScript 类型定义

验证和错误处理 ✅

该项目使用 Zod 进行全面验证：

1. 模式定义：特定于域的模式在 src/schemas/ 中定义
2. 模式验证：validateWithSchema 实用程序确保一致的验证
3. 错误处理：用于结构化错误报告的自定义 ValidationError 类

使用验证的示例：

// 在服务方法中
const validData = validateWithSchema(MySchema, inputData);
// validData 现在已正确键入和验证

添加新工具 🔧

要添加新工具：

1. 在适当的域文件中定义工具接口（例如，src/tools/issue.tools.ts）
2. 在域模式文件中添加验证模式（例如，src/schemas/issue.schema.ts）
3. 在服务文件中实现服务方法（例如，src/services/issue.service.ts）
4. 在 src/tools/index.ts 中注册该工具

测试 🧪

该项目包括多种类型的测试：

单元测试

运行单元测试（快速，无 API 调用）：

npm run test:unit

集成测试

这些测试会进行真实的 API 调用，因此需要 API 凭据：

1. 创建一个包含以下内容的 .env.test 文件：

API_KEY=your_plane_api_key
WORKSPACE_SLUG=your_workspace_slug

2. 运行集成测试：

npm run test:local

3. 快速端点检查：

npm run check:local

预提交钩子

预提交钩子仅运行代码检查和格式化，不运行测试。 这确保：

• 更快的提交
• 开发期间无需 API 调用
• 常规开发期间无需 API 凭据

当您想手动运行测试时：

# 仅单元测试
npm run test:unit

# 包括集成的所有测试（需要 API 凭据）
npm test

代码检查和格式化 ✨

使用 Biome 检查代码检查和格式化错误：

npm run lint
npm run format:check

自动应用格式化和代码检查修复：

npm run format

（注意：格式化也会通过 Husky 和 lint-staged 在提交时自动应用！）

🙌 贡献

欢迎贡献！ 请参阅 CONTRIBUTING.md 了解有关如何贡献、报告错误或建议功能的详细信息。

🤝 行为准则

我们致力于提供一个热情和包容的环境。 请查看我们的 CODE_OF_CONDUCT.md。

---

📜 许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。