S1000D Writer (S1000D Stack)

@shuji-bonji/s1000d-writer-mcp

英語 | 日本語

LLM が XML を記述せずに S1000D® データモジュールを作成できる MCP サーバーです。LLM が構造化されたドラフトと番号付けルールを渡すと、サーバーが XML を構築し、XSD、BREX、参照に照らして検証したうえで、候補が1つだけの修正（exact）を自動的に適用します。候補が複数ある修正は、選択された場合にのみ適用され、候補に含まれない値は受け付けられません。デフォルトでは何も書き込みません。

重要

これは個人プロジェクトであり、ASD（欧州航空宇宙・防衛産業協会）とは無関係です。S1000D® は ASD の登録商標です。 S1000D 仕様、XML スキーマ、デフォルトの BREX、公式サンプルは、使用条件で再配布が認められていないため、いかなるパッケージやリポジトリにも含まれていません。s1000d.org から入手し、展開したフォルダーを指すように S1000D_SPEC_DIR 環境変数を設定してください。

機能

ツール	説明
build_data_module	1つのドラフト（descript、proced、process、fault、PM のいずれか）と番号付けルールからデータモジュールを構築します。DMC、ICN、issue は台帳（ledger）と CSDB から取得され、同じ sourceId には常に同じ DMC が割り当てられます。構築後、XSD、BREX、参照を検証し、最大 maxFixRounds 回まで exact 修正のみを適用します。残りの修正は候補とともに fixes[] で返されます
convert_manual	実践マニュアル（@shuji-bonji/experiential-manual-model）を、トピックごとに1つのデータモジュールと、1つの出版モジュールに変換します。説明、手順、故障箇所の特定は直接対応します。画面フローは、1つのプロセスデータモジュールと、画面ごとに1つの手順に変換されます。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）。
• XSD に違反する XML は、allowInvalid: true を指定しない限り書き込まれません（schema-invalid）。schema-not-found（XSD が見つからない）は違反ではなく、ファイルは未検証として書き込まれます。
• write: true の場合、convert_manual は元のアセットも ICN のファイル名でコピーします。

自動的に修正される内容

confidence が exact で、候補がちょうど1つの場合に限り、修正が適用されます（たとえば、BREXで責任を持つ会社が1社に限定されている場合に値を置き換える、または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 とは提携しておらず、仕様、スキーマ、公式サンプルは含まれていません。