AgentDX
用于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 lintAgentDX 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条规则）
| 规则 | 严重性 | 它检查什么 |
|---|---|---|
desc-exists | 错误 | 工具有描述 |
desc-min-length | 警告 | 描述至少包含20个字符 |
desc-max-length | 警告 | 描述少于200个字符 |
desc-action-verb | warn | 描述以动词开头（“检索…”、“创建…”） |
desc-clarity | info | 标记“句柄”、“进程”、“杂项”等模糊术语 |
desc-unique | 警告 | 没有两个工具的描述几乎完全相同 |
description-states-purpose | warn | 描述清楚地说明了该工具的功能 |
description-includes-usage-guidance | info | 解释何时或如何使用该工具 |
description-states-limitations | info | 提及限制、费率限制或注意事项 |
description-has-examples | info | 复杂工具（3+参数）包括示例输入 |
架构和参数（11条规则）
| 规则 | 严重性 | 它检查什么 |
|---|---|---|
schema-exists | 错误 | 工具定义了一个输入模式 |
schema-valid | 错误 | 架构类型为“对象” |
schema-param-desc | warn | 每个参数都有描述 |
schema-required | warn | 标记了必需的参数 |
schema-enum-bool | info | 为了清晰起见，建议使用枚举而不是布尔值 |
schema-no-any | warn | 每个参数都有一个类型 |
schema-defaults | info | 可选参数文档默认值 |
param-enum-documented | warn | 枚举值在描述中进行了说明 |
param-default-documented | info | 描述中提到了默认值 |
schema-not-too-deep | 警告 | 嵌套深度不超过3 |
schema-no-excessive-params | warn | 工具的参数不超过10个 |
命名约定（4条规则）
| 规则 | 严重性 | 它检查什么 |
|---|---|---|
name-convention | 警告 | 一致的命名（snake_case、camelCase或烤肉串case） |
name-verb-noun | info | 遵循verb_noun模式（例如。 get_user) |
name-unique | 错误 | 没有重复的工具名称 |
name-prefix | info | 相关工具共享一个通用前缀 |
提供商兼容性（4条规则）
| 规则 | 严重性 | 它检查什么 |
|---|---|---|
openai-tool-count | 警告/错误 | 警告>20个工具，错误>128个（提供程序限制） |
openai-name-length | 错误 | 名称不超过64个字符 |
openai-name-pattern | 错误 | 名称匹配 /^[a-zA-Z0-9_-]+$/ |
name-not-ambiguous | 警告 | 没有“搜索”、“获取”、“运行”等通用名称 |
建筑
┌──────────┐
│ 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退出代码
| 代码 | 含义 |
|---|---|
0 | 所有规则均已通过 |
1 | 发现错误 |
2 | 发现警告（无错误） |
输出格式
pretty（默认）--带摘要的彩色终端输出json--带分数、问题和工具列表的结构化JSONsarif--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指南和代码风格
请注意，这个项目有一个 行为准则.
许可证
麻省理工学院