# @crayon-c4/mcp 中文文档

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

版本：1\.52\.0
npm 元数据更新时间：2026-11-02T17:52:09.011Z
中文译文更新时间：2026-11-13T07:03:26.390Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40crayon-c4/mcp
原文对照：https://npmcn.com/package/%40crayon-c4/mcp/?lang=original
项目主页：https://crayon-c4.com/
源码仓库：https://github.com/SQUORA-NL/CRAYON.C4

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

- 包体积（解压后）：2.6 MB，10 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：4 个
- 首次发布：2026-09-11T10:57:57.853Z
- 最新版本发布：2026-11-02T17:52:08.860Z
- 近 30 天下载量：2142（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

CRAYON-C4的MCP服务器——让任何AI编码代理作者,验证和维护一个CRAYON-C4架构模型(JSON),这个模型总是对已公布的schema有效.

## 安装

```sh
npm install @crayon-c4/mcp
```

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

## README

# @crayon-c4/mcp (英语)

MCP 服务器,允许任何 AI 编码代理创建、更新和维护一个 [克雷扬-C4](https://crayon-c4.com/) 结构模型——在一个.NET,Java,节点,Python或 任何语文储存库——和 **永远** 生成无效文件.

它与克洛德代码,克洛德桌面,克洛德光标,VS代码,Zed,或者其他任何 讲"示范背景协议".

* * *

## 安装

没有安装。 指向您的 MCP 客户端:

```jsonc
{
  "mcpServers": {
    "crayon-c4": {
      "command": "npx",
      "args": ["-y", "@crayon-c4/mcp", "."],
      "env": {
        // Optional. Without it you get the free tier, which is the whole local
        // authoring loop — see "Licensing" below.
        "CRAYON_C4_LICENSE_KEY": "crayon-c4.…"
      }
    }
  }
}
```

这个 `"."` 是服务器的工作空间 。 工具的每个路径都会解决 里面还有 **可能无法逃脱** ——呼叫者是传递其推断路径的代理人 而工作空间根是您同意的边界.

需要节点18+.

* * *

## 担保

**此服务器所写的每个模型都是有效的 .** 不是"通常",也不是"如果特工小心":

-   每个编辑工具都会验证 **内存中的全部模型** 并仅采用该修改 暂停,所以一个被拒绝的编辑会让会话保持原样,并告诉代理商原因;
-   `write_model` 在边界重新验证 **拒绝** 坚持任何无效的;
-   校验为 **两个通行证**因为他们捕捉到不同的东西.. 已发表 [杰森·斯克马](https://crayon-c4.com/schema/v1/crayon-c4.schema.json) (2020-12-草案)说文件是否正确 _形状_,而且应用程序本身的语义 验证者是否表示 _表示_ 关系指向一个元素 不存在, 配属到一个系统的一个组件, 一个指定容器编号的部署 不见了 任何计划都无法表达这些,而它们使进口变为空.

错误会随着JSON指针的出现而回来,每条指针后面都有规则,所以一个特工可以修复和 重提而不是猜测.

* * *

## 它会做什么

**撰写** - 安装一个模型,创建和更新带有C4封装的元素, 维护一个中央关系列表,构建图表(与 `subject` 绘制为 边界框架,将首先报告的级联安全移除,并用 diff 预览 .

**谅解** ——机器可读能力地图,编导指南,已知好 实例,以及 `explain_c4`,它回答每个图级是什么 _页:1_ 而不是说 它的形状。 生成的模型最常见的失败不是无效; 每张图都显示一个不同的缩放.

**扫描** _(持证)_ 检测堆栈,从代码中获取一个C4模型,从代码中获取一个 从 Dockerfiles 的部署视图并作曲( 声明它所做的每个来源) **没有** 改为: Kubernetes, Helm, Terraform, CI), 行为流的微量, 并合并一个再扫描成一个 现有模式 **没有丢弃手写的装饰**。同样合并 校正仓库本身 `adr/*.md` 决策记录 - Git-inative格式 模型本身导出到——所以编辑一个决定文件(或写一个全新的文件,没有) 编号需要)并重新运行 `merge_model` 是一个真正的双向通道,而不是只输出.

**决定** ——查找并管理模型的架构决定(ADRs):按 状态、类别或它们所涉及的要素(扩展至其内部或包含的内容) 它),全文读出一个,记录一个与元素相联的新元素,移动它整个生命周期, 替换它,重新编号(项目中的每一处内容都重写),并检查 stale 链接。 规则是应用程序自己的:接受的决定是 _记录_ 内容无法 更长时间的编辑——你将取代它——而地位只能向前发展. `write_model` 保留 `adr/*.md` 中,包括删除用于居住的重命名或被删除的决定.

**浓缩** _(持证)_ 列出仍然缺失的每个描述(取自模型) 自己,所以重新运行 从不重复别人已经写的东西) 并填满他们,拒绝 覆盖已经存在的道词.

**指导工作流程** - 5个提示(`author-c4-model`, (中文(简体) ), `add-deployment-view`, (中文(简体) ), `add-flow`, (中文(简体) ), `tune-config`, (中文(简体) ), `enrich-descriptions`——计划,而不是讲座:每个工具的名称, 命令,和陷阱 特定的工作陷入.

* * *

## 偏好来自何处

三个声音, 命令他们如何具体的工作:

1.  页:1 **引擎默认**, (中文(简体) ),
2.  这个 **仓库** —— 说 `.crayon/config.json`,节 `authoring`, (中文(简体) ),
3.  这个 **第二届会议** —— 说 `set_session_settings`。 。 。 .

以后赢了, **每个字段**。无人设置的字段会停留在引擎默认状态,而不是 写成一个,这样设置 `language` 从未默默采用 `granularity` 你没有 提及. `get_session_settings` 报告有效值 _和每个来自哪里_, (中文(简体) ), 因为"为什么它释放出双向边缘"需要一个答案.

* * *

## 许可证发放

校验为 **离线**: 二进制中的公用钥匙船,所以一个钥匙在飞机上工作 这层完全没有遥测.

-   **免费** ——每个资源,既通过验证,又通过整个本地的作者循环.
-   **有执照** - 仓库扫描(`scan`)和AI浓缩管弦乐(`enrich`) (中文(简体) ).

键读取自 `CRAYON_C4_LICENSE_KEY`,则 `.crayon/license` 在工作空间.

**它没有打开.** 没有密钥,一个无法读取的文件,一个伪造的密钥,一个过期的密钥——每一个 他们给你一个工作免费的会话和句子 解释为什么,从来没有坠机和 从来没有一个死服务器。 打电话 `license_status` (从来没有门,从来没有错误) 看到准确的 这届会议能做什么.

买个钥匙 [https://crayon-c4.com/#定价](https://crayon-c4.com/#pricing)。 。 。 .

* * *

## 托管

第二个入口, `crayon-c4-mcp-http`中,用于 团队。 它已经 **无文件系统** ——你的仓库在你的机器上,不是我们的——所以每一个 读取工作空间的工具被拒绝,并指定要运行的本地服务器. 内相编译回路,资源与导出全部工作不变.

* * *

## 走过: 从仓库到模型, 您可以导入

此序之分为序. 一个开始在它面前写入元素的代理 可以说系统 _实值_ 生产出技术上有效的模型,不说任何东西.

**1\. 了解你在建模的内容.**

```
explain_c4                                  → what C4 is for, and each level
explain_c4 { level: "container" }           → the level most models are missing
```

读吧 `crayon-c4://capabilities` ——机器可读规则——和 `crayon-c4://examples/c4-only` 为了形状.

**2\. 说你想写什么.** _(可选)_

```
set_session_settings { descriptionStyle: "concise", language: "nl" }
get_session_settings                        → the effective values AND where each came from
```

**3\. 获得第一个模型.** 要么从中得出

```
detect_stack                                → is there anything here to scan?
propose_config                              → measure first: which diagrams come out too big
write_config { config: <the proposal>, confirm: true }
scan_repo { depth: "container", adopt: true }
```

——或手写:

```
create_model { name: "Acme Shop" }
upsert_nodes { nodes: [ …system and its containers, in one call… ] }
upsert_relationships { relationships: [ …between the DEEPEST elements that talk… ] }
upsert_layer { id: "l-context",    label: "…", diagramType: "context",   subject: null }
upsert_layer { id: "l-containers", label: "…", diagramType: "container", subject: "sys-shop", parent: "l-context" }
upsert_nodes { nodes: [{ id: "sys-shop", zoomLevel: "l-containers" }] }   → drill-in
```

**4.填出通论.** _(持证)_

```
list_enrichment_tasks { limit: 10 }         → what is missing, and the file to read it FROM
apply_enrichment { fills: [ … ] }           → refuses to overwrite anything already written
```

**5\. 检查和写作.**

```
validate_model                              → fix every error; read the warnings
write_model                                 → a DIFF, and nothing written
write_model { confirm: true }               → writes the model + its sidecars
```

**6\. 稍后,当代码继续运行时.**

```
merge_model                                 → the whole change set, nothing applied
merge_model { apply: true, acceptRemovals: [ … ] }
```

`merge_model` 从不丢弃拼写:描述和姓名 双方更改的名称被报告为冲突并被单独保留,以及一个因素 代码不再被删除 只有在你要求它通过 id —— 如果它是 手作相从起. 裁决记录 `adr/*.md` 从未被它删除 全部 任何关于决定的信息 都不是代码生成的 所以一个失踪的文件被报告 有保留,没有提出去除;有记录 `proposed` 永远不会被 文档,无论你解决什么,因为模型自己的 接受/折旧/被取代 不可剥夺规则也在这里适用.

最后,导入 `crayon-c4-project.json` 时间 [https://crayon-c4.com (英语)](https://crayon-c4.com/) (单位:千美元)**新项目 + 从 文件**,或 **从代码更新** 画、整理和分享.

* * *

## 参考文献

图例: **小时** =读取或写出您的工作空间,所以在主机运输上被拒绝.

### 工具

| 工具 | 需求 | 小时 | 它会做什么 |
| --- | --- | --- | --- |
| `validate_model` | 免费 |  | 请检查access-date=中的日期值 (帮助) **财务报告和审定财务报表** 语义——内含或路径 |
| `create_model` | 免费 |  | 会话中的脚手架新有效模式 |
| `read_model` | 免费 | 小时 | 打开一个模型并概括它( 计数, 图表, 什么是错的) |
| `upsert_nodes` | 免费 |  | 创建或更新元素, 已执行封装 |
| `upsert_relationships` | 免费 |  | 创建或更新中央关系列表 |
| `upsert_layer` | 免费 |  | 创建或更新图:其元素、主题、父体、行样式 |
| `remove_elements` | 免费 |  | 安全删除,首先报告级联(`dryRun`(中文(简体) ) |
| `set_layout` | 免费 |  | 一个图上的平面元素位置 |
| `write_model` | 免费 | 小时 | 验证 = 预览 diff = 写入 `confirm` |
| `list_decisions` | 免费 |  | 按地位、文本、类别、日期或所涉要素查找决定 |
| `get_decision` | 免费 |  | 一项完整的决定,及其环节和取而代之 |
| `create_decision` | 免费 |  | 记录与决定内容相关的决定 |
| `update_decision` | 免费 |  | 编辑草稿;在被接受的记录中仅列出链接和类别 |
| `set_decision_status` | 免费 |  | (仅提前) |
| `supersede_decision` | 免费 |  | 替换决定并链接链条 |
| `acknowledge_decision` | 免费 |  | 确认标记的决定仍然有效 |
| `delete_decision` | 免费 |  | 删除 a `proposed` 草案 |
| `renumber_decision` | 免费 |  | 重新编号并重写每一次提及(审查,然后) `confirm`(中文(简体) ) |
| `check_decisions` | 免费 |  | 调试链接, 决定审查, 无效的记录 |
| `import_decisions` | 免费 | 小时 | 折叠 `adr/*.md` 手编辑和新文件输入模型 |
| `license_status` | 免费 |  | 层次、能力,以及——当没有许可证时——究竟为什么 |
| `explain_c4` | 免费 |  | 每个图级用于什么;6个专题深度 |
| `get_session_settings` | 免费 |  | 有效的设置和决定每个声音的声音 |
| `set_session_settings` | 免费 |  | 本会话的偏好, 每个字段合并 |
| `read_config` | 免费 | 小时 | 读取和验证 `.crayon/config.json` |
| `write_config` | 免费 | 小时 | 合并写作,拒绝计划拒绝的任何东西 |
| `detect_stack` | `scan` | 小时 | Next.js / react /.NET / Java,外加部署证据 |
| `scan_repo` | `scan` | 小时 | 从代码中衍生出一个 C4 模型 |
| `extract_deployment` | `scan` | 小时 | Dockerfiles + 作曲 ~ 部署画布, 声明它做了什么 **没有** 读取 |
| `extract_flows` | `scan` | 小时 | 从指定的切入点追踪 F4 流量 |
| `merge_model` | `scan` | 小时 | 重新扫描一下,不要丢弃装饰 |
| `propose_config` | `scan` | 小时 | 措施、提议和重新措施 |
| `list_enrichment_tasks` | `enrich` |  | 每个描述仍然缺失, 及其源文件 |
| `apply_enrichment` | `enrich` |  | 写他们,永远不要覆写什么 |

### 资源

| URI 资源 | 这是什么 |
| --- | --- |
| `crayon-c4://capabilities` | **先念此经.** 元素类型和每个元素的用途, 封装规则,什么 `subject` 指每个关卡,关系语义,DC-\*约束的完整目录 |
| `crayon-c4://guide/authoring` | 传言指南,包括部署和行为片合同 |
| `crayon-c4://schema/model` | 已公布型号为JSON Schema(2020-12草案) |
| `crayon-c4://schema/config` | 这个 `.crayon/config.json` 计划 |
| `crayon-c4://schema/decisions` | 决定(ADR) |
| `crayon-c4://examples/c4-only` | 最小的完整型号 |
| `crayon-c4://examples/full-stack` | 三个片段, 显示交叉连接 |
| `crayon-c4://model/current` | 此会话的模式正在编辑,包括未写编辑 |
| `crayon-c4://config/current` | 磁盘上的这个寄存器配置 |
| `crayon-c4://license` | 本届会议的级别和能力 |

### 提示

| 提示 | 参数 | 它让你经历的 |
| --- | --- | --- |
| `author-c4-model` | `system`, (中文(简体) ), `depth` | 了解系统,然后自下而上地构建系统,以便级别一致 |
| `add-deployment-view` | `environments` | 在集装箱实际运行的地方,连接回它们 |
| `add-flow` | `flow` | 在一次互动中会发生什么,在进行互动的各要素之间 |
| `tune-config` | —— 说 | 使生成的图表可以读取——在改变任何东西之前进行测量 |
| `enrich-descriptions` | —— 说 | 写什么扫描不能推断, 不重写一个人做了什么 |

* * *

## 它写的文件

仅在 `write_model { confirm: true }`,并且只在模型旁边:

| 文件 | 为什么这很重要 |
| --- | --- |
| `crayon-c4-project.json` | 那个模特儿 上面印有一条线索的新线 所以重写是干净的 Git diff |
| `crayon-c4-provenance.json` | 上次扫描的结果是什么? 就是让一个后期的重播 告诉一个名字 **个人** 从代码上写到——没有它,合并就悄悄地取回代码的名字 |
| `crayon-c4-enrichment.json` | 每个缺失的描述均应取自 |
| `adr/*.md` | 每个决定一个文件,只有在模型携带任何文件时才写出. 同样的格式 `merge_model` 直接编辑一个,或者写一个全新的,真正的双向频道 |

全部四人承诺. `.crayon/license`,如果你使用一个, 应该在 `.gitignore`。 。 。 .

* * *

## 许可证和隐私

CRAYON-C4为专有;参见 `LICENSE`。列出捆绑的开源依赖 通知在 `THIRD-PARTY-NOTICES.txt`。 。 。 .

服务器只读取您指向的工作空间, 并且只在您调用工具时 说它有。 离线层不提出任何网络要求.

支助: [https://crayon-c4.com/ support (中文(简体) )](https://crayon-c4.com/support)

## 常见问题

### @crayon-c4/mcp 是什么？

CRAYON-C4的MCP服务器——让任何AI编码代理作者,验证和维护一个CRAYON-C4架构模型\(JSON\),这个模型总是对已公布的schema有效\.

### 如何安装 @crayon-c4/mcp？

在项目目录运行 npm install @crayon-c4/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 crayon-c4-mcp、crayon-c4-mcp-http，可以用 npx crayon-c4-mcp 直接运行。

### @crayon-c4/mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/crayon-c4\_\_mcp 是否存在。

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

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

### @crayon-c4/mcp 可以商用吗？

@crayon-c4/mcp 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @crayon-c4/mcp 的下载量有多少？

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

### @crayon-c4/mcp 还在维护吗？

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