ISO Agents — an MCP server that drafts ISO management-system documents clause by clause

ISO Agents is a Model Context Protocol server written in TypeScript. Each tool produces one documented deliverable of an integrated management system (quality, environment, occupational health and safety, anti-bribery), following the Annex SL high-level structure shared by ISO 9001, ISO 14001, ISO 45001 and ISO 37001. Any MCP client (Claude Desktop, Claude Code, the MCP Inspector, your own agent) can call them.

It was built by a lead ISO auditor to automate the part of consulting work that is repetitive but unforgiving: the model supplies domain judgement, the code enforces the rules that an auditor would otherwise check by hand (nothing fabricated, nothing silently dropped, every change visible, the standard's wording respected).

Deliverables are produced in Spanish and anchored on the Peruvian legal framework, because that is who the tool serves. Everything in this repository (examples, fixtures, templates) is fictional; no client data or official ISO text is versioned.

What makes it different

Most "ISO document generators" fill a template from scratch. This server works on the client's existing Word documents:

Related MCP server: Word AI

Architecture

flowchart LR
    C[MCP client<br/>Claude Desktop · Claude Code · Inspector] -- stdio --> S[src/index.ts<br/>McpServer]
    S --> H[src/lib/herramienta.ts<br/>registrarHerramienta]
    H --> P[perfil.ts · opciones.ts<br/>company profile + grounding options]
    H --> N[normas.ts<br/>requirement text]
    H --> E[extract.ts<br/>.docx → Markdown grid]
    H --> A[anthropic.ts<br/>Claude · JSON or Markdown]
    A --> R[render.ts<br/>Markdown deliverable + JSON]
    R --> D[docx/<br/>casa · plantilla · marcas · markdown]
    R --> F[fidelidad.ts<br/>source → output diff]
    D --> O[(salidas/*.docx)]

Every deliverable is declared as a HerramientaSpec (system prompt, render, Word render, template data) and registered with one call. The shared pipeline applies grounding, mode, format, normative reference, Word export and the fidelity guard uniformly, so a new clause is one new spec file.

Coverage by Annex SL clause

Standards supported in the company profile: 9001, 14001, 45001, 37001 (2025 edition).

The six tools

All tools share the same input: a company profile plus grounding options.

{
  // Profile
  "nombre": "Textiles del Sur S.A.C.",          // required
  "sector": "Manufactura textil",               // required
  "tamano": "51-200",
  "productosServicios": "Tejido de punto y confección",
  "procesos": ["Diseño", "Tejido", "Confección", "Despacho"],
  "ubicacion": "Arequipa, Perú",                // default: Perú
  "normas": ["9001", "45001"],                  // default: ["9001"]
  "material": "Free text from real documents, for grounding",

  // Grounding options (all optional)
  "documentoCliente": "…current document as text…",
  "documentoClientePath": "ejemplos/cliente-partes-interesadas.md",
  "modo": "generar" | "actualizar",
  "formato": "casa" | "cliente",
  "exportarDocx": true,
  "plantillaPath": "ejemplos/plantilla-partes-interesadas.docx",
  "salidaPath": "salidas/"
}

Every tool returns a Markdown deliverable (title, company, requirement, body) followed by a collapsible JSON block with the structured data, so tools can be chained (issues → SWOT → risk planning). When a Word file is produced, its absolute path is appended; in update mode the fidelity report closes the response.

Input:

{
  "nombre": "Financiera del Altiplano S.A.",
  "sector": "Servicios financieros",
  "normas": ["37001"],
  "documentoClientePath": "ejemplos/matriz-vigente-2016.docx",
  "modo": "actualizar",
  "plantillaPath": "ejemplos/plantilla-antisoborno-partes-interesadas.docx"
}

Output (abridged, illustrative):

# Matriz de Partes Interesadas

**Empresa:** Financiera del Altiplano S.A.
**Requisito:** 4.2 Comprensión de las necesidades y expectativas de las partes interesadas

## Partes interesadas internas (4)
| Parte interesada | Necesidades y expectativas | Requisitos para el SIG | ¿Legal? | Influencia | Seguimiento | Abordado mediante el sistema de gestión |
| --- | --- | --- | --- | --- | --- | --- |
| Directorio | Confianza de los grupos de interés<br>Involucramiento de la plana gerencial | Revisión periódica del desempeño del sistema | No | alta | Revisión por la dirección | Revisión por la dirección (9.3) |
| Colaboradores | Ambiente laboral con integridad | Canales de denuncia y protección al denunciante | Sí | media | Canal de denuncias | Canal de denuncias (8.9) |
…

---
<details><summary>Datos estructurados (JSON — para reuso entre herramientas)</summary>
{ "partes": [ { "parte": "Directorio", "tipo": "interna", … } ] }
</details>

---
📄 Plantilla del cliente rellenada — identidad visual exacta:
   /…/salidas/4.2-matriz-de-partes-interesadas-1760000000000.docx
🔎 Fragmentos del origen conservados: 40/40 (100%)
✅ Sin posibles pérdidas.
➕ Adiciones no presentes en el origen (3) — confirmar que respondan a la norma:
   · Determinar si el cambio climático es una cuestión pertinente
   · Canal de denuncias (8.9)
   …

In the generated .docx the new column and the new rows are green, the obsolete reference is red strike-through, and the client's shading per row (internal vs. external) is preserved.

contexto_cuestiones_4_1 — { "nombre": "Textiles del Sur S.A.C.", "sector": "Manufactura textil", "normas": ["9001","45001"] } → two tables (internal / external) with columns Categoría · Cuestión · Tendencia · Impacto potencial en el SIG · FODA, 12–20 issues, each tagged F/O/D/A.

contexto_foda_4_1 — same profile, optionally documentoClientePath: "ejemplos/cliente-foda-2019.md", modo: "actualizar" → SWOT lists, then the cross matrix (FO · FA · DO · DA strategies). In update mode the 2019 reference to ISO 9001:2008 is corrected and the missing cross matrix is added; the fidelity report confirms no original item was lost.

contexto_pestel_4_1 — same profile → one table per PESTEL dimension: Factor · Descripción · Implicancia para el SIG · Tendencia, anchored on Peruvian regulators where relevant.

contexto_alcance_4_3 — profile with productosServicios, procesos, ubicacion → formal scope statement (quoted), products and services covered, physical boundaries (sites), organizational boundaries (units), processes included, exclusions table (ISO 9001 only, each with a justification; empty for 14001/45001/37001).

contexto_mapa_procesos_4_4 — profile with procesos → processes grouped as strategic / operational / support, one SIPOC row each (supplier, inputs, outputs, customer, indicator, owner) and the interactions between them.

Add "exportarDocx": true to any call to also get a house-format Word file.

Running it

Requirements: Node ≥ 20.12 (tested on 22) and an Anthropic API key. The key lives only in the server's environment; the MCP client never sees it.

git clone https://github.com/edpauce/iso-agents.git
cd iso-agents
npm ci
cp .env.example .env.local     # then set ANTHROPIC_API_KEY

Claude Desktop

Add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "iso-agents": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/iso-agents/src/index.ts"],
      "env": { "ANTHROPIC_API_KEY": "<your key>" }
    }
  }
}

Or compile once (npm run build) and point command to node with args: ["/absolute/path/to/iso-agents/dist/index.js"]. The six tools appear under the server name; ask Claude, for example: "Usa contexto_partes_interesadas_4_2 para Textiles del Sur S.A.C., sector manufactura textil, normas 9001 y 45001, y exporta a Word."

Claude Code

claude mcp add iso-agents --env ANTHROPIC_API_KEY=<your key> -- npx tsx "$(pwd)/src/index.ts"

The repository also ships a .mcp.json, so opening the folder in Claude Code offers the server (named ehsq) automatically; it reads the key from .env.local.

MCP Inspector (manual testing in the browser)

npm run inspect

ejemplos/README.md lists five ready-made trials (client format, update mode, house Word, client template, ISO 37001 template) using the fictional company Textiles del Sur S.A.C.

Demo

A short recording of the server inside Claude Desktop belongs here. To make one:

1. Register the server as above and restart Claude Desktop.

2. Record the screen (macOS: ⌘⇧5, or Kap for a GIF) while you ask for the 4.2 matrix of Textiles del Sur S.A.C. with exportarDocx: true, then open the .docx.

3. Keep it under 30 s, save it as docs/demo.gif and reference it here: ![ISO Agents in Claude Desktop](docs/demo.gif).

Use fictional company data in the recording.

Tests

npm ci && npm test

39 tests in about two seconds, no API calls, no client data. Fixtures are synthetic (test/helpers.ts, test/fixtures/) and reproduce the pathologies met on real documents:

• extraction keeps tables as a grid; an ambiguous merged cell produces a note, never a guess; truncated source text arrives verbatim;

• change marks colour the right fragment, keep the run's own properties and leave no residue;

• enumerated fields with change marks do not empty the document; the ISO 37001 4.2 c) column comes from the model, never a hardcoded "Sí"; lists stay lists;

• the normative loader prefers official text, falls back to the paraphrased guide and never invents a requirement that the standard does not have;

• end to end: a client .docx → template with two prototype rows and an extra column → filled document with the right shading per row, one bullet per item, green/red changes, and every input item present in the output;

• the fidelity guard reports losses and additions, tolerates light rewording, is not fooled by change marks and does not count an item cited only in Cambios realizados as preserved.

The tests name the case that motivated them, so nobody deletes them as redundant.

Limitations and things to know

• Clause 4 only. Clauses 5–10 are planned; the framework is ready (HerramientaSpec).

• Spanish output, Peruvian legal anchors (SUNAFIL, OEFA/MINAM, Indecopi, Ley 30424…). Other jurisdictions need the prompts in src/tools/ adjusted.

• Official ISO text is not included. It is copyrighted. The repository ships paraphrased guides (normas/comun/); if you hold a licence, drop the requirement text in normas/<standard>/<code>.md and it takes precedence (.gitignore keeps it local).

• Documents travel to the Anthropic API. Before processing a real client's document, make sure you have the client's consent and that your data-handling agreement allows it. Anthropic does not train on API data by default; check the current terms.

• The model is not deterministic. The guards catch truncation, fabrication of fixed values and content loss; they do not replace the auditor's review. Treat every green addition as a proposal.

• PDF input is not supported (convert to .docx or paste the text). The default model is claude-sonnet-5; override with ANTHROPIC_MODEL.

Project layout

src/
├─ index.ts                 # MCP entry point (stdio), registers the tools
├─ lib/
│  ├─ herramienta.ts        # framework: HerramientaSpec + registrarHerramienta
│  ├─ perfil.ts             # company profile schema (zod)
│  ├─ opciones.ts           # grounding options: document, mode, format, export
│  ├─ extract.ts            # .docx/.txt/.md → Markdown (tables as grid)
│  ├─ normas.ts             # loads the requirement text from normas/
│  ├─ anthropic.ts          # Claude client, JSON/Markdown generation, truncation guard
│  ├─ fidelidad.ts          # runtime fidelity guard (source → output diff)
│  ├─ render.ts             # Markdown helpers, deliverable envelope
│  └─ docx/                 # casa (house Word), plantilla (docxtemplater), marcas (colours), markdown→docx, salida
└─ tools/clausula4/         # one file per deliverable (4.1 ×3, 4.2, 4.3, 4.4)
normas/                     # paraphrased guides + placeholders for licensed text
ejemplos/                   # fictional client documents and templates
scripts/                    # docx-a-plantilla, md-a-docx, template generators
test/                       # 39 tests, synthetic fixtures

Stack

@modelcontextprotocol/sdk · @anthropic-ai/sdk · zod · docx · docxtemplater · mammoth · TypeScript (ESM) · Node test runner.

License

MIT © 2026 Edson Palomino. ISO standards are the property of ISO; this project does not redistribute their text.