# @actiondock/mcp 中文文档

规范地址：https://npmcn.com/package/%40actiondock/mcp/

版本：2\.22\.0
npm 元数据更新时间：2026-10-29T09:01:39.097Z
中文译文更新时间：2026-11-06T23:48:30.893Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40actiondock/mcp
原文对照：https://npmcn.com/package/%40actiondock/mcp/?lang=original
项目主页：https://github.com/team4u/actiondock#readme
源码仓库：https://github.com/team4u/actiondock

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

- 包体积（解压后）：52.7 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.12\.0
- 运行依赖：3 个
- 首次发布：2026-09-02T08:45:48.818Z
- 最新版本发布：2026-10-29T09:01:38.695Z
- 近 30 天下载量：2153（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

动作Dock MCP 将行动曝光为模式背景协议工具的适应器

## 安装

```sh
npm install @actiondock/mcp
```

也可以使用：`pnpm add @actiondock/mcp`、`yarn add @actiondock/mcp`、`bun add @actiondock/mcp`

## README

# @actiondock/mcp

ActionDock 2.x 模型上下文协议适配器。

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-Protocol%20Compliant-purple)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

`@actiondock/mcp` 将 ActionDock 中的原子 Action 映射为标准的模型上下文协议工具，无缝接入各类主流智能体与宿主环境。MCP 适配层直接对接 `@actiondock/core` 导出的标准服务端口体系，忠实保持工具模式与业务入参契约。

* * *

## 核心能力

### 双协议传输通道

-   STDIO 标准输入输出通道：专为本地客户端设计，直接通过子进程标准流双向通信，具备受控诊断流隔离与进程退出协同机制。
-   HTTP 传输通道：专为远程服务与容器化部署设计，基于 Web 标准请求与响应实现流式传输，支持跨域策略配置与鉴权令牌校验。

### 纯净模式映射与契约忠实

-   原始模式完全保真：工具入参和出参模式完全忠实于 Action 定义，不在模式中注入非业务执行包装字段。
-   业务入参纯净传递：工具入参直接透明传递至底层执行引擎，不修改或过滤业务自有的入参字段。
-   命名空间冲突隔离：智能处理多包聚合场景下的动作标识冲突，自动使用包命名空间前缀消除歧义。
-   结构化结果转换：执行结果自动封装为包含文本内容块与结构化数据的 MCP 标准信封。

### 规程映射为资源与提示词

-   只读资源映射：将 Playbook 操作规程自动注册为只读 MCP Resource，支持客户端直接读取 Markdown 规程文本。
-   提示词模版映射：将 Playbook 映射为 MCP Prompt，方便智能体快速装配规程指令。

### 协同取消信号向下传播

-   当 MCP 客户端发起取消请求时，适配层自动捕获中断事件。
-   取消信号通过服务端口直接传递至底层的执行服务，并联动激活当前任务上下文中的 `ctx.signal`。
-   业务代码可通过监听 AbortSignal 安全释放资源或提前终止执行。

### 细粒度权限白名单与安全过滤

MCP 适配层原生支持基于包与动作维度的双层白名单控制，通过 `ActionDockMcpOptions` 进行配置：

-   包白名单 `packageAllowlist`（别名 `packageIds`）：限制仅暴露指定包内的工具与规程。
-   动作白名单 `actionAllowlist`：限制仅暴露指定的动作，支持动作短名 `actionId` 与全限定名 `packageId/actionId`。
-   联动过滤机制：同时配置包白名单与动作白名单时自动计算权限交集，未获授权的动作不会出现在 `tools/list` 工具列表中。

* * *

## 快速使用

通过命令行启动 MCP 服务：

```bash
# 以 STDIO 协议启动
ad mcp

# 以 HTTP 协议启动并在指定端口监听
ad mcp serve --port 8080
```

在代码中通过编程方式创建适配器服务：

```ts
import { startMcpStdio } from "@actiondock/mcp";

await startMcpStdio({
  projectRoot: process.cwd(),
  packageAllowlist: ["system-tools"],
  actionAllowlist: ["system-tools/status", "ping"],
});
```

* * *

## 开源协议

本项目采用 Apache-2.0 开源协议。

## 常见问题

### @actiondock/mcp 是什么？

动作Dock MCP 将行动曝光为模式背景协议工具的适应器

### 如何安装 @actiondock/mcp？

在项目目录运行 npm install @actiondock/mcp，或使用 pnpm add / yarn add / bun add。

### @actiondock/mcp 支持 TypeScript 吗？

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

### @actiondock/mcp 支持 ESM 还是 CommonJS？

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

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

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

### @actiondock/mcp 可以商用吗？

@actiondock/mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @actiondock/mcp 的下载量有多少？

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

### @actiondock/mcp 还在维护吗？

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