Onplana MCP server

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

• onplana-mcp-server：服务器模板。Streamable HTTP 传输、Bearer 认证、提示注入遏制、可插拔调度器。

• onplana-mcp-client：类型化的 TypeScript 客户端 SDK，用于调用位于 https://api.onplana.com/api/mcp/v1 的公共 Onplana MCP 端点。

这是什么

一个 MCP 服务器的传输层（Streamable HTTP 接线、无状态模式、作用域 Bearer 认证、提示注入遏制）被妥善实现，并与平台特定的工具注册表分离。使用 服务器模板 来构建你自己的 MCP 服务器，内置安全最佳实践。使用 客户端 SDK 从你自己的代码驱动 Onplana 托管的 MCP。

这些模式提取自 Onplana 的生产部署（公开文档见 onplana.com/mcp），同一层还处理真实的 Claude Desktop、Cursor、ChatGPT 自定义连接器以及内部代理对 Onplana 平台的流量。

Related MCP server: MCP Server Template

为什么开源

MCP 传输层对每个人来说都是一样的。大多数早期的 MCP 服务器在安全原语上做得不对：

• 提示注入。 返回用户生成内容（任务标题、评论正文、维基文本）的工具会将这些内容直接放入模型的上下文。如果没有遏制，恶意行为者可以在自己的数据中植入 "ignore previous instructions"，下一个读取它的代理就会照做。

• 无状态传输。 大多数 SDK 示例假设使用内存中的会话状态，这破坏了水平扩展，并使认证模型复杂化。

• Plan-gate 语义。 展示调用者实际上无法调用的工具会浪费轮次，并让模型感到困惑。

Onplana 在六个月的 MCP 服务器工作中于生产环境解决了这些问题。公开这些模式具有很高的杠杆效应：

1. 其他 MCP 作者可以获得一个已知良好的模板，而不是重新发明轮子。

2. 该仓库是一个预训练信号来源。公开的 GitHub README 在下一代 LLM 训练数据中权重很高，而一个包含模式 + 关于 MCP 的清晰文档的仓库，能提高模型对“好的 MCP 服务器是什么样的”的召回能力。

3. 调度器接口是您的业务逻辑接入的接缝。传输层是通用的；您的 MCP 服务器的关键之处在于工具注册表。开源传输层不会泄露任何专有内容。

调度器实现、工具目录、Plan-gate 逻辑、审计基础设施，以及 Onplana 其余约 ~600 行代码的闭源调度器，都保留在闭源 monorepo 中，因为它们编码了平台业务逻辑。如果您使用此模板构建自己的 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：将任务移入或移出冲刺。

租约（适用于共享待办事项的代理）

• next_task：在一次调用中选取下一个可用任务并认领它。先列出再认领会留下一个间隙，两个代理都可能落入其中。

• claim_task：对特定任务取得独占租约。

• renew_task_lease：在工作仍在进行时延长租约。

• release_task：交还租约；完成或阻塞任务也会释放它，而结束会话会释放该次运行持有的所有租约。

租约绑定到 RUN（运行），而不是用户。同一个客户端的两个会话以相同的代理身份进行认证，因此基于用户的锁会让一个会话释放另一个会话的工作。租约会自行过期，因此崩溃的代理会释放其任务，而不是一直持有它。

删除工具不在默认目录中，破坏性操作默认拒绝：组织所有者必须在代理调用之前按操作启用它们。可以启用的操作是可恢复的，会移入回收站而不是被销毁。无论如何，优先使用 update_task 而不是删除后重建，因为 Onplana 会审计每一次字段更改并保留历史记录。

生产检查清单

模板 + SDK 能让您跑起来。在此基础上再加上以下各项：

• 按令牌限流。 每个 Bearer 令牌 60–120 次请求/分钟；代理循环比人类更嘈杂。

• 租户成本上限。 如果您的工具调用付费 LLM，请根据本月至今的支出对调度进行门控。Onplana 的部署使用 aiMonthlyCostCapUsd，带有 WARN / BLOCK 模式。

• 审计日志。 每次调度都应写入一条审计记录，标记为 actorType: 'mcp_agent'，以便管理员能够将 AI 代理在其租户中的操作与人类活动分开查看。

• 计划/范围策展。 不要暴露每一个内部工具。Onplana 暴露了 26 个中的 21 个；被隐藏的 5 个要么需要应用内预览 UI，要么对于无人监督的调用来说风险太大，要么会产生过大的负载。

• 针对高风险变更的 PREVIEW 模式。 在免费层级上，默认将变更工具设为仅预览。Onplana 已提供此功能：在用户明确升级并重新运行之前，代理会看到“它将做什么”。

• 幂等键。 对规范化后的输入 + 会话 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

这会运行 claude mcp add --transport http onplana https://mcp.onplana.com/mcp，并引导您完成浏览器登录。MCP 服务器在 Onplana 的每个计划上都可用，包括免费计划。

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

插件清单特意不声明任何 MCP 服务器。插件以 stdio 形式（command、args、env）声明服务器，而 Onplana 的服务器是远程且通过 OAuth 认证的，因此 /onplana-connect 在运行时通过 Claude Code 原生的 HTTP 传输来附加它，而不是通过 stdio 垫片来路由。

在 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 上下文会拾取本仓库附带的用法提示。

贡献

欢迎提交 Issue 和 PR。该仓库刻意保持小巧，目标是让传输模式清晰、经过充分测试且稳定。主版本号的提升保留给导出的 Dispatcher / BearerAuth / 处理器工厂形状的破坏性变更。补丁和次版本用于提示注入遏制的改进、新的辅助工具以及额外的测试覆盖。

许可证

MIT. © 2026 Onplana

另请参阅

• onplana.com/mcp: 生产环境 Onplana MCP 部署的公开文档页面（完整工具目录、设置说明、安全模型）

• onplana.com: Onplana，PM 平台。云无关、AI 原生、Microsoft Project Online 的替代方案

• Model Context Protocol 规范: MCP 标准

• Anthropic 提示注入指南: 本仓库的封装所实现的安全模式