agentdx (14ee14)

AgentDX

](https://www.npmjs.com/package/agentdx)  ](package.json) 

用于MCP服务器的ESLint。

AgentDX是一个linter，可以捕获工具描述、模式和命名问题，这些问题会使LLM选择错误的工具、猜测参数并默默失败。不需要API密钥-只需几秒钟即可运行。

npx agentdx lint

为什么？

研究表明 97.1%的MCP工具存在描述质量问题 (arxiv 2602.14878).常见问题：

• 工具描述太模糊，法学硕士无法理解
• 缺少参数描述——LLM猜测要传递什么
• 名称重叠的类似工具——LLM选错了
• 深度嵌套模式——复杂嵌套的LLM性能下降47%
• 工具太多——选择精度降低到超过20个工具

AgentDX比您的用户更早发现这些问题。

快速开始

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

安装

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

规则

AgentDX附带了4个类别的30条规则，这些规则基于学术研究和现实世界的法学硕士行为。

描述质量（10条规则）

架构和参数（11条规则）

命名约定（4条规则）

提供商兼容性（4条规则）

建筑

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

cli/ 编排命令， core/ 提供共享基础设施（MCP客户端、配置加载、服务器自动检测），以及 lint/ 包含规则引擎、4个类别的30条规则和3个输出格式化程序。

CLI参考

agentdx lint [options]

Options:
  -f, --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 to .agentdxrc.json config file
  -v, --verbose           Enable verbose output
  --help                  Show help
  --version               Show version

退出代码

输出格式

• pretty （默认）--带摘要的彩色终端输出
• json --带分数、问题和工具列表的结构化JSON
• sarif --SARIF v2.1.0用于GitHub代码扫描集成

配置

AgentDX的工作原理是零配置。它会自动检测您的服务器入口点。可选择通过以下方式配置规则 agentdx.config.yaml 或 .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集成

# .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

使用 --quiet 对于只应在错误时失败的CI管道：

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

研究

AgentDX规则是基于LLM工具交互的学术研究而制定的：

• “MCP工具描述有异味” (arxiv 2602.14878)--分析了1899个MCP工具，发现97.1%的工具存在描述质量问题。确定了5种气味类别：缺少目的、缺少指导、语言模糊、缺少约束和重复。

• 微软MCP面试官研究 --发现MCP生态系统中有775个命名冲突，工具选择精度下降到20个以上，深度嵌套模式（高达20个级别）导致47%的性能下降。

发展

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

看 贡献.md 发展指南。

路线图

• \[x\] CLI骨架， init, dev
• \[x\] agentdx lint --30条规则，3个格式化器，皮棉评分
• \[ \] --fix 用于自动固定棉绒规则
• \[\]CI GitHub行动(agentdx/lint-action)
• \[\]MCP服务器注册表集成
• \[\]agentdx.dev的登录页面

贡献

我们欢迎捐款！看 贡献.md 用于：

• 开发设置
• 如何添加lint规则
• PR指南和代码风格

请注意，这个项目有一个 行为准则.

许可证

麻省理工学院