# @animalabs/mcpl-core 中文文档

规范地址：https://npmcn.com/package/%40animalabs/mcpl-core/

版本：0\.4\.0
npm 元数据更新时间：2026-10-25T18:56:09.852Z
中文译文更新时间：2026-11-06T04:44:18.460Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40animalabs/mcpl-core
原文对照：https://npmcn.com/package/%40animalabs/mcpl-core/?lang=original
项目主页：https://github.com/anima-research/mcpl-core-ts#readme
源码仓库：https://github.com/anima-research/mcpl-core-ts

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

- 包体积（解压后）：390 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：0 个
- 首次发布：2026-06-14T17:06:04.763Z
- 最新版本发布：2026-10-25T18:56:09.306Z
- 近 30 天下载量：15126（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

MCPL核心:JSON-RPC连接,频道,推出事件,以及能力类型.

## 安装

```sh
npm install @animalabs/mcpl-core
```

也可以使用：`pnpm add @animalabs/mcpl-core`、`yarn add @animalabs/mcpl-core`、`bun add @animalabs/mcpl-core`

## README

# @animalabs/mcpl-core (英语)

> Npm上公布为 **`@animalabs/mcpl-core`**在连接体内部 生态系统作为兄弟的源检出 `@connectome/mcpl-core` 依赖密钥( o)`file:../mcpl-core-ts`)——npm键 `file:` 道克以名相取,故二者相并相取.

类型脚本核心 **MCPL 互联网档案馆的存檔,存档日期2013-12-02** 添加的 MCP 超集线协议 服务器启动 **推动活动**, (中文(简体) ), **频道** (双向,推力驱动) 消息流, 对话 **分支**,推断钩,主机管理 在JSON-RPC之上进行能力/设置特征的谈判.

这个软件包是连接体上使用的 共享的、可知性核心 代理人(中继器,桥梁,主机). 它没有商业逻辑——只有电线 合同和连接原始.

## 这里面是什么

-   **`McplConnection`** ——JSON-RPC 2.0连接于可读/可写 流对 (`McplConnection.fromStreams(stdin, stdout)`),带有牵引式 `nextMessage()` 收到的申请/通知和基于承诺 `sendRequest()` 编号 : `sendResponse()` 编号 : `sendNotification()` 编号 : `sendError()`。 。 。 . 每条消息都是一行的,以 `\n` (最后一个也是) 在输入结尾处),因此,内部有一个U+2028或U+2029 a JSON 字符串保留在信件中;通过 WebSocket(`fromWebSocket`, (中文(简体) ), 每个短信都是一个消息。 它让两个角色逃脱了 (单位:千美元)`\u2028`, (中文(简体) ), `\u2029`因此,一个对等点的行读取器会在那里分裂,作为节点 24的读行是,仍然读一个消息. 它关闭一次: 当任一流失败时( TCP 重置时, 一个 WebSocket 错误, a 子进程中断的管子,当其输入结束或被销毁时,当其 输出在完成前被销毁,或者在 `close()`。输出结束于 目的让输入完成:连接仍然读取,并发送 没有更多的。 关闭在报告事前生效:无 更多发送或读取,等待请求以 `ConnectionClosedError`, (中文(简体) ), 财务报告和审定财务报表 `nextMessage()` 返回已排队,然后拒绝。 礛 关闭的流出错误,一次作为 `'error'`,以及 `'close'` 依次为:一旦关闭,无所读取 没有报告流出错。 错误的行作为 `'error'`, (中文(简体) ), 例外也一样a `'request'` 或者说 `'notification'` 听者抛出 : a 错误本身,以及任何其他抛出值作为 `cause` 一、导 言 错误。 也没有关闭连接, 和听众发出的信息 仍然达到 `nextMessage()`请求从 关闭后的队列无法回答。 在一条已经流上建立的连接 完成从一开始就关闭,并在活动后期报告 循环,在等待其他东西之前添加听众: 如果它有一个错误,那么 `'close'`。 。 。 . `close()` 也释放输出, 一次( 它破坏输出流, 关闭 WebSocket; 输入) 授予 `fromStreams` 留在打电话者的,即使 `'close'` 监听器 扔出,所以在关闭后叫它 端口引起,太.
-   **`method`** ——方法名称常数: `initialize`, (中文(简体) ), `push/event`, (中文(简体) ), `channels/*` (单位:千美元)`list`, (中文(简体) ), `open`, (中文(简体) ), `close`, (中文(简体) ), `publish`, (中文(简体) ), `changed`,(......), `branches/*`, (中文(简体) ), `inference/*`, (中文(简体) ), `state/*`, (中文(简体) ), `model/info`,, , , , , , , ,
-   **类型参数/结果** 对于每一种方法(例如:. `ChannelDescriptor`, (中文(简体) ), `PushEventParams`, (中文(简体) ), `ChannelsPublishParams`) (中文(简体) ).
-   **内容块** —— 说 `ContentBlock` (单位:千美元)`text` 编号 : `image` 编号 : `audio`\+ 帮助者 喜欢 `textContent(...)`。 。 。 .
-   **功能集( T)** - 谈判类型(`InitializeCapabilities`, (中文(简体) ), `McplCapabilities`, (中文(简体) ), `FeatureSetDeclaration`,上下文/参考钩盖) 关闭 `CAPABILITY_PATHS` 词汇(SPEC 第6.2节),循环广告 步行( l)`advertisedCapabilities`,第5.1节,赠款匹配(`capabilityGranted`, (中文(简体) ), §5.4)和已关闭 `uses` 审定(`validateUses`,第6.4节.
-   **明显变化(第17节/RFC-003)** —— 说 `manifestDigest` (教条内容) 文摘, `changedDomains`,以及 `ManifestTracker`: 调用 `setManifest(next)` 财务报告和审定财务报表 文摘, diff, 每条连接 `mcpl/manifestChanged` 通知 编辑 `mcpl/manifest` 快照下来 服务器不会手写 发布.
-   **错误** —— 说 `ConnectionClosedError`他的口信上写着什么 用于呼叫( 没有发送; 它被交给连接的 输出而无答案;或 `nextMessage()`,没有更多的消息会 来了,谁 `outcome` 实值 `'not-sent'` 或者说 `'no-response'` 请求 未定义 `nextMessage()`· ; `RpcError`JSON-RPC 错误及其 `code` 财务报告和审定财务报表 `data`,其消息前没有密码: 自己的讯息,或一句话说,当它没有发出任何短信时,会发生什么; `ConnectionTimeoutError`,则 `RpcError` (代码 -32000, `outcome` `'no-response'`(a) 一项请求,但未得到及时答复 `ERR_*` 协议错误代码.

## 能力广告是一棵树,缺席是否定

`channels`, (中文(简体) ), `contextHooks.beforeInference` 财务报告和审定财务报表 `inferenceRequest` 为: **对象** 其成员是第6.2节词汇的叶子。 布尔 `true` 任何地点 每片叶子的分层都是简指的; `false` 或缺席意味着无.

```ts
const mcpl: McplCapabilities = {
  version: '0.5',
  channels: { register: true, publish: true, incoming: true, streaming: true },
  contextHooks: {
    beforeInference: { observe: false, inject: { beforeUser: true, afterUser: true } },
  },
};

advertisedCapabilities(mcpl);
// Set { 'channels.register', 'channels.publish', 'channels.incoming',
//       'channels.streaming',
//       'contextHooks.beforeInference.inject.beforeUser',
//       'contextHooks.beforeInference.inject.afterUser' }
```

这是一个 **输入到** 东道主的赠款计算, 从来没有授权. `effectiveCapabilities` (§5.4)是唯一的规范许可人:每条路径不 拒绝存在. `deniedCapabilities` 是诊断,而必须不达到 授权决定.

## 合规向量

`test/vectors/manifest-digest-vectors.json` 是一份被冻结的逐字记录 来自 [`anima-research/mcpl`](https://github.com/anima-research/mcpl) `conformance/manifest-digest-vectors.json`。此处不编辑它——矢量 认为错误是一个问题 与收回。 使用 :

```bash
MCPL_DIGEST_VECTORS=/path/to/mcpl/conformance/manifest-digest-vectors.json npm test
```

## 工具箱和工具提示(RFC-014,RFC-015-草稿)

`ToolsetServer` 是 MCPL RFC-014 草稿(工具存在、工具集)的服务器侧运行时间 (原始内容存档于2018-03-26). and surfaces. 这是一个框架,不是电线合同, 所以它住在自己的入口, `@animalabs/mcpl-core/toolsets`; 包根只携带 RFC-014/015 方法名 (单位:千美元)`method.TOOLSETS_OPEN`, (中文(简体) ), `method.ACCESS_TOKEN`,.)和有线类型. 一个服务器保留了完整的工具列表,并说,每个工具,是否是 `static` 或者说 `dynamic`,无论它是 `visible` 现在,和什么 `toolset` 属于它。 主办者 理解提示将动态工具排除在模型的稳定工具列表之外; 不使用的主机 参见完整列表,加 `toolset_open` 编号 : `toolset_close` (对于有实例的工具, `toolset_use`工具使服务器能够继续使用.

```ts
import { McplConnection } from '@animalabs/mcpl-core';
import { ToolsetServer } from '@animalabs/mcpl-core/toolsets';

const server = new ToolsetServer({
  name: 'arcade', version: '1.0.0',
  toolsets: {
    game: {
      title: 'Game', summary: 'A game against the bot', default: 'closed', instances: true,
      tools: [play, pass, resign],                        // MCP tool definitions
      open(ctx, options) {                                // one instance per toolsets/open
        const g = newGame(options);
        return {
          title: 'Game',
          visible: () => (g.myTurn ? ['play', 'pass', 'resign'] : ['resign']),
          content: () => [{ type: 'text', text: g.board() }],
          async call(tool, args) { return g.do(tool, args); },   // results carry their own hint changes
          close() {},
        };
      },
    },
  },
});
await server.serve(McplConnection.fromStreams(process.stdin, process.stdout), 'local');
```

对你有什么好处:

-   工具集方法,并注明实例;
-   提示调用结果的更改, 针对事件, 或独立, 每条连接连续的 revs (宿主在到达时应用,所以拒绝的推力永远不会被重复);
-   `toolsets/list` 全文发言 `ended` (以美元计) (一) 离开的本金,按清单交付;
-   由电话引起的事件(因此,电话的后果从未被推动);
-   属于本金和幸存的再连接;
-   `ctx.access(audience)`, RFC-015 (授权访问) 的服务器侧面,该服务器侧面向主机请求 短暂的证书.

了解的限制:

-   **鉴定.** 检查每个工具的参数, 静态或工具盘, 工具盘选项 带有一个小内置的 JSON Schema 子集: 类型, enum, const, 属性, 需要, 附加财产、项目、分/最大关键字、图案、 OneOf/AnyOf/AllOf。 它充满了 `default`s 和 **忽略** 其它所有东西`$ref`, (中文(简体) ), `if`编号 :`then`编号 :`else`, (中文(简体) ), `not`, (中文(简体) ), `format`, (中文(简体) ), `uniqueItems`传出 `validate` (例如ajv) 如果你的计谋使用这些.
-   **寿.** 实例超过连接,所以重新连接找到它们。 校长最后一位之后 连接关闭, 它们会打开 `idleCloseMs` (违约24小时),然后关闭 校长被遗忘; `idleCloseMs: 0` 保存到进程退出.
-   **赠款.** 未授予的 MCPL 主机 `tools`,或已禁用服务器的 `<name>.tools` 特性集,没有呼叫或工具集方法(-32002 / -32001). 一个简单的 MCP 主机 作为MCP服务.

## 安装

```bash
npm install @animalabs/mcpl-core
```

## 使用量

```ts
import { McplConnection, ConnectionClosedError, textContent, method } from '@animalabs/mcpl-core';

const conn = McplConnection.fromStreams(process.stdin, process.stdout);

// Stream errors (a reset, a broken pipe), malformed lines and exceptions
// thrown by 'request' or 'notification' listeners arrive here. A stream
// destroyed without an error closes the connection with no 'error'.
// Like any EventEmitter, a connection with no 'error' listener throws them.
conn.on('error', (err) => console.error('mcpl:', err.message));

// server-initiated push, at any time while the connection is open:
conn.sendNotification(method.PUSH_EVENT, { /* … */ });

try {
  while (true) {
    let msg;
    try {
      msg = await conn.nextMessage();
    } catch (err) {
      // The connection closed: a stream ended or failed, or close() was called.
      if (err instanceof ConnectionClosedError) break;
      throw err;
    }
    if (msg.type === 'request' && msg.request.method === 'tools/list') {
      conn.sendResponse(msg.request.id, { tools: [] });
    }
  }
} finally {
  // Releases the output (stdout here), whichever side closed the connection.
  // The input stays this program's: the connection only stops reading it.
  conn.close();
}
```

## 构建测试( T)

```bash
npm install
npm run build   # tsc → dist/
npm test
```

节点 22.12 或以后支持,因为 `engines` 说 CI 创建和测试 Linux 有22.12.0,24和最新的节点, 并以22.12.0的macOS为基础 和最新的.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40animalabs/mcpl-core/LICENSE)。 。 。 .

## 常见问题

### @animalabs/mcpl-core 是什么？

MCPL核心:JSON-RPC连接,频道,推出事件,以及能力类型\.

### 如何安装 @animalabs/mcpl-core？

在项目目录运行 npm install @animalabs/mcpl-core，或使用 pnpm add / yarn add / bun add。

### @animalabs/mcpl-core 支持 TypeScript 吗？

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

### @animalabs/mcpl-core 支持 ESM 还是 CommonJS？

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

### @animalabs/mcpl-core 需要什么版本的 Node\.js？

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

### @animalabs/mcpl-core 可以商用吗？

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

### @animalabs/mcpl-core 的下载量有多少？

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

### @animalabs/mcpl-core 还在维护吗？

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