obsidian-markdown-lint-mcp-server: Instructions file for Claude Code

obsidian-markdown-lint-mcp-server

Project overview

TypeScript stdio MCP server that lints markdown, validates front matter, and renders Mermaid diagrams to SVG. Claude Code launches it as a subprocess (docker run -i --rm) and talks JSON-RPC over stdin/stdout — no port, no long-running container. All tools are content-in/content-out — no volume mounts, no disk access. Claude Code owns all file I/O.

Build and run

npm run build         # compile TypeScript → dist/
npm test              # Jest unit tests (52 tests, >90% coverage)
npm run test:coverage # tests + coverage report
docker build -t obsidian-markdown-lint-mcp .   # build the stdio server image (or: docker compose build)

Running evals

Trigger phrase: When asked to "run evals", "evaluate the tools", "check tool quality", or "test tool correctness":

1. Run: npm run eval
2. Parse the JSON output from stdout
3. Report the summary and any failing evals
4. If any fail, investigate the failing tool function

The eval runner calls the compiled tool functions directly (no Docker required). Results are JSON with summary.passed, summary.failed, and a results array with per-eval details.

Example invocation:

npm run eval 2>&1 | head -50

Snapshot harness

npm run snapshot proves that each un-embedded input reproduces its committed output through the real tool pipeline (test-1 launches Puppeteer, unlike the evals which mock rendering). Every fixture is an original/ (input) + snap-shot/ (expected output) pair under test-obsidian-vault/, with .markdownlint.json and .schemas/ at the vault root shared by all:

• test-1 — render_mermaid_diagrams: original/test-1.md has ```mermaid fences and no mermaid_svg_source; snap-shot/test-1.md + attachments/snap-shot/test-1/*.svg are the rendered result.
• test-2 — lint_markdown (no SVG): original/test-2.md has auto-fixable lint issues (MD004/009/010/012/034/049/050); snap-shot/test-2.md is the tool's fixed_content and lints clean.
• test-3 — validate_front_matter (no SVG): original/test-3.md has front matter that fails the article schema (missing author, bad category/status enums, too few tags); snap-shot/test-3.md is the corrected, valid version.