@yawlabs/ctxlint 0.3.0 → 0.5.0

package/README.md

@@ -1,8 +1,25 @@
 # ctxlint
 
-Lint your AI agent context files against your actual codebase.
+[![npm version](https://img.shields.io/npm/v/@yawlabs/ctxlint)](https://www.npmjs.com/package/@yawlabs/ctxlint)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
+[![CI](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml)
 
-Your `CLAUDE.md` is lying to your agent. ctxlint catches it.
+**Lint your AI agent context files and MCP server configs against your actual codebase.** Context linting + MCP config linting. 21+ context formats, 8 MCP clients, auto-fix. Works as a CLI, CI step, pre-commit hook, or MCP server.
+
+Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API key. ctxlint catches both.
+
+## Why ctxlint?
+
+Context files rot fast. You rename a file, change a build script, or switch from Jest to Vitest — and your `CLAUDE.md` still says the old thing. Your agent follows those instructions faithfully, then fails.
+
+- **Catches real problems** — broken paths, wrong commands, stale references, contradictions across files
+- **Smart suggestions** — detects git renames and fuzzy-matches to suggest the right path
+- **Auto-fix** — `--fix` rewrites broken paths automatically using git history
+- **Token-aware** — shows how much context window your files consume and flags redundant content
+- **Every AI tool** — supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 14 more
+- **Multiple outputs** — text, JSON, and SARIF (GitHub Code Scanning)
+- **MCP server** — 4 tools for IDE/agent integration with tool annotations for auto-approval
 
 ## Install
 
@@ -49,6 +66,75 @@ npx @yawlabs/ctxlint
 | `.rules` | Zed |
 | `replit.md` | Replit |
 
+## MCP Server Config Linting
+
+ctxlint also lints MCP server configuration files — the JSON configs that tell AI clients which tools to connect to. These are context interfaces too: they shape what your agent can do.
+
+```bash
+# Lint context files + MCP configs
+npx @yawlabs/ctxlint --mcp
+
+# Lint only MCP configs
+npx @yawlabs/ctxlint --mcp-only
+
+# Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)
+npx @yawlabs/ctxlint --mcp-global
+```
+
+### What MCP config files are scanned
+
+| File | Client |
+|------|--------|
+| `.mcp.json` | Claude Code (universal project config) |
+| `.cursor/mcp.json` | Cursor |
+| `.vscode/mcp.json` | VS Code / GitHub Copilot |
+| `.amazonq/mcp.json` | Amazon Q Developer |
+| `.continue/mcpServers/*.json` | Continue |
+
+With `--mcp-global`, also scans Claude Desktop, Cursor, Windsurf, Cline, and Amazon Q global configs.
+
+### What MCP config checks catch
+
+| Check | What it finds |
+|-------|--------------|
+| **Schema** | Invalid JSON, wrong root key (`servers` vs `mcpServers`), missing required fields |
+| **Security** | Hardcoded API keys and Bearer tokens in git-tracked config files |
+| **Commands** | Missing `cmd /c` wrapper for npx on Windows, broken file paths in args |
+| **Deprecated** | SSE transport usage (deprecated March 2025, use Streamable HTTP) |
+| **Env vars** | Wrong env var syntax for the client (`${VAR}` vs `${env:VAR}` vs `${{ secrets.VAR }}`) |
+| **URLs** | Malformed URLs, localhost in project configs, missing path component |
+| **Consistency** | Same server configured differently across client configs |
+| **Redundancy** | Disabled servers, identical configs at multiple scopes |
+
+### Example MCP config output
+
+```
+MCP Configs
+  .mcp.json
+    ✗ mcp-security    Server "api": hardcoded Bearer token in a git-tracked file
+    ✗ mcp-deprecated  Server "old-svc": SSE transport is deprecated — use "http"
+    ✓ mcp-schema
+    ✓ mcp-commands
+  .cursor/mcp.json
+    ✗ mcp-env  Server "api": Cursor uses ${env:VAR}, not ${VAR}
+    ✓ mcp-schema
+  .vscode/mcp.json
+    ✗ mcp-schema  .vscode/mcp.json must use "servers" as root key, not "mcpServers"
+
+Cross-file
+    ⚠ Server "api" is configured differently in .mcp.json and .cursor/mcp.json
+    ℹ Server "db" is in .mcp.json but missing from .cursor/mcp.json
+
+Summary: 3 errors, 2 warnings, 1 info
+```
+
+### MCP Config Linting Specification
+
+The full specification for MCP config linting rules, the cross-client config landscape, and a machine-readable rule catalog are published as open specifications:
+
+- **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — 23 lint rules across 8 categories, the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
+- **[`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json)** — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.
+
 ## Example Output
 
 ```
@@ -92,6 +178,7 @@ Options:
   --quiet              Suppress all output (exit code only, for scripts)
   --config <path>      Path to config file (default: .ctxlintrc in project root)
   --depth <n>          Max subdirectory depth to scan (default: 2)
+  --mcp                Start the MCP server instead of running the linter
   -V, --version        Output the version number
   -h, --help           Display help
 
@@ -175,14 +262,44 @@ CLI flags override config file settings. Use `--config <path>` to load a config
 
 ## Use as MCP Server
 
-ctxlint ships with an MCP server that exposes four tools (`ctxlint_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`):
+ctxlint ships with an MCP server that exposes four tools (`ctxlint_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`). All tools declare annotations so MCP clients can skip confirmation dialogs for read-only operations.
 
-```bash
-# Claude Code
-claude mcp add ctxlint -- node node_modules/@yawlabs/ctxlint/dist/mcp/server.js
+### With `.mcp.json` (Cursor, Windsurf, and other MCP clients)
 
-# Or run from source
-claude mcp add ctxlint -- node /path/to/ctxlint/dist/mcp/server.js
+Create `.mcp.json` in your project root:
+
+macOS / Linux / WSL:
+
+```json
+{
+  "mcpServers": {
+    "ctxlint": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/ctxlint", "--mcp"]
+    }
+  }
+}
+```
+
+Windows:
+
+```json
+{
+  "mcpServers": {
+    "ctxlint": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@yawlabs/ctxlint", "--mcp"]
+    }
+  }
+}
+```
+
+> **Tip:** This file is safe to commit — it contains no secrets.
+
+### With Claude Code
+
+```bash
+claude mcp add ctxlint -- npx -y @yawlabs/ctxlint --mcp
 ```
 
 ## JSON Output
@@ -193,6 +310,19 @@ npx @yawlabs/ctxlint --format json
 
 Returns structured JSON with all file results, issues, and summary — useful for building integrations or dashboards.
 
+## Specifications
+
+ctxlint is the reference implementation of two open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.
+
+| Spec | What it covers |
+|------|---------------|
+| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)** | 19 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions. |
+| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)** | 23 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency. |
+
+Both specs include machine-readable rule catalogs for programmatic consumption:
+- [`context-lint-rules.json`](./context-lint-rules.json) — context file rules and 16 supported format definitions
+- [`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json) — MCP config rules and 8 client definitions
+
 ## Also By Yaw Labs
 
 - [Yaw](https://yaw.sh) — The AI-native terminal