@bpos/mcp-contract (1.0.0)
Installation
@bpos:registry=https://gitea.akhr-ai.com/api/packages/ChaiHao/npm/npm install @bpos/mcp-contract@1.0.0"@bpos/mcp-contract": "1.0.0"About this package
@bpos/mcp-contract —— MCP 契约
BPOS 作为 MCP 服务器，对 host 那条线上的全部形状。（系统设计 §10.8）
仓里有四份契约，各有各的两头。这一份的读者是 host（执行人自己的桌面 AI 助手）：
| 契约 | 两头 | 凭据 | 面 |
|---|---|---|---|
web/api/contracts |
人 ⇄ 系统 | 会话令牌 | /api/v1 |
contract/activity-contract |
活动 ⇄ 系统 | 能力令牌 | /activity-api/v1 |
contract/data-contract |
数仓 ⇄ 系统 | 库角色 | 没有 HTTP |
| 本包 | host ⇄ 系统 | 接入令牌 | /mcp/v1/<服务> |
四份互不引用（tests/boundary.test.ts 与 server 的 tests/boundaries.test.ts R8b 两头钉）。
同一件事（一张工单）在四份里可以有四种摆法，因为读者不同：屏要渲色渲章，活动要事件与名词，
数仓要列与语义，host 里的模型要的是「我该填哪几格、交付物放哪儿」。
里面有什么
| 名字 | 是什么 |
|---|---|
MCP_CONTRACT_VERSION |
本包的版本（与 package.json 同一个数，用例钉） |
MCP_PROTOCOL_VERSION |
MCP 规范的修订版（此刻 2026-07-28）——服务端、桥、契约套件都读这一格，别处不抄 |
MCP_SERVER_NAME |
serverInfo.name（bpos）；版本那一格由服务端现填 |
MCP_SERVICES · mcpServiceSchema |
服务名的事实源。一期只有 desk（协同办单） |
SERVICES · toolCountOf · toolOf |
每一种服务的工具表与那一句 instructions；条数现算 |
DESK_TOOLS |
九件 desk.* 工具的名、标题、给模型的一句、入参 / 出参 zod |
RESOURCE_TEMPLATES · orderIdOfUri · fileShaOfUri |
两个只读投影的 URI 模版与解析 |
MCP_ERROR_CODES |
这张面独有的几个码（stale-baseline · rate-limited · truncated） |
fileRefSchema 等 |
工具入参 / 出参里反复用到的几样小形状 |
工具表从这里扫出去：服务端按 SERVICES 注册（键不在这里的 handler 拒绝启动，出站按同一份
zod 自校验），系统模块服务卡上「工具几个」、连接说明抽屉那张表、《MCP 接入手册》那张表，
全部现算。抄一个数的那天它不会报错，只会静默地少一件。
九件工具（desk，协同办单）
次序就是 tools/list 的次序，也是人办一张单的次序：
desk.list_orders → desk.get_order → desk.get_task_context → desk.save_order →
desk.upload_file → desk.release_order → desk.say → desk.answer_card → desk.lookup
全部落在执行人面：没有管理面的写、没有审批签批。要人定的事（起单、挑执行人、加额度、签批） 回工作台——那是另一个人在另一张面上的事。
什么改动要升大版本
判据与脚手架契约那一条同构，问的是「已经配好的 host 会不会因此办不成事」：
- 破（大版本）：撤一件工具 · 给入参加一格必填 · 收窄取值集 · 换
MCP_PROTOCOL_VERSION（那是换了一套话在说）。 - 不破（小版本）：加一件工具 · 给出参加一格 · 给入参加一格可选的——老 host 不知道它， 也永远不会收到它。
升版的同一次提交把外层 AI-Native/CLAUDE.md 的「契约版本」表那一格改到。
跑
npm install
npm run typecheck && npm test
发到 Gitea 私有 npm 的步骤与另外两个包同一条，见 contract/README.md。
Dependencies
Dependencies
| ID | Version |
|---|---|
| zod | 4.4.3 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^24.0.0 |
| tsx | ^4.19.0 |
| typescript | ^5.6.0 |