Doc Tools

CI npm License: GPL v3 Node.js Version TypeScript MCP

⚠️ 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.