# @contentful/mcp-tools 中文文档

规范地址：https://npmcn.com/package/%40contentful/mcp-tools/

版本：0\.12\.61
npm 元数据更新时间：2026-11-06T00:18:51.216Z
中文译文更新时间：2026-11-10T16:39:53.322Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2025-10-20T07:29:36.856Z
- 最新版本发布：2026-11-06T00:18:50.944Z
- 近 30 天下载量：29389（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 87 个）

## 中文简介

包含可重复使用的MCP(模式上下文协议)工具的工具包,用于内容。 这个软件包提供结构化工具集,包含完整的元数据,包括描述,输入计划,语义说明,以及工具执行等.

## 安装

```sh
npm install @contentful/mcp-tools
```

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

## README

# @ actionful/ mcp 工具

包含可重复使用的MCP(模式上下文协议)工具的工具包,用于内容。 这个软件包提供结构化工具集,包含完整的元数据,包括描述,输入计划,语义说明,以及工具执行等.

## 安装

```bash
npm install @contentful/mcp-tools
```

## 使用量

### 使用工具收藏

包导工具集按类别排列. 收藏中的每个工具包括:

-   `title`: 工具名称
-   `description`: 工具会做什么
-   `inputParams`: Zod schema 或原始形状用于输入验证
-   `annotations`:关于工具行为的语义提示(只读,有破坏性,有同能,有同能,有同能)
-   `tool`: 实际工具执行功能

```typescript
import { ContentfulMcpTools } from '@contentful/mcp-tools';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({ name: 'my-contentful-mcp', version: '1.0.0' });
const tools = new ContentfulMcpTools({
  accessToken: '<management-token>',
  mcpVersion: '1.0.0',
});

// Register a specific tool
const { searchEntries } = tools.getEntryTools();
server.registerTool(
  searchEntries.title,
  {
    description: searchEntries.description,
    inputSchema: searchEntries.inputParams,
    annotations: searchEntries.annotations,
  },
  searchEntries.tool,
);

// Register all tools from a collection
Object.values(tools.getAssetTools()).forEach((toolConfig) => {
  server.registerTool(
    toolConfig.title,
    {
      description: toolConfig.description,
      inputSchema: toolConfig.inputParams,
      annotations: toolConfig.annotations,
    },
    toolConfig.tool,
  );
});
```

### 数据大会写入输入

`create_data_assembly` 无需编辑即可配置 `sys`, (中文(简体) ), `dataType`,或 `variant`。 API 生成 `sys.id` 和推断 `sys.dataType` 从 `return`。 。 。 . `parameters` 是一个命令的、具有稳定状态的状态 `id` 和明确 布尔 `required`。删除参数的更新需要从 当前获取响应并保留服务器元数据。 坐标线 覆盖和工具分布,然后发布这个仅数组的合同. 这是一个中断的输入更改: 呼叫者仍然通过顶层 `sys`, (中文(简体) ), `dataType`, (中文(简体) ), 或者说 `variant` 获取验证错误。 升级时删除这些参数 . 嵌入式资源链接 `sys` 对象仍然是配置的一部分.

`ContentfulMcpTools.getDataAssemblyTools()` 将这些工具曝光给MCP主机. 本地服务器只在 ExO 工具 `ENABLE_EXO_TOOLS` 启用和 该组织拥有 `exoM1` 权利。 远程服务器也要求 页:1 `exoM1` 权利.

```json
{
  "spaceId": "my-space",
  "environmentId": "master",
  "name": "Page title",
  "description": "A static page title",
  "parameters": [{ "id": "title", "type": "String", "required": false }],
  "resolvers": {},
  "return": { "$object": { "title": { "$literal": "Hello" } } }
}
```

`update_data_assembly` 使用组装ID和当前 `sys.version` 从 `get_data_assembly`。允许编辑的字段保留其当前值.

```json
{
  "spaceId": "my-space",
  "environmentId": "master",
  "dataAssemblyId": "the-created-sys-id",
  "version": 3,
  "name": "Updated page title"
}
```

### 可用的工具收藏

收藏来自 `ContentfulMcpTools` 获取器,例如 `getEntryTools()`, (中文(简体) ), `getAssetTools()`, (中文(简体) ), `getContentTypeTools()`, (中文(简体) ), `getReleaseTools()`,以及 `getDataAssemblyTools()`。每个服务器只登记 ExO 收藏 当它的出入门口经过的时候.

### 工具说明

每个工具都包含语义说明来帮助MCP客户端理解工具行为:

-   **`readOnlyHint`**数字 : `true` 如果工具只读取数据而不修改
-   **`destructiveHint`**数字 : `true` 如果工具永久删除或删除数据
-   **`idempotentHint`**数字 : `true` 如果使用相同的输入多次调用该工具,则产生相同的结果
-   **`openWorldHint`**数字 : `true` 如果工具与外部服务或系统交互,则内容范围以外

## 可用的工具

| 类别 | 工具名称 | 说明 |
| --- | --- | --- |
| **背景设置( S)** | `get_initial_context` | 初始化连接并获得使用指令 |
| **内容类型** | `list_content_types` | 列出内容类型(每个请求最多10个) |
|  | `get_content_type` | 获取详细内容类型信息 |
|  | `create_content_type` | 创建新内容类型 |
|  | `update_content_type` | 修改现有内容类型 |
|  | `publish_content_type` | 发布内容类型更改 |
|  | `unpublish_content_type` | 撤消内容类型 |
|  | `delete_content_type` | 删除内容类型 |
| **条目** | `search_entries` | 搜索和过滤空间中的条目 |
|  | `get_entry` | 获取特定条目 |
|  | `create_entry` | 在 locale 支持下创建新内容条目 |
|  | `update_entry` | 在本地端支持下修改已存在的条目 |
|  | `patch_entry` | 更改特定的字段地块, 而不重放其它( JSON Patch) |
|  | `publish_entry` | 公布条目(单项或批量不超过100个) |
|  | `unpublish_entry` | 撤销条目(单项或批量最多100个) |
|  | `delete_entry` | 删除条目 |
| **编辑器接口** | `list_editor_interfaces` | 在空格中列出所有编辑器接口 |
|  | `get_editor_interface` | 获取内容类型的编辑器界面 |
|  | `update_editor_interface` | 更新字段控件、侧边栏和布局 |
| **资产** | `upload_asset` | 上传新资产 |
|  | `list_assets` | 列出和浏览资产(每个请求最多3个) |
|  | `get_asset` | 收回具体资产 |
|  | `update_asset` | 修改资产元数据 |
|  | `publish_asset` | 公布资产(单独或批量最多100个) |
|  | `unpublish_asset` | 未提资产(单件或多件可达100个) |
|  | `delete_asset` | 删除资产 |
| **空间环境( E)** | `list_spaces` | 列出可用的空格( 每个请求最多 10个) |
|  | `get_space` | 获取空间细节 |
|  | `list_environments` | 在空间中列出环境 |
|  | `create_environment` | 创造新的环境 |
|  | `delete_environment` | 删除环境 |
| **语言** | `list_locales` | 列出环境中的所有位置 |
|  | `get_locale` | 获取特定区域信息 |
|  | `create_locale` | 为多语种内容创建新地块 |
|  | `update_locale` | 修改现有的语言设置 |
|  | `delete_locale` | 从环境中删除本地地址 |
| **标记** | `list_tags` | 在环境中列出所有标签 |
|  | `create_tag` | 创建公/私可见度的新标签 |
| **组织** | `list_orgs` | 用户可访问列表组织 |
|  | `get_org` | 获取特定组织的详细信息 |
| **释放** | `list_releases` | 清单释放(每个请求最多10个) |
|  | `get_release` | 获取释放 |
|  | `create_release` | 以条目/资产创建发行 |
|  | `update_release` | 修改发布的标题和/或内容 |
|  | `delete_release` | 删除释放(及其链接的释放行动) |
|  | `publish_release` | 发布发布( 同步; 通过 `get_release_action`(中文(简体) ) |
|  | `unpublish_release` | 取消发布( 同步; 检查通过 `get_release_action`(中文(简体) ) |
|  | `validate_release` | 验证一个发布,可选择反对出版/不出版 |
|  | `get_release_action` | 检查队列释放动作的状况 |
|  | `list_release_actions` | 列出释放行动(每个请求最多10个) |
|  | `schedule_publish_release` | 计划在未来日期(或重新安排)发布 |
|  | `schedule_unpublish_release` | 计划发布到未来日期( 或重排) |
|  | `cancel_scheduled_release` | 取消预定放行(两相确认) |
|  | `list_scheduled_actions` | 列出预定行动(每件请求最多10起) |
| **数据组合( ExO)** | `get_data_assembly` | 获取集合及其当前版本 |
|  | `get_published_data_assembly` | 获取已公布的集合 |
|  | `list_data_assemblies` | 列表组件 |
|  | `list_published_data_assemblies` | 列出已公布的集会 |
|  | `create_data_assembly` | 用无 sys 和 API 生成的 ID 创建 |
|  | `update_data_assembly` | 以无 sys 主体和当前版本更新 |
|  | `delete_data_assembly` | 删除集合 |
|  | `publish_data_assembly` | 发布集会 |
|  | `unpublish_data_assembly` | 解开集合 |
| **AI 行动** | `create_ai_action` | 创建自定义的 AI 驱动工作流程 |
|  | `invoke_ai_action` | Invoke AI 动作带有变量( 块支持) |
|  | `get_ai_action_invocation` | 获取 AI 动作引用细节 |
|  | `get_ai_action` | 获取 AI 动作细节和配置 |
|  | `list_ai_actions` | 在空格中列出 AI 动作( 每个请求最多 3个) |
|  | `update_ai_action` | 更新现有的 AI 动作 |
|  | `publish_ai_action` | 发布 AI 动作以供使用 |
|  | `unpublish_ai_action` | 解开 AI 动作 |
|  | `delete_ai_action` | 删除 AI 动作 |
| **分类概念** | `create_concept` | 创建本地化的新分类概念 |
|  | `get_concept` | 获取特定分类概念 |
|  | `list_concepts` | 列出带有过滤和分级的概念 |
|  | `update_concept` | 更新分类概念属性 |
|  | `delete_concept` | 删除分类学概念 |
| **分类学计划** | `create_concept_scheme` | 创建新的分类概念方案 |
|  | `get_concept_scheme` | 获取具体的概念方案 |
|  | `list_concept_schemes` | 列出带有页形的概念方案 |
|  | `update_concept_scheme` | 更新概念方案属性 |
|  | `delete_concept_scheme` | 删除概念方案 |
| **空间迁移** | `space_to_space_migration_handler` | 启用/损坏空间迁移工作流程 |
|  | `space_to_space_param_collection` | 收集迁移工作流程的参数 |
|  | `export_space` | 导出备案空间以进行迁移 |
|  | `import_space` | 从导出的文件导入空格 |
| **使用量** | `get_usages` | 获取一个组织的汇总使用指标,可选择过滤或按空间分组 |

## 配置

这些工具需要配置环境变量:

```bash
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=your_token_here
CONTENTFUL_HOST=api.contentful.com
SPACE_ID=your_space_id
ENVIRONMENT_ID=master
```

## 测试

所有工具包括综合单元测试。 以 :

```bash
npm test
```

## 许可证

麻省理工学院

## 常见问题

### @contentful/mcp-tools 是什么？

包含可重复使用的MCP\(模式上下文协议\)工具的工具包,用于内容。 这个软件包提供结构化工具集,包含完整的元数据,包括描述,输入计划,语义说明,以及工具执行等\.

### 如何安装 @contentful/mcp-tools？

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

### @contentful/mcp-tools 支持 TypeScript 吗？

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

### @contentful/mcp-tools 支持 ESM 还是 CommonJS？

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

### @contentful/mcp-tools 可以商用吗？

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

### @contentful/mcp-tools 的下载量有多少？

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

### @contentful/mcp-tools 还在维护吗？

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