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"
      }
    }
  }
}

Related MCP server: MCP Refchecker

Environment Variables

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

Bibliography Tools (bib:*)

Read

Write

Validation

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:

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.

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.