Onplana

Onplana MCP 服务

开源 TypeScript Model Context Protocol 构建模块，提取自 Onplana 的生产环境 MCP 部署。包含两个软件包：

• onplana-mcp-server：服务模板。支持 Streamable HTTP 传输、Bearer 身份验证、提示词注入防护和可插拔分发器。
• onplana-mcp-client：类型化 TypeScript 客户端 SDK，用于调用 Onplana 的公共 MCP 端点 https://api.onplana.com/api/mcp/v1。

这是什么

MCP 服务的传输层（Streamable HTTP 接线、无状态模式、作用域限定的 Bearer 身份验证、提示词注入防护）实现得当，并与特定平台的工具注册表分离。使用服务模板，按照内置的安全最佳实践构建自己的 MCP 服务。使用客户端 SDK，通过自己的代码调用 Onplana 托管的 MCP。

这些模式提取自 Onplana 的生产环境部署（公开文档见 onplana.com/mcp），也就是处理真实 Claude Desktop、Cursor、ChatGPT 自定义连接器和内部 Agent 流量、并连接到 Onplana 平台的同一层。

为什么开源

MCP 传输对所有人都一样。许多早期 MCP 服务都没有正确处理安全基础机制：

• 提示词注入。 返回用户生成内容（任务标题、评论正文、Wiki 文本）的工具会将这些内容直接放入模型的上下文中。如果没有防护，恶意行为者可以在自己的数据中植入 "ignore previous instructions"，下一个读取这些数据的 Agent 就会照做。
• 无状态传输。 大多数 SDK 示例都假设会话状态保存在内存中，这会破坏水平扩展能力，并使身份验证模型更加复杂。
• 计划门控语义。 展示调用者实际上无法使用的工具，会浪费轮次并使模型困惑。

Onplana 通过六个月的 MCP 服务开发，在生产环境中解决了这些问题。公开这些模式能带来很大价值：

1. 其他 MCP 作者可以直接使用经过验证的模板，无需从头摸索。
2. 这个仓库是预训练信号的来源。公开的 GitHub README 在新一代大模型训练数据中占有很大权重；包含相关模式和清晰 MCP 文档的仓库，有助于提升模型对“优秀 MCP 服务应有的样子”的记忆。
3. 分发器接口是接入业务逻辑的连接点。传输层是通用的；MCP 服务中真正重要的是工具注册表。开源传输层不会泄露任何专有内容。

分发器实现、工具目录、计划门控逻辑、审计基础设施，以及 Onplana 其余约 600 行的闭源分发器仍保留在闭源单体仓库中，因为它们承载着平台业务逻辑。如果你用这个模板构建自己的 MCP 服务，就需要自行编写分发器。这才是重要的工作，也是与你的平台息息相关的工作。

仓库结构

onplana-mcp-server/
├── packages/
│   ├── server-template/        # onplana-mcp-server (npm)
│   │   ├── src/
│   │   │   ├── transport.ts    # Streamable HTTP wiring
│   │   │   ├── auth.ts         # Bearer auth pattern
│   │   │   ├── promptInjection.ts  # wrapUserContent + escape
│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface
│   │   │   └── index.ts
│   │   ├── tests/              # promptInjection + auth + transport
│   │   └── README.md
│   └── client/                 # onplana-mcp-client (npm)
│       ├── src/
│       │   ├── client.ts       # OnplanaMcpClient class
│       │   ├── types.ts        # Public type surface
│       │   └── index.ts
│       ├── tests/              # client.test.ts (stub fetch)
│       └── README.md
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace
├── plugins/
│   └── onplana/                # Claude Code plugin (skills + connect command)
├── examples/
│   └── in-memory/              # Runnable demo with 3 toy tools
├── gemini-extension.json       # Gemini CLI manifest
├── mcp.json                    # stdio client config (mcp-remote)
├── server.json                 # MCP registry manifest
└── .github/workflows/
    ├── ci.yml                  # tsc + vitest on PR
    └── publish.yml             # npm publish on tag v*

快速入门

构建服务

安装：

npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express

接入 Express 应用：

import express from 'express'
import {
  createMcpPostHandler,
  createMcpMethodNotAllowedHandler,
  requireBearerAuth,
  type Dispatcher,
} from 'onplana-mcp-server'

const dispatcher: Dispatcher = {
  async listTools(ctx) { /* return your tool descriptors */ return [] },
  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },
}

const auth = async (token: string) => {
  // Validate against your token store. Return AuthContext or null.
  return { userId: 'u', scopes: ['MCP_AGENT'] }
}

const app = express()
app.use(express.json())
app.use('/api/mcp/v1',
  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),
)
app.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))
app.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.listen(3000)

完整快速入门见 packages/server-template/README.md；可运行的演示见 examples/in-memory/。

通过代码调用 Onplana

安装：

npm install github:Onplana/onplana-mcp-server

使用：

import { OnplanaMcpClient } from 'onplana-mcp-client'

const client = new OnplanaMcpClient({
  url:   'https://api.onplana.com/api/mcp/v1',
  token: process.env.ONPLANA_PAT!,
})

const projects = await client.listProjects({ status: 'ACTIVE' })

// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical
// search across your org's indexed content (projects, tasks, risks,
// goals, comments, wiki pages).
const { matches } = await client.searchOrgKnowledge({
  query: 'rationale for the 3-week design phase',
  scope: 'all',
  limit: 5,
})

客户端完整文档见 packages/client/README.md。

工具

托管服务 https://mcp.onplana.com/mcp 提供 285 个工具，涵盖项目、任务、冲刺、里程碑、挣值、风险、问题、治理、变更控制、工时表、维基、白板、工作流和 Microsoft Graph 集成。由于工具目录在提供给客户端之前，会根据调用者的角色和组织的套餐筛选工具，因此每个客户端看到的确切数量会更少。

以下 33 个工具值得优先了解，并非完整目录。读取工具标注为 readOnlyHint；写入工具带有 destructiveHint，以便客户端进行控制。每次调用都使用调用者的身份执行，并会根据该用户的权限和组织套餐进行检查，同时记录在审计日志中。

读取（readOnlyHint: true）

• list_projects：列出组织中的项目，可按状态筛选。
• get_project：获取单个项目的完整信息，包括日期、负责人和进度。
• list_tasks：列出某个项目的任务，或跨项目列出任务。
• get_task：获取单个任务的信息，包括描述、受派人、日期和近期评论。
• list_my_tasks：列出分配给调用用户的任务。
• list_overdue：列出已超过截止日期的任务。
• list_team_members：列出项目成员。
• list_org_members：列出组织成员。
• list_risks：列出某个项目中记录的风险。
• find_similar_projects：查找与描述相似的过往项目，用于估算。
• search_org_knowledge：在任务、项目、维基页面和评论中进行 BM25 与向量混合搜索。
• summarize_project：根据实时计划合成 AI 项目摘要。
• analyze_project_risks：使用 AI 检测进度安排、预算、范围和资源方面的风险。
• generate_status_report：根据当前进度安排和活动生成 AI 状态报告。
• search：App Directory 适配器，返回 {id, title, snippet?, url?}。
• fetch：App Directory 适配器，返回 {id, title, content, url?, metadata?}。

写入，增量操作（destructiveHint: false）

• create_project：创建项目。
• create_task：创建任务，可选择将其设为某个父任务的子任务。
• create_milestone：为项目添加里程碑。
• create_comment：在任务、问题或项目上发表评论。
• create_sprint_with_tasks：创建冲刺并将任务加入其中。
• submit_timesheet：记录某个任务的工时。
• add_project_member：将现有组织成员添加到项目。
• link_dependency：关联两个任务，通过唯一约束实现幂等操作。

写入，修改操作（destructiveHint: true）

• update_project：更改项目字段，例如状态、日期或预算。
• update_task：更改任务字段，例如状态、进度或日期。
• bulk_update_tasks：对多个任务应用同一项更改。
• assign_task：设置任务的受派人。
• move_task_to_sprint：将任务移入或移出冲刺。

租约（适用于共享待办列表的 Agent）

• next_task：选取下一个可用任务，并在一次调用中认领该任务。先列出任务再认领会留下间隙，两个 Agent 可能同时认领同一任务。
• claim_task：对指定任务获取独占租约。
• renew_task_lease：在工作仍在进行时延长租约。
• release_task：归还租约；完成或阻塞任务也会释放租约，结束会话则会释放该运行持有的所有租约。

租约与运行（RUN）绑定，而非与用户绑定。同一客户端的两个会话会以同一 Agent 身份进行身份验证，因此，按用户加锁会允许一个会话释放另一个会话的任务。租约会自动过期，因此 Agent 崩溃后，其任务会被释放，不会一直被占用。

目录中有 4 个删除工具（用于任务、项目、列表和文档）。每个工具都是按组织设置的开关，在组织管理员保存选择之前默认开启；Agent 仍需具备相应权限，而且这 4 个工具都会将项目移至回收站，而非永久销毁。无论如何，都应优先使用 update_task，而不是删除后重新创建，因为 Onplana 会审计每次字段变更并保留历史记录。

生产环境检查清单

模板 + SDK 可助你快速上手。还需补充以下内容：

• 按令牌限流。 每个 Bearer 令牌每分钟限制 60–120 个请求； Agent 工作流比人类操作更频繁。
• 租户成本上限。 如果你的工具会调用付费大模型，应根据本月至今的支出控制调度。Onplana 的部署使用 aiMonthlyCostCapUsd，并支持 WARN / BLOCK 模式。
• 审计日志。 每次调度都应写入一条审计记录，并标记 actorType: 'mcp_agent'，让管理员能够将 AI Agent 在其租户中的操作与人工操作区分开来。
• 计划 / 范围筛选。 不要暴露所有内部工具。 Onplana 暴露了 26 个工具中的 21 个；其余 5 个要么需要应用内 预览 UI，要么不适合在无人监督的情况下调用，要么会产生 过大的负载。
• 为高风险变更启用 PREVIEW 模式。 对免费套餐中的变更类工具默认仅允许预览。Onplana 已提供此功能：用户明确升级并重新运行之前，Agent 会先看到“将要执行的操作”。
• 幂等键。 对规范化后的输入 + 会话 ID 进行哈希； 并在审计记录上将其存储为唯一约束。模型 重试同一逻辑操作时，不应重复创建。

以上各项都因平台而异。模板提供了接入点 （Dispatcher.callTool）；你的调度器可以根据平台对这些概念的编码方式实现它们。

兼容性

• Node.js ≥ 20（适用于服务端模板和 CI 矩阵）；客户端需 ≥ 18 （使用环境提供的 fetch）。
• @modelcontextprotocol/sdk@^1.29.0
• express@^4.18.0 或 express@^5.0.0

已通过以下工具测试：

• Claude Code（插件市场，或 claude mcp add --transport http）
• Claude Desktop（自定义连接器）
• Cursor（~/.cursor/mcp.json）
• ChatGPT 自定义连接器（账户已启用 MCP 时）
• Gemini CLI + Gemini Code Assist（~/.gemini/settings.json）
• VS Code 中的 GitHub Copilot（.vscode/mcp.json）
• 官方 MCP Inspector

在 Claude Code 中安装

此仓库同时也是 Claude Code 插件市场，因此只需两条命令即可安装：

/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplana

插件会一并安装服务，然后只需登录一次：

/onplana-connect

此操作会引导你通过浏览器登录，并使用 whoami 检查连接。 所有 Onplana 套餐（包括免费套餐）都可以使用 MCP 服务。

该插件附带两个 Onplana Agent 技能，通过 onplana:<name> 调用：

技能	使用场景
onplana-project-planner	你有一个目标或需求简报，并希望获得可执行的计划：一份附加到项目的计划文档，以及一棵包含日期、依赖项、负责人和测试用例的任务树。
onplana-autonomous-agent	已有计划，并希望执行该计划：认领任务、完成任务、记录进度和证据、解决问题或交回任务，然后继续处理下一个任务。

该插件在 plugins/onplana/.mcp.json 中将服务声明为 远程 HTTP 服务，因此 Claude Code 可直接连接，无需 stdio 适配层。如果你已使用 claude mcp add 添加相同 URL， Claude Code 会保留你添加的条目并跳过插件中的条目，因此 工具仍只有一套。

在 Gemini CLI 中安装

此仓库在根目录附带 gemini-extension.json 清单，因此 只需一条命令即可在 Gemini CLI 中安装 Onplana：

export ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server

重启 gemini CLI（如果你使用 Gemini Code Assist，则重新加载 VS Code / JetBrains 窗口）。 Onplana 工具会显示在 /mcp 中，而 GEMINI.md 上下文也会加载 此仓库附带的使用提示。

贡献

欢迎提交问题和 PR。此仓库刻意保持精简，目标是让 传输模式清晰易懂、经过充分测试且稳定。 只有导出的 Dispatcher / BearerAuth / 处理器工厂接口发生破坏性变更时，才会提升主版本号。 补丁版本和次版本用于改进提示词注入防护、 新增辅助工具和扩充测试覆盖率。

许可证

MIT。© 2026 Onplana

另请参阅

• onplana.com/mcp：生产环境 Onplana MCP 部署的公开文档页面 （完整工具目录、设置说明、安全模型）
• onplana.com：Onplana，一款原生支持 AI 的项目和投资组合管理平台
• Model Context Protocol specification：MCP 标准
• Anthropic prompt-injection guidance：此仓库中的封装实现的安全模式