S1000D Writer (S1000D Stack)

@shuji-bonji/s1000d-writer-mcp

英语 | 日语

一个 MCP 服务，可让大模型无需编写 XML 即可创建 S1000D® 数据模块。大模型传入结构化草稿和编号规则；服务生成 XML，根据 XSD、BREX 和引用进行验证，并仅自动应用只有一个候选项的修复（exact）。有多个候选项的修复只有在用户选择后才会应用；候选项之外的值绝不会被接受。默认情况下不会写入任何内容。

重要

这是一个个人项目，与 ASD（欧洲航空航天与国防工业协会）无关。S1000D® 是 ASD 的注册商标。 任何软件包或代码仓库均不包含 S1000D 规范、XML 架构、默认 BREX 和官方示例，因为其使用条款不允许再分发。请从 s1000d.org 获取，并将 S1000D_SPEC_DIR 环境变量指向解压后的文件夹。

功能

工具	描述
build_data_module	根据一份草稿（descript、proced、process、fault 或 PM）和编号规则构建数据模块。DMC、ICN 和版本来自台账（ledger）和 CSDB；相同的 sourceId 始终对应相同的 DMC。构建后会验证 XSD、BREX 和引用，并在最多 maxFixRounds 轮中仅应用 exact 修复。其余修复会连同候选项一起返回到 fixes[] 中
convert_manual	将体验手册（@shuji-bonji/experiential-manual-model）转换为每个主题一个数据模块，外加一个出版模块。描述、程序和故障隔离会直接映射；屏幕流程会转换为一个流程数据模块，并为每个屏幕生成一个程序。DM、PM 和 ICN 之间的引用会根据 CSDB 解析，并纳入刚构建的 DM 以及在磁盘上找到的 ICN 原件。无法表示的内容会以计数形式返回到 notRepresented 中
apply_fixes	应用你从 fixes[] 候选项中选择的修复。所选内容必须是候选项的副本；候选项之外的值或不符合范围的值会连同原因一起列入 rejected。应用后会重新验证
create_comment	构建并验证评论数据模块（comment）。序列号为 CSDB 中的下一个编号
extract_segments	从数据模块中提取供人阅读的句子（标题、段落、步骤、警告、表格单元格、图注），以便进行翻译。行内元素会替换为 {1}、{2} 占位符，并返回 skeletonHash
apply_segments	将翻译后的句子放回提取它们的数据模块中。DMC 保持不变，仅语言发生变化。如果提取后数据模块发生变化，则会因 skeleton-mismatch 停止

写入规则

• 默认情况下不会写入任何内容。 只有设置 write: true 时，服务才会将 DMC-….XML 写入 csdbDirs 中的第一个文件夹（或 S1000D_CSDB_DIR 中的第一个文件夹）。没有目标位置时不会写入任何内容，并会返回原因（no-csdb-dir）。
• 除非传入 overwrite: true，否则不会覆盖同名文件（write-conflict）。
• 除非传入 allowInvalid: true，否则不会写入违反 XSD 的 XML（schema-invalid）。schema-not-found（没有可用的 XSD）不属于违规；文件会作为未经验证的文件写入。
• 设置 write: true 时，convert_manual 还会使用原始资源的 ICN 文件名复制这些资源。

自动修复的内容

只有 confidence 为 exact 且候选项恰好为一个的修复才会应用（例如，当 BREX 只允许一家责任公司时替换某个值，或移除 BREX 禁止的元素）。several（候选项多于一个，或给出的值为一个范围）和 none 不会应用，而是返回在 fixes[] 中。由用户选择，服务绝不会使用候选项之外的值进行修复。每项已应用的修复都会连同修复前后的值返回在 appliedFixes[] 中。

验证状态（verification）

每个响应都包含 XSD、BREX 和引用的验证状态。缺少 XSD 时会报告 schema-not-found，跳过的步骤会报告 not-run；这两者都不表示 valid。服务只报告验证结果：不会判断是否符合 S1000D，也不会解读严重性。

输入错误

草稿或编号规则中的错误不会作为 isError 返回，而是以 error: { code: "input-error", path, detail } 的形式返回。path 是错误所在的位置（例如 /body[1] 或 /allocation/rules/infoCodeByKind/proced）。修正后再次调用。

它不会做什么

警告

• 它不接受由 LLM 编写的 XML。 它只会根据草稿构建。接受现有 XML 的工具（apply_fixes、extract_segments、apply_segments）不会更改文档结构。
• 它不会使用候选项之外的值进行修复。 没有用于写入任意值的入口。
• 它不会跳过验证。 构建的 XML 在返回前始终会经过验证。
• 它不会判断是否符合 S1000D，也不会解读严重性。 请查看 s1000d-verify-mcp 中的违规项，以及 s1000d-brex-mcp 中的 BREX 规则说明。
• 它不会翻译。 它只会提取句子并将其放回原处。翻译由 LLM 或人员完成。
• 它不会创建插图，也不会判断简明技术英语（STE）。 对于插图，它只会分配一个 ICN 并插入引用。
• 数据模块无法表示的内容，例如热点坐标或经验手册中 scopeRefs 的部分内容，会报告在 notRepresented 中，绝不会静默丢弃。
• 它不会创建 ACT、CCT 或 PCT。适用性依赖于草稿中的 applic 和现有的适用性存储库。

配置

环境变量	含义
S1000D_SPEC_DIR	存放已解压的 S1000D 发行包的文件夹。系统会在其中搜索 XSD（xml_schema_flat/）和默认 BREX
S1000D_CSDB_DIR	存放项目数据模块的文件夹。可提供多个文件夹，以 : 分隔（Windows 上使用 ;）。系统会在这些文件夹中搜索 BREX 链、引用目标和现有问题，并将第一个文件夹用作写入目标

也可以通过工具参数 csdbDirs 添加文件夹（第一个文件夹用作写入目标）。

配置文件（未传入环境变量时，例如使用 Claude Desktop 插件）

未设置 S1000D_SPEC_DIR / S1000D_CSDB_DIR 时，服务会读取配置文件 ~/.config/s1000d-stack/config.json（如果设置了 XDG_CONFIG_HOME，则在该目录下；也可以通过 S1000D_CONFIG 更改位置）。Claude Desktop 不会向作为插件安装的服务传递环境变量，因此在这种情况下，请在此处填写设置。

{
  "specDir": "/path/to/s1000d/issue-7",
  "csdbDirs": ["/path/to/your/csdb"]
}

设置了环境变量时，环境变量优先。每次调用都会重新读取配置文件。

Claude Desktop / Claude Code 配置示例

{
  "mcpServers": {
    "s1000d-writer": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/s1000d-writer-mcp"],
      "env": {
        "S1000D_SPEC_DIR": "/path/to/s1000d/issue-7",
        "S1000D_CSDB_DIR": "/path/to/your/csdb"
      }
    }
  }
}

通过 HTTP 运行（嵌入产品）

默认使用 stdio。使用 --http 时，服务会通过 Streamable HTTP 启动。

npx -y @shuji-bonji/s1000d-writer-mcp --http                      # http://127.0.0.1:3000/mcp
npx -y @shuji-bonji/s1000d-writer-mcp --http --port 3102 --path /writer

参数	默认值	含义
--host	127.0.0.1	绑定地址
--port	3000	端口；0 会选择一个空闲端口
--path	/mcp	MCP 端点的路径。GET /healthz 会返回名称和版本
--allowed-host	（见下文）	Host 标头中允许的主机名；可用逗号分隔或重复指定
--allowed-origin	（见下文）	Origin 标头中允许的主机名

当 --host 为环回地址时，Host 和 Origin 会限制为 localhost 名称（防止 DNS 重绑定）。绑定到其他地址时不会进行检查，因此请将服务部署在产品的反向代理或身份验证之后。由于此服务可以写入文件，请勿在未进行身份验证的情况下将其公开。

工作原理

所有构建、验证、修复、注释和分段代码都位于共享库 @shuji-bonji/s1000d-core 中；此服务仅负责解析参数、定义响应结构，以及将手册转换为草稿（src/convert/）。输入架构会导入 core 的 draft.schema.json 定义。转换功能也可通过 @shuji-bonji/s1000d-writer-mcp/convert 使用。

开发

npm install
npm test            # runs on self-made test data only (tests/fixtures/)
npm run test:spec   # uses the distribution you obtained (location given by S1000D_SPEC_DIR; default ../../specs/s1000d/issue-7)
npm run build && S1000D_SPEC_DIR=/path/to/issue-7 S1000D_CSDB_DIR=/path/to/csdb npm start   # start over stdio

许可证

MIT。S1000D® 是 ASD 的注册商标。本软件与 ASD 无关，也不包含该规范、架构或官方示例。