Contextlint

contextlint

[](https://www.npmjs.com/package/@contextlint/cli) [](https://www.npmjs.com/package/@contextlint/cli) [](https://www.npmjs.com/package/@contextlint/mcp-server) [](https://www.npmjs.com/package/@contextlint/lsp-server) [](https://github.com/nozomi-koborinai/contextlint/actions/workflows/ci.yml) [](LICENSE)

🌐 [日本語](README.ja.md) | [中文](README.zh.md) | [한국어](README.ko.md)

A rule-based linter for structured Markdown documents. Catch broken references, duplicate IDs, missing sections, and structural issues — deterministically, in seconds, CI-friendly.

> 📚 Full reference and guides: ****

Why contextlint?

In AI-driven workflows like SDD (Spec Driven Development), Markdown documents form a dependency graph: requirements reference IDs, design docs link back to specs, ADRs cross-reference each other. When that graph silently breaks — a deleted requirement, a mistyped ID, a missing section — the consequence shows up only at read time.

contextlint provides deterministic, static validation for structured Markdown. No AI, no cost, CI-friendly.

> contextlint focuses on content semantics and cross-file integrity. For > Markdown syntax, formatting, and style, use > markdownlint alongside > contextlint — they complement each other well.

Quick Start

AI-assisted (recommended) — for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and any Agent Skills-compatible client. Requires GitHub CLI v2.90+:

gh skill install nozomi-koborinai/contextlint contextlint-init

Then ask your agent to "set up contextlint". The skill detects your repo layout, infers rules, installs the CLI, and writes contextlint.config.json for you.

Manual setup:

npm install -D @contextlint/cli
npx contextlint init
npx contextlint

Sample output:

docs/requirements.md
  line 3   warning  Empty cell in column "Status"  TBL-002

docs/design.md
  line 12  error    Link target "./api.md" does not exist  REF-001

1 error, 1 warning in 2 files

Rules

contextlint ships 21 rules across 7 categories:

| Prefix | Category | What it validates | Count | | --- | --- | --- | --- | | TBL | Table | Required columns, empty cells, allowed values, patterns, cross-column constraints, cross-file ID uniqueness | 6 | | SEC | Section | Existence and order of section headings | 2 | | STR | Structure | Project-level file existence | 1 | | REF | Reference | Links, anchors, cross-file ID references, stability consistency, zone dependencies, image references | 6 | | CHK | Checklist | Checklist completion status | 1 | | CTX | Context | Placeholder detection, term consistency | 2 | | GRP | Graph | Traceability chains, circular references, orphan documents | 3 |

See Rules for the full per-rule reference.

Learn more

For commands beyond lint (init, impact, slice, graph, compile, --watch), run npx contextlint --help or browse the docs:

| Topic | Link | | --- | --- | | Get Started | | | Configuration reference | | | Rule reference (all 21) | | | CLI commands and flags | | | Editor integration (LSP) | | | AI agents (MCP, Agent Skills) | | | CI/CD integration | | | Recipes (ADR / SDD / monorepo) | | | Programmatic Graph API | |

Packages

| Package | Description | | --- | --- | | @contextlint/core | Rule engine and Markdown parser | | @contextlint/cli | CLI entry point (contextlint command) | | @contextlint/mcp-server | MCP server for AI tool integration | | @contextlint/lsp-server | Language Server Protocol implementation | | contextlint-vscode | VS Code / Cursor extension — install the VSIX from GitHub Releases until Marketplace publishing lands |

Resources

• Introducing contextlint — A Linter for Markdown Document Integrity

License

[Apache 2.0](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nozomi-koborinai
• Source: nozomi-koborinai/contextlint
• License: Apache-2.0
• Homepage: https://contextlint.dev

Install and usage instructions live in the source repository linked above.