AI工作流检查

Install

Run directly (no install needed):

npx -y @yawlabs/ctxlint@latest

Project install (recommended for teams)

```bash npm install -D @yawlabs/ctxlint

Global install

npm install -g @yawlabs/ctxlint

Useful if you want ctxlint available in every project without per-project setup.

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

Example Output

ctxlint v0.9.10

Scanning /Users/you/my-app...

Found 2 context files (1,847 tokens total)
  CLAUDE.md (1,203 tokens, 42 lines)
  AGENTS.md -> CLAUDE.md (symlink)

CLAUDE.md
  ✗ Line 12: src/auth/middleware.ts does not exist
    → Did you mean src/middleware/auth.ts? (renamed 14 days ago)
  ✗ Line 8: "pnpm test" — script "test" not found in package.json
  ⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
  ⚠ testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
  ℹ Line 3: "Express" is in package.json dependencies — agent can infer this

Summary: 2 errors, 2 warnings, 1 info
  Token usage: 1,203 tokens per agent session
  Estimated waste: ~55 tokens (redundant content)

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@latest --mcp

Lint only MCP configs

npx @yawlabs/ctxlint@latest --mcp-only

Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)

npx @yawlabs/ctxlint@latest --mcp-global ```

What MCP config files are scanned

With --mcp-global, also scans Claude Desktop, Cursor, Windsurf, and Amazon Q global configs.

What MCP config checks catch

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 — 43 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 — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.

mcph Config Linting

ctxlint also lints .mcph.json — the config file read by the @yawlabs/mcph CLI, which orchestrates MCP servers via the mcp.hosting registry. Distinct from .mcp.json (different schema, different threat model). Applies across the user-global (~/.mcph.json), per-project (.mcph.json), and machine-local (.mcph.local.json) scope cascade.

```bash

Treat any token in any .mcph.json as an error (env-var-only posture)

npx @yawlabs/ctxlint@latest --mcph --mcph-strict-env-token ```

What mcph config checks catch

Options

Usage: ctxlint [options] [path]

Arguments:
  path                 Project directory to scan (default: ".")

Options:
  --strict                  Exit code 1 on any warning or error (for CI)
  --checks <list>           Comma-separated checks to run (see below)
  --ignore <list>           Comma-separated checks to skip
  --fix                     Auto-fix broken paths using git history and fuzzy matching
  --fix-dry-run             Preview --fix changes without writing
  --yes                     Skip interactive confirmation prompts (required for --fix in TTY)
  --follow-symlinks         Allow --fix to write through symlinks (default: skip)
  --format <fmt>            Output format: text, json, or sarif (default: text)
  --tokens                  Show token breakdown per file
  --verbose                 Show passing checks too
  --quiet                   Suppress all output except errors (exit code only)
  --config <path>           Path to config file (default: .ctxlintrc in project root)
  --depth <n>               Max subdirectory depth to scan (default: 2)
  --mcp                     Enable MCP config linting alongside context file checks
  --mcp-only                Run only MCP config checks, skip context file checks
  --mcp-global              Also scan user/global MCP config files (implies --mcp)
  --mcph                    Enable .mcph.json (mcp.hosting CLI config) linting
  --mcph-only               Run only mcph config checks
  --mcph-global             Also scan ~/.mcph.json (implies --mcph)
  --mcph-strict-env-token   Upgrade mcph-config/prefer-env-token from warning to error
  --session                 Enable session audit checks (cross-project consistency)
  --session-only            Run only session checks, skip context and MCP checks
  --mcp-server              Start the MCP server (alias: `serve` subcommand)
  --watch                   Re-lint on context file changes
  -V, --version             Output the version number
  -h, --help                Display help

Commands:
  init                 Set up a git pre-commit hook

Available checks: paths, commands, staleness, tokens, tier-tokens, redundancy, contradictions, frontmatter, ci-coverage, ci-secrets, mcp-schema, mcp-security, mcp-commands, mcp-deprecated, mcp-env, mcp-urls, mcp-consistency, mcp-redundancy, mcph-token-security, mcph-apibase, mcph-schema-conformance, mcph-lists, mcph-gitignore, session-missing-secret, session-diverged-file, session-missing-workflow, session-stale-memory, session-duplicate-memory, session-loop-detection, session-memory-index-overflow

Passing any mcp-* check name implies --mcp. Passing any mcph-* check name implies --mcph. Passing any session-* check name implies --session.

Config File

Create a .ctxlintrc or .ctxlintrc.json in your project root:

{
  "checks": ["paths", "commands", "tokens", "contradictions", "frontmatter"],
  "ignore": ["redundancy"],
  "strict": true,
  "tokenThresholds": {
    "info": 500,
    "warning": 2000,
    "error": 5000,
    "aggregate": 4000,
    "tierBreakdown": 1000,
    "tierAggregate": 4000
  },
  "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"]
}

The contextFiles array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like CONVENTIONS.md.

Config Reference

Config file resolution order: .ctxlintrc → .ctxlintrc.json in the project root. Use --config <path> to point elsewhere. CLI flags override config fields.

CLI flags override config file settings. Use --config <path> to load a config from a custom location.

With `.mcp.json` (Claude Code project config, Cursor, Windsurf)

Create .mcp.json in your project root:

macOS / Linux / WSL:

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "ctxlint": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Tip: This file is safe to commit — it contains no secrets.

With VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}