@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.

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.

Related MCP server: AutoCAD MCP Pro

What it does not do

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.