Skip to main content
Glama
Sign In
S1000D Writer MCP

S1000D Writer MCP

by shuji-bonji
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

convert_manual

Convert experiential operation manual JSON into S1000D publication and data modules, glossary, and ICN assets; verify results, apply exact fixes, and optionally write to CSDB.

Instructions

Convert an experiential operation manual (@shuji-bonji/experiential-manual-model JSON) into S1000D: one publication module, one data module per topic (description → descript, procedure → proced, troubleshooting → fault, screenFlow → process plus one proced per screen), a glossary data module, applicability from the scopes, and ICNs for the assets. Every data module goes through the same flow as build_data_module (build, verify, automatic exact fixes, verify again); references between the data modules are resolved against the CSDB plus the data modules built in this call. Returns dataModules[], publicationModule, assets[] (assetId → ICN and the original file; with write: true the originals are copied under the ICN file name), the ledger, a summary of verification states and notRepresented (what the draft format cannot express). Nothing is written unless write is true.

Input Schema

NameRequiredDescriptionDefault
writeNoWrite the result into the CSDB (the first folder of csdbDirs / S1000D_CSDB_DIR). Default false: the XML is only returned. Nothing is written when the XML is not valid against the XSD unless allowInvalid is true.
manualNoThe manual as JSON (Manual of experiential-manual-model). Alternative to manualPath.
topicsNoTopic ids to convert (default: all; the glossary is converted only when all topics are).
productNoThe product to evaluate applicability for. attributes: ACT productAttribute id → value; conditions: CCT cond id → value. Omit to skip the applicability check.
csdbDirsNoCSDB folders (in addition to S1000D_CSDB_DIR) used to resolve references, find BREX and number new objects. The FIRST folder is also where write: true writes.
languageNoLanguage of the output. Default: Manual.language ("ja" → ja-JP). A BCP 47 tag or { languageIsoCode, countryIsoCode }.
maxFixesNoCap on the remaining fixes listed in the response (default 50).
overwriteNoWith write: true, replace a file of the same name. Default false: an existing file is left alone and reported as write-conflict.
allocationYesNumbering rules and the ledger. infoCodeByKind must give the info codes for descript, proced, process and fault (there is no default).
includeXmlNoInclude the XML of every data module in the response (default: true when write is false, false when write is true).
manualPathNoPath of a manual JSON file. Relative asset paths are resolved from its folder.
originatorNo
issuePolicyNoWhen the CSDB already has the same data module and the draft gives no issueInfo: raise issueNumber (default), raise inWork, or keep the issue.increment-issue
allowInvalidNoWith write: true, write even when verification.schema.state is "invalid". Default false.
assetBaseDirNoFolder the relative Asset.source.path values are resolved from (default: the folder of manualPath).
assetFormatsNoFile format of each figure original, by assetId (or ICN): { extension: "PNG", notation: "png", publicId? }. Default: taken from the original file name for known formats (png, jpg, gif, svg, cgm, pdf).
maxFixRoundsNoHow many times to apply the fixes the server is certain about (confidence "exact") and verify again (default 3). 0 turns automatic fixing off.
defaultApplicNoapplic for data modules without scopeRefs (default: display text "All" / "すべて").
publicationModuleNoBuild the publication module too (default true).
securityClassificationYessecurityClassification for every data module (the manual has none; the value is written as given, not interpreted).
responsiblePartnerCompanyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the build/verify/auto-fix/verify loop, that references are resolved against the CSDB plus DMs built in this call, what write:true actually copies (originals renamed to ICN), and the default of no writes at all. It also names the response fields (dataModules[], publicationModule, assets[], ledger, notRepresented), which is the behavioral contract an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and the kind mapping, and nearly every clause carries information (topic→DM kind mapping, verification loop, return fields, write default). It is a dense single block with no visual structure, which makes it heavier than it needs to be for its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter mutation-capable tool with no annotations and no output schema, the description covers the write semantics, the verification pipeline, the response shape and the limits of the draft format (notRepresented). The remaining depth on parameters like allocation.ledger and issuePolicy lives in the schema, so nothing critical is missing, though a note on failure/partial-write behavior would complete it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 90%, so the schema already explains allocation, ledger, issuePolicy, allowInvalid and the rest. The description adds value mainly for write and for the return shape rather than for individual parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Convert an experiential operation manual ... into S1000D') and then enumerates the exact output artifacts (one PM, one DM per topic with kind mapping, glossary DM, ICNs). It explicitly names the sibling relationship to build_data_module, so an agent can distinguish whole-manual conversion from single-DM building.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is clear from context: this is the batch/manual-level path, and 'Every data module goes through the same flow as build_data_module' tells the agent how the two relate. It also states the glossary-only-when-all-topics rule and that nothing is written unless write is true. It stops short of an explicit 'use build_data_module instead when you have a single DM' routing sentence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools