GitHub - agentdx/agentdx: The MCP developer toolkit. Scaffold, lint, test, benchmark, and publish MCP servers.

ESLint for MCP servers.

AgentDX is a linter that catches the tool description, schema, and naming problems that make LLMs pick the wrong tool, guess parameters, and fail silently. No API keys needed — runs in seconds.

Why?

Research shows 97.1% of MCP tools have description quality issues (arxiv 2602.14878). Common problems:

• Tool descriptions too vague for an LLM to understand
• Missing parameter descriptions — the LLM guesses what to pass
• Similar tools with overlapping names — the LLM picks the wrong one
• Deeply nested schemas — LLM performance drops 47% with complex nesting
• Too many tools — selection accuracy degrades past 20 tools

AgentDX finds these problems before your users do.

Quick Start

cd my-mcp-server
npx agentdx lint

AgentDX Lint — my-weather-server (5 tools)

✗ error  get_forecast: no input schema defined                    [schema-exists]
⚠ warn   get_weather: parameter "units" has no description        [schema-param-desc]
⚠ warn   get_alerts: description is 12 chars — too vague          [desc-min-length]
✓ pass   naming is consistent (snake_case)

✓ 22 rules passed | ⚠ 2 warnings | ✗ 1 error

Lint Score: 84/100

Install

npm install -g agentdx
# or use npx for zero-install

Rules

AgentDX ships with 30 rules across 4 categories, informed by academic research and real-world LLM behavior.

Description Quality (10 rules)

Schema & Parameters (11 rules)

Naming Conventions (4 rules)

Provider Compatibility (4 rules)

Architecture

    ┌──────────┐
    │   cli/   │  Commander commands
    └────┬─────┘
         │ imports entry functions only
    ┌────┴─────┐
    │  core/   │  MCP client, config, auto-detect
    └────┬─────┘
         │
    ┌────┴─────┐
    │  lint/   │  Rule engine, rules, formatters
    └──────────┘

cli/ orchestrates commands, core/ provides shared infrastructure (MCP client, config loading, server auto-detection), and lint/ contains the rule engine, 30 rules across 4 categories, and 3 output formatters.

CLI Reference

agentdx lint [options]

Options:
  -f, --format <format>   Output format: pretty (default), json, sarif
  --fix-suggestions       Show concrete fix suggestions for each failing rule
  --quiet                 Only show errors, suppress warnings and info (CI mode)
  -c, --config <path>     Path to .agentdxrc.json config file
  -v, --verbose           Enable verbose output
  --help                  Show help
  --version               Show version

Exit Codes

Output Formats

• pretty (default) — colored terminal output with summary
• json — structured JSON with score, issues, and tool list
• sarif — SARIF v2.1.0 for GitHub Code Scanning integration

Configuration

AgentDX works zero-config. It auto-detects your server entry point. Optionally configure rules via agentdx.config.yaml or .agentdxrc.json:

# agentdx.config.yaml
server:
  entry: src/index.ts
  transport: stdio

lint:
  rules:
    desc-min-length: 30 # override threshold
    schema-enum-bool: off # disable rule
    description-states-limitations: warn # escalate to warning

// .agentdxrc.json
{
  "lint": {
    "rules": {
      "desc-min-length": 30,
      "schema-enum-bool": "off"
    }
  }
}

CI Integration

# .github/workflows/agentdx.yml
name: Lint MCP Server
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install
      - run: npx agentdx lint --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Use --quiet for CI pipelines that should only fail on errors:

npx agentdx lint --quiet  # exit 0 unless errors found

Research

AgentDX rules are informed by academic research on LLM-tool interaction:

• "MCP Tool Descriptions Are Smelly" (arxiv 2602.14878) — analyzed 1,899 MCP tools and found 97.1% have description quality issues. Identified 5 smell categories: missing purpose, missing guidance, vague language, missing constraints, and duplicates.

• Microsoft MCP Interviewer research — found 775 naming collisions across the MCP ecosystem, tool selection accuracy drops past 20 tools, and deeply nested schemas (up to 20 levels) cause 47% performance degradation.

Development

git clone https://github.com/agentdx/agentdx.git
cd agentdx
npm install
npm run build      # tsup → dist/
npm test           # vitest
npm run typecheck  # tsc --noEmit
npm run lint:code  # eslint + prettier

See CONTRIBUTING.md for development guidelines.

Roadmap

• CLI skeleton, init, dev
• agentdx lint — 30 rules, 3 formatters, lint score
• --fix for auto-fixable lint rules
• CI GitHub Action (agentdx/lint-action)
• MCP server registry integration
• Landing page at agentdx.dev

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• How to add lint rules
• PR guidelines and code style

Please note that this project has a Code of Conduct.

License

MIT