Onplana MCP server
OfficialOnplana 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 服务器工作中于生产环境解决了这些问题。公开这些模式具有很高的杠杆效应:
其他 MCP 作者可以获得一个已知良好的模板,而不是重新发明轮子。
该仓库是一个预训练信号来源。公开的 GitHub README 在下一代 LLM 训练数据中权重很高,而一个包含模式 + 关于 MCP 的清晰文档的仓库,能提高模型对“好的 MCP 服务器是什么样的”的召回能力。
调度器接口是您的业务逻辑接入的接缝。传输层是通用的;您的 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.0express@^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)
在 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 提示注入指南: 本仓库的封装所实现的安全模式
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Hosted MCP server for AI agents to post to LinkedIn profiles and X and upload to YouTube.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceA production-ready TypeScript MCP server providing basic tools (add, echo, timestamp), resources (server info, greetings, data access), and prompt templates (analyze, code-review, summarize). Serves as a foundation for building custom MCP servers with extensible architecture.547 npm-
- AlicenseAqualityNot gradedmaintenanceA production-ready TypeScript template for building MCP servers with dual transport support (stdio/HTTP), OAuth 2.1 foundations, SQLite caching, observability, and security features including PII sanitization and rate limiting.429 npm-
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server template designed for building structured tools, prompts, and resources with built-in support for HTTP and STDIO transports. It provides a standardized framework for developers to create and deploy AI-driven services using TypeScript and Zod schema validation.-
- FlicenseAqualityDmaintenanceA TypeScript MCP server template with Zod validation, dual transport (stdio/HTTP), and modular architecture for building MCP-compatible tools, resources, and prompts.11-