Doc Tools MCP Server

⚠️ Work in Progress — APIs may change without notice.

A Model Context Protocol (MCP) server for managing pandoc/CSL-YAML bibliographies and verifying citations. Lets your LLM read, search, add, update, delete, validate bibliography entries, and systematically verify that citations support the claims made in your text.

Quick Start

npx @metaneutrons/doc-tools-mcp

Add to your MCP client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "doc-tools": {
      "command": "npx",
      "args": ["-y", "@metaneutrons/doc-tools-mcp"],
      "env": {
        "DT_BIB_YAML": "/path/to/references.yaml",
        "DT_BIB_CSL": "/path/to/style.csl",
        "DT_CT_REGISTRY": "/path/to/ctverify.json"
      }
    }
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | DT_BIB_YAML | Default path to CSL-YAML bibliography file. Makes file param optional on all bib:* tools. | | DT_BIB_CSL | Default path to CSL style file (.csl). Enables style-aware field validation on bib:validate, bib:add, bib:update. | | DT_CT_REGISTRY | Default path to citation verification registry JSON. Makes registry_path optional on all ctverify:* tools. |

All env vars are ignored if the referenced file does not exist. Tool descriptions adapt dynamically to show configured defaults.

Bibliography Tools (bib:*)

Read

| Tool | Description | |------|-------------| | bib:get | Retrieve a single entry by ID (full YAML block) | | bib:search | Full-text search across all fields: author, title, type, year, editor, container-title | | bib:list | List all entries of a given type (e.g., legal_case, chapter, article-journal) | | bib:exists | Check if an ID exists (fast boolean check before citing) | | bib:stats | Entry count total and breakdown by CSL type |

Write

| Tool | Description | |------|-------------| | bib:add | Add a new entry with duplicate ID check, required field validation, and YAML confirmation output | | bib:update | Patch individual fields of an existing entry (other fields remain untouched) | | bib:delete | Remove an entry by ID |

Validation

| Tool | Description | |------|-------------| | bib:validate | Check entire file: YAML syntax, required fields per CSL type, duplicate IDs, missing issued dates |

All write operations automatically create a .bak backup before modifying the file.

CSL Style Validation

When a CSL style file is configured (via DT_BIB_CSL or the style parameter), validation uses the variables actually referenced in the style instead of hardcoded required fields. Entry types not handled by the style produce a warning.

Without a style file, these hardcoded defaults apply:

| Type | Required Fields | |------|----------------| | legal_case | title, authority, number, issued | | book | title, issued | | article-journal | title, container-title, issued | | chapter | title, container-title, issued | | legislation | title, issued | | thesis | title, issued |

Citation Verification Tools (ctverify:*)

Systematic verification that cited sources actually support the claims made in the text.

Workflow: extract → set claims → verify each claim against the source → update status.

| Tool | Description | |------|-------------| | ctverify:extract | Extract citations from Pandoc inline footnotes (^[...]). Captures ~200 chars of context before each footnote. Merges into registry preserving existing claims/statuses. Supports dry_run to preview changes after text edits. | | ctverify:update | Batch update citation entries: set claim, status, note per entry via entries array. Creates new entries when cite is provided. | | ctverify:bulk-update | Batch status update by ID list or filter_status. | | ctverify:status | Show verification progress with counts. Filter by filter_status, filter_claim (use "" for missing claims), or file (basename/suffix match). |

Re-sync after edits

Re-running ctverify:extract after text changes is safe:

1. Exact match — citations with unchanged text keep their claims and status
2. Proximity match — if cite text changed but the position is within ±5 lines, claims are recovered from the nearest previous entry
3. dry_run: true — preview new, removed, and proximity-matched entries before committing

Architecture

src/
├── index.ts                    # MCP server, dynamic provider loading, stdio transport
├── shared/
│   ├── types.ts                # Provider, ToolDefinition, ToolResult interfaces
│   ├── logger.ts               # Structured logging (pino → stderr)
│   └── errors.ts               # Typed error hierarchy
└── providers/
    ├── bib/                    # Bibliography provider
    │   ├── index.ts            # BibProvider (9 tool handlers, env var resolution)
    │   ├── store.ts            # YAML read/write with .bak backup
    │   ├── schema.ts           # Zod schemas + per-type field validation
    │   ├── csl-style.ts        # CSL style parser (variable extraction per type)
    │   └── tools/              # Dynamic tool definitions (read + write)
    └── ctverify/               # Citation verification provider
        ├── index.ts            # CtverifyProvider (4 tool handlers)
        ├── extract.ts          # Pandoc inline footnote parser
        └── types.ts            # CitationEntry interface

The provider system is extensible — add a new directory under src/providers/ with a createProvider() export and it will be auto-discovered at startup.

Development

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run lint          # ESLint

Commit Convention

This repo uses Conventional Commits enforced via Husky + commitlint.

Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert Scopes: bib, ctverify, core, deps, config

License

GPL-3.0 — See LICENSE for details.