S1000D Writer (S1000D Stack)

@shuji-bonji/s1000d-writer-mcp

English | 日本語

An MCP server that lets an LLM create S1000D® data modules without writing XML. The LLM passes a structured draft and numbering rules; the server builds the XML, verifies it against the XSD, the BREX and the references, and applies automatically only the fixes that have exactly one candidate (exact). A fix with several candidates is applied only from a selection, and a value outside the candidates is never accepted. By default nothing is written.

[!IMPORTANT] This is a personal project and is not affiliated with ASD (Aerospace, Security and Defence Industries Association of Europe). S1000D® is a registered trademark of ASD. The S1000D specification, XML schemas, default BREX and official samples are not included in any package or repository, because their terms of use do not grant redistribution. Obtain them from s1000d.org and point the S1000D_SPEC_DIR environment variable at the extracted folder.

What it does

Write rules

• Nothing is written by default. Only with write: true does the server write DMC-….XML into the first folder of csdbDirs (or the first of S1000D_CSDB_DIR). With no destination it writes nothing and returns the reason (no-csdb-dir).
• A file with the same name is not overwritten (write-conflict) unless overwrite: true is passed.
• XML that violates the XSD is not written (schema-invalid) unless allowInvalid: true is passed. schema-not-found (no XSD available) is not a violation; the file is written as unverified.
• With write: true, convert_manual also copies the original assets under their ICN file names.

What is fixed automatically

Only a fix whose confidence is exact and which has exactly one candidate is applied (for example, replacing a value when the BREX allows a single responsible company, or removing an element the BREX forbids). several (more than one candidate, or a value given as a range) and none are not applied and are returned in fixes[]. The user chooses, and the server never fixes with a value outside the candidates. Each applied fix is returned in appliedFixes[] with the values before and after.

Verification status (verification)

Every response carries the verification status of the XSD, the BREX and the references. A missing XSD is reported as schema-not-found and a skipped step as not-run; neither is valid. The server reports the result of verification only: it does not judge conformance to S1000D and does not interpret severity.

Input errors

A mistake in the draft or the numbering rules is returned not as isError but as error: { code: "input-error", path, detail }. path is the location of the mistake (for example /body[1] or /allocation/rules/infoCodeByKind/proced). Fix it and call again.

What it does not do

[!WARNING]

• It does not accept XML written by an LLM. It builds only from a draft. The tools that take existing XML (apply_fixes, extract_segments, apply_segments) do not change the structure of the document.
• It does not fix with a value outside the candidates. There is no entry point for writing a free value.
• It does not skip verification. A built XML is always verified before it is returned.
• It does not judge conformance to S1000D or interpret severity. Read the violations in s1000d-verify-mcp and the explanation of BREX rules in s1000d-brex-mcp.
• It does not translate. It only takes sentences out and puts them back. The LLM or a person translates.
• It does not create illustrations or judge Simplified Technical English (STE). For an illustration it only allocates an ICN and inserts the reference.
• What a data module cannot represent, such as hotspot coordinates or part of scopeRefs in an experiential manual, is reported in notRepresented and never dropped silently.
• It does not create an ACT, CCT or PCT. Applicability relies on the applic of the draft and an existing applicability repository.

Configuration

You can also add folders with the tool argument csdbDirs (the first one is the write destination).

Config file (when environment variables are not passed, such as a Claude Desktop plugin)

When S1000D_SPEC_DIR / S1000D_CSDB_DIR are not set, the server reads the config file ~/.config/s1000d-stack/config.json (under XDG_CONFIG_HOME if set; the location can be changed with S1000D_CONFIG). Claude Desktop does not pass environment variables to a server installed as a plugin, so write the settings here in that case.

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

Environment variables take precedence when they are set. The config file is read again on every call.

Example configuration for 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"
      }
    }
  }
}

Running over HTTP (embedding in a product)

The default is stdio. With --http the server starts over 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

When --host is a loopback address, Host and Origin are limited to localhost names (DNS rebinding protection). When bound to any other address they are not checked, so put the server behind the product's reverse proxy or authentication. Because this server can write files, do not expose it without authentication.

How it works

All building, verification, fixing, comment and segment code lives in the shared library @shuji-bonji/s1000d-core; this server holds only the interpretation of arguments, the shape of the responses and the conversion from a manual to drafts (src/convert/). The input schemas import the definitions of core's draft.schema.json. The conversion is also available as @shuji-bonji/s1000d-writer-mcp/convert.

Development

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

License

MIT. S1000D® is a registered trademark of ASD. This software is not affiliated with ASD and does not include the specification, schemas or official samples.