# @12-apps/mcp 中文文档

规范地址：https://npmcn.com/package/%4012-apps/mcp/

版本：3\.22\.0
npm 元数据更新时间：2026-11-03T23:37:32.718Z
中文译文更新时间：2026-11-05T19:45:42.539Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/mcp
原文对照：https://npmcn.com/package/%4012-apps/mcp/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，133 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：7 个
- peer 依赖：zod \>=4\.0\.0，hono \>=4\.0\.0，react \>=19\.0\.0，playwright-bdd \>=8\.3\.0，@12-apps/wiring \>=1\.9\.0，@playwright/test \>=1\.55\.0
- 首次发布：2026-07-17T22:21:44.063Z
- 最新版本发布：2026-11-03T23:37:32.383Z
- 近 30 天下载量：33182（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

App-agnostic MCP服务器核心:每次OpenAPI操作时生成一个MCP工具并代理每个带有呼叫者无记名符号(permission passover)的呼叫. OAuth 2.1授权服务器(./oaut、./hono:注册/授权/托肯、JWKS和b)

## 安装

```sh
npm install @12-apps/mcp
```

也可以使用：`pnpm add @12-apps/mcp`、`yarn add @12-apps/mcp`、`bun add @12-apps/mcp`

## README

# @ 12- apps/ mcp

App-anoistic core 用于曝光一个应用的 HTTP 端点作为 MCP 服务器,其中 **代理代理完全使用用户的调用权限**。 。 。 .

## 这个想法

生成 **每个 OpenAPI 操作一个 MCP 工具**,并发送每个工具呼叫 **代理到真正的端点 携带打电话者的无记名符号**因为 代理点击浏览器的相同端点, 所有现有的认证/授权 (会议警卫、房客范围界定、角色检查)没有变化——本套计划持有 **零** 授权逻辑。 一个代理可以做 准确的用户可以,没有 再来.

这是通过模式,不是"金子目录"的目录模式: 1:1 工具,没有手写字段地图。 这就是它可以遗传和移动的原因 整个应用程序.

## 两个不常客 一个消费的应用必须满足

1.  **Schema'd HTTP 表面** ——每一次代理可接触操作都是HTTP端点 在运行时生成的 OpenAPI 文件中描述( Zod ) OpenAPI (英语). 该文档是这个软件包的唯一输入.
2.  **一个标准携带者认证** 每个端点都认证一个呼叫者 `Authorization: Bearer <token>` 解决与《公约》相同的问题 正常会话。 代理人盲目地转发了信使.

## 这个软件包提供了什么

| 导出 | 作用 |
| --- | --- |
| `generateTools(doc, opts)` | OpenAPI 操作 — `GeneratedTool[]` (输入计划+HTTP路由元数据). 决取相取. |
| `createToolRegistry({ tools, baseUrl })` | 运输不可知性 `listTools` 编号 : `callTool`· ; `callTool` 与召相持者为代理人. |
| `dispatchTool(tool, args, cfg)` | 通则-代用:通由平方格 → 路径/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格/平方格,向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向后向. |
| `buildManifest` 编号 : `serializeManifest` | 坚定的漂流文物 `mcp:check` 再生 + diffs (参见 `12-apps/ci` `mcp-contract.yml`) (中文(简体) ). |
| `buildProtectedResourceMetadata` 编号 : `bearerChallenge` | OAuth 2.0 保护资源元数据(RFC 9728) + `WWW-Authenticate` 用于资源服务器模式. |

## 授权服务器( 12-23)

上面的传球需要有人去MINT 它向前,直到 12至23分,每个应用程序都写了自己—— ~1.5k LOC 授权/托肯/注册+ 代码,PKCE,旋转并重放其下机械. 这些都是表面的 合同,所以它现在住在这里:

| 条目 | 导出 | 作用 |
| --- | --- | --- |
| `./oauth` | `createApiMcpOauth({ stores, resolveSession })` | OAuth 2.1 授权服务器 : `register` (RFC 7591号) `authorize` (代码+强制性PCE S256) / `token` (代码+刷新),JWKS,和两个 `.well-known` 文档。 还有原始人 无国籍的签名代码 ES256 访问令牌 散列旋转的刷新令牌 与排行撤销 和重试优雅窗口 `verifyBearer` 资源服务器的一半. |
| `./hono` | `mcpOauthRouter(config)` | 与路由器相同的表面,安装在 **来源根** (连接符读作 `.well-known` 从来源,从不从前缀). `hono` 是一个可选的对等点. |
| `./generate` | `mcpGenerateCli(options)` | `mcp:generate` 编号 : `mcp:check` ——执着地表及其漂移之门. |
| `./coverage` | `mcpCoverageCli(options)` | `mcp:coverage` ——每个路由方法和服务器动作要么作为工具被曝光,要么有原因被排除在外. |
| `prisma/` | `mcp.prisma` + 迁移 | `OAuthClient`, (中文(简体) ), `OAuthRefreshToken`, (中文(简体) ), `McpConnection`。授权代码是故意的,不是表格:它们是无国籍的签名blobs. |

门是图书馆+CLI FACE,所以一个主机 `scripts/mcp/{generate,coverage}.ts` 成为导入和一个调用,以及可重复使用的 CI 工作流程 (单位:千美元)`12-apps/ci`是因为 `mcp-contract.yml`保持炮击到相同的包脚本.

**[采用.md](https://npmcn.com/package/%4012-apps/mcp/ADOPTING.md) 收养合同** - 配置表,该 10个接线规则(接线员门、可信任的原产地许可人、 复出店上的多处提示)和B阶段注释.

```ts
const mcpOauth = mcpOauthRouter({
  stores: createPrismaMcpStores(async () => (await getPrismaClient()) as unknown as McpOauthPrisma),
  resolveSession: async (request) => sessionOf(request),   // cookie session ONLY
  enabled: () => process.env.MCP_BEARER_ENABLED === '1',
  trustedOrigins: trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS'),
});
app.route('/', mcpOauth.router);
```

## 应用程序提供什么( 不在这里)

-   这个 **OpenAPI 文档** (从其Zod-schema'd路线)和登记 决定哪一个终点成为工具.
-   **谁签了名** - 饼干会话 `authorize` 将代码绑定到 `AuthResolver` 用于资源服务器侧.
-   **数据所在的地方** ——三家店(一线与 `createPrismaMcpStores`)和签名材料.
-   装订 `ToolRegistry` 页:1 **MCP运输** (单位:千美元) `@modelcontextprotocol/sdk` HTTP 服务器在 `/api/mcp`) (中文(简体) ).

## 交互式 OAuth 同意和现场撤销

主办方在获得任何授权之前可要求资源所有人作出明确决定 代码发布 :

```ts
createApiMcpOauth({
  // Existing stores, cookie-only session resolver and signing configuration…
  consent: {
    path: "/admin/oauth-consent",
    replay: sharedConsentReplayStore,
    requireClientApproval: true,
  },
  isAccessTokenActive: (binding) =>
    isRefreshBindingActive(stores.refreshTokens, binding),
});
```

饼干解析器必须返回一个稳定的每个日志 `sessionBinding`,则 改为 `email` 财务报告和审定财务报表 `subject`。 。 。 . `@12-apps/auth` 显示已校验的会话 `loginSessionId` 为此. 原始 JWT 饼干字节, `iat` 财务报告和审定财务报表 `jti` 旋转 普通会议读取,不得使用。 仅一个用户 id 或电子邮件不是 登录会话绑定。 永远不要解决无记名认证为 资源拥有者会议。 更改/过期的登录会话需要重新启动 流动; 客户端不能提供或覆盖其身份。 一个经过认证的遗产 没有非曲直的会话将发送给同意的UI `reauthenticate=1` 没有 罚单或代码。 显示退出/ 签名指示而不是循环到一个 登录页面,该页面考虑用户已经认证.

`GET authorize` 验证准确的注册回调和PKCE请求,然后 以5分钟签名重定向到配置的同源UI `request` 罚单。 它不发布代码。 票上有原始授权查询 和单向会话绑定,从会话饼干或用户身份. UI 获取 `handlers.consentDetails` (单位:千美元)`GET /api/oauth/consent?request=…`和 使验证 `accountEmail`,注册客户名/代号,准确回调 并请求将范围作为隐藏文本。 账户身份为只响应. 它必须明确批准和拒绝控制。 不日志 要求票,包括遥测,或作为裁判员送票.

`handlers.consentDecision` 仅接受同源 JSON Post 中包含 `{ request, decision: "approve" | "deny" }`它重新检查饼干会话, 登记和请求,在解剖时消耗票并返回 `{ redirectUrl }`。只有批准薄荷 代码。 拒绝返回已验证的 调用 `error=access_denied` 和原始状态。 失踪/不同 起源,会话变更,票面修改,OAuth-field 超载,过期和 重放失败关闭 。 UI在成功响应后才导航. 一个迷失 响应、 刷新/ 回击或重复点击不能修改第二个代码; 重新启动 终端出错后客户端授权流程 。 单独的标签有单独的 罚单,不要相互覆盖.

何时 `requireClientApproval` 常规操作员/提供者规则仍然是 资格上限,在票前检查,在决定前再次检查. 他们从未取代人类的决定,包括预先批准的客户身份证明. 无 该旗帜,明确同意 取代遗留的批准接合.

同意回放店不同于90秒授权码 存储 : `consume(jti, nowMs, expiresAtMs)` 必须共享、原子化和保留权利主张 直到签了名的票过期为止 断电必须拒绝,没有本地程序 倒计时. `inProcessConsentReplayStore()` 仅用于明确的单一进程 主机或测试。 同意的路线只有在下列情况下才列入线路说明: 同意是配置的;所有操作员都留在操作员门后.

现在使用非机密的 SHA-256 来装入所发行的确切刷新行 标识符. `isRefreshBindingActive` 只跟随独特的直接接班人,所以 普通刷新保存已发布的访问权限,直到到期。 断开连接 并在下次验证时重放无效的活行; 重连接 建立不相干根并无法恢复旧的存取,即使在同一秒. 当验证钩被关闭时没有装订失败的后遗症访问符 启用 。 现有的有效刷新令牌可以旋转到绑定访问中而无需 其它 cookie 登录或扩大范围; 自动客户端刷新可能恢复 连接。 只有在无法刷新或取消时才需要重新连接 . 遗留的 cookie 丢失的登录非ce 只需在开始时重新登录 新的授权。 不得有正结果缓存可立即撤销.

Prisma 商店使用索引 `rotated_from` 查找, 限于两行拒绝 模糊的分支。 采用添加剂指数迁移和收养. Traversal 拒绝循环、错误的链接、身份变化和超过 32 继任者跳出. 正常的15分钟访问令牌为0或1个旋转; 2; 32允许攻击性客户端同时限定数据库工作. 客户超过 约束必须使用它最新的进入标志.

Prisma 旋转、 重放撤销和 连接运行的两半 可连续交易。 写入冲突重试整个交易至 三次;疲劳报告失败并卷回,而不是隐藏 连接到现场记录。 自定义仓库应执行可选 原子 `revokeLineage` 财务报告和审定财务报表 `connections.disconnect` 等同端口 序列化; 非原子读取- 当时- revoke 可忽略同时旋转 继任者。 软件包测试 Pin 交易边界和完整操作 重试; 多会场 PostgreSQL 验证必须进行实际冲突 旋转、重放、断开和延迟活动操作.

## 静态技能导入

`createSkillCatalog(namespace, sources, pageSize?)` 部署自备快照 UTF-8资源. 每个来源都有 `name` (单位:千美元) `files` 包括地图 `SKILL.md`。 。 。 . 传回目录为 `McpJsonRpcOptions.skills`。没有这样的主机 选项保持其现有能力和方法.

运输广告 `capabilities.extensions["io.modelcontextprotocol/skills"]` 财务报告和审定财务报表 `resources`,然后服务 `skills/list`, (中文(简体) ), `skills/get`,以及 `resources/read`。 。 。 . 该目录解析了所有YAML前题, 散开准确的UTF-8字节, 拒绝不安全或模糊的路径, 并限制文件和总大小 。 它接受 1至5个技能,每个技能最多100个文件,256个基B `SKILL.md`每架1米B 支持文件,每个技能5个MiB和一个保守的7个MiB横跨目录. 它只支持文本资源. 它从不读取调用文件系统 路径或获取 URL。 返回的值不能突变目录快照 .

阅读需要经过认证的呼叫者。 附加目录范围的主机 检查必须采用同样的政策 `isSkillReadMethod(request.method)` 关于 `tools/list`;图书馆不能推断东道主的租户或范围政策. 仅服务于经过审查的静态指令,从不提供私人或租户特定数据. Skill内容不允许执行工具或发布更改.

`skills/list` 接受 `{}` 刚回来就回来 `{cursor}` 用于后页. 光标绑入目录摘要; 错误或陈旧光标返回 `-32602`。 。 。 . `skills/get` 拿走目录 `SKILL.md` URI 返回 `{skill}`。 。 。 . `resources/read` 返回时 `{contents: [content]}` 与请求的 URI 完全一致. 标准 `resources/list` 财务报告和审定财务报表 `resources/templates/list` 返回空列表 : 技能资源是通过技能表发现的。 两者要求相同 目录认证并拒绝光标,因为它们没有后续的页面. 未知的技能 URI 返回 `-32602`; 未知资源返回 `-32002`无效 参数返回 `-32602`,未认证的读取使用现有的认证 错误代码和未配置主机保留 `-32601` 这些方法。 包含 `catalog.digest` 在主机版本中,如果技能更新必须改变握手方式.

合同: [OpenAI MCP 技能导入](https://developers.openai.com/plugins/build/mcp-server#import-skills-from-the-mcp-server)。 。 。 . 这些方法支持提交时间的快照。 单位测试和HTTP探测器 不证明 ChatGPT 导入 : 部署后, 运行扫描工具, 验证导入 文件,然后通过单独的出版进程提交插件版本.

## 常见问题

### @12-apps/mcp 是什么？

App-agnostic MCP服务器核心:每次OpenAPI操作时生成一个MCP工具并代理每个带有呼叫者无记名符号\(permission passover\)的呼叫\. OAuth 2\.1授权服务器\(\./oaut、\./hono:注册/授权/托肯、JWKS和b\)

### 如何安装 @12-apps/mcp？

在项目目录运行 npm install @12-apps/mcp，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @12-apps/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @12-apps/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @12-apps/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @12-apps/mcp 可以商用吗？

@12-apps/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @12-apps/mcp 的下载量有多少？

根据 npm 官方下载统计，@12-apps/mcp 在 2026/10/04 – 2026/11/02 这 30 天内被下载 33,182 次，日均约 1,106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @12-apps/mcp 还在维护吗？

最新版本 3\.22\.0 发布于 2026/11/04（2 天前）；至今共发布 61 个版本，其中过去 12 个月发布了 61 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。