使用说明

MCP代理评估

统一的MCP代理评估：将MCP验证、A2A代理卡检查、ERC-8004链上验证和信誉查询整合到一个具有严重性分类和比较支持的结构化评估中。

什么是代理人？

在本模块的上下文中 代理人 是一个MCP服务器端点，它公开了多达四个协议层的功能：

MCP 服务器 --通过模型上下文协议提供工具、资源和提示
A2A代理卡 --按照谷歌的代理到代理协议发布代理卡
ERC-8004注册 --通过ERC-8004代理注册表具有链上身份
链上声誉 --在链上携带可验证的声誉数据

代理不限于单一协议。本模块评估端点提供的全方位功能，从基本的MCP合规性到链上身份和声誉。“代理”一词反映了现代MCP服务器越来越多地充当具有身份、支付能力（x402）和跨协议互操作性的自主服务提供商。

描述

该模块为MCP代理提供了一个全面的4层评估管道。它验证协议合规性、支付能力、代理卡结构、链上注册和信誉数据。结果按严重程度（错误、警告、信息）分类并分级（A/B/C），以便快速进行健康评估。

评估包括：

层1：MCP协议验证和x402付款要求（通过 x402-mcp-validator)
层2：A2A代理卡结构和功能（通过 a2a-agent-validator)
层3：ERC-8004链上注册验证（通过 erc8004-registry-parser)
第4层：链上信誉数据查询

快速入门

安装并运行基本评估：

git clone https://github.com/agentprobe/mcp-agent-assessment.git
cd mcp-agent-assessment
npm install

import { McpAgentAssessment } from 'mcp-agent-assessment'

const result = await McpAgentAssessment.assess( {
    endpoint: 'https://mcp.example.com/sse',
    timeout: 15000
} )

console.log( `Grade: ${result.entries.assessment.grade}` )
console.log( `Healthy: ${result.categories.overallHealthy}` )
console.log( `Supports x402: ${result.categories.supportsX402}` )

特性

4层评估管道（MCP、A2A、ERC-8004、声誉）
严重性分类分为3个级别（错误、警告、信息）
基于错误和警告计数的分级系统（A/B/C）
22个统一的布尔类别标志
快照与每层差异的比较
独立层的并行执行
每层可配置超时

建筑学

评估管道将四个独立的验证器协调成一个统一的结果：

flowchart LR
    A[MCP Server URL] --> B[AssessmentPipeline]
    B --> C[Layer 1: MCP + x402]
    B --> D[Layer 2: A2A Card]
    B --> E[Layer 3: ERC-8004]
    E --> F[Layer 4: Reputation]
    C --> G[SeverityClassifier]
    D --> G
    E --> G
    F --> G
    G --> H[AssessmentBuilder]
    H --> I[Grade A/B/C + Unified Result]

方法

该模块导出一个类 McpAgentAssessment 采用两种静态方法评估MCP服务器并比较评估结果。

.asset（）

对MCP服务器端点执行完整的4层评估。返回结构化数据，其中包含严重性分类消息、布尔功能标志、分级和原始层结果。

方法

.assess( { endpoint, timeout, erc8004 } )

参数

密钥	类型	描述	必填
endpoint	string	MCP服务器端点URL	是
timeout	number	请求超时（毫秒）。默认 `15000`	没有
erc8004	对象或空	ERC-8004配置 `rpcNodes` 映射（RPC URL的链别名）。默认 `null`	没有

示例

import { McpAgentAssessment } from 'mcp-agent-assessment'

const result = await McpAgentAssessment.assess( {
    endpoint: 'https://mcp.example.com/sse',
    timeout: 15000,
    erc8004: {
        rpcNodes: {
            'ETHEREUM_MAINNET': 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
            'BASE_MAINNET': 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY'
        }
    }
} )

console.log( `Grade: ${result.entries.assessment.grade}` )
console.log( `Errors: ${result.entries.assessment.errorCount}` )
console.log( `Warnings: ${result.entries.assessment.warningCount}` )

退货

returns {
    status: true,
    messages: [
        {
            code: 'PRB-001',
            severity: 'info',
            layer: 1,
            location: 'tools',
            message: 'Found 3 tools'
        }
    ],
    categories: { /* 22 boolean flags */ },
    entries: {
        endpoint: 'https://mcp.example.com/sse',
        timestamp: '2026-02-07T10:30:00.000Z',
        mcp: { /* Layer 1 data */ },
        a2a: { /* Layer 2 data */ } | null,
        erc8004: { /* Layer 3 data */ } | null,
        reputation: { /* Layer 4 data */ } | null,
        assessment: {
            errorCount: 0,
            warningCount: 0,
            infoCount: 1,
            grade: 'A'
        }
    },
    layers: {
        mcp: { /* raw Layer 1 result */ },
        a2a: { /* raw Layer 2 result */ },
        erc8004: null,
        reputation: null
    }
}

密钥	类型	描述
状态	布尔值	`true` 如果不 `error`-严重性发现
messages	数组	分类查找对象 `{ code, severity, layer, location, message }` （小写内联严重性）
类别	对象	所有4层有22个布尔功能标志
entries	object	结构化数据：端点、时间戳、mcp、a2a、erc8004、信誉、评估
layers	object	每一层的原始结果（mcp、a2a、erc8004、信誉）

.compare（）

比较两个评估结果，并返回一个详细的差异，显示所有层的变化。代表MCP和A2A数据的特定层比较器。

方法

.compare( { before, after } )

参数

密钥	类型	描述	必填
before	对象	上一个 `assess()` 结果	是
after	对象	后续 `assess()` 结果	是

示例

import { McpAgentAssessment } from 'mcp-agent-assessment'

const resultA = await McpAgentAssessment.assess( { endpoint: 'https://mcp.example.com/sse' } )
// ... changes happen on the server ...
const resultB = await McpAgentAssessment.assess( { endpoint: 'https://mcp.example.com/sse' } )

const diff = McpAgentAssessment.compare( { before: resultA, after: resultB } )

console.log( `Has changes: ${diff.hasChanges}` )
console.log( `Grade changed: ${diff.diff.assessment.grade.before} → ${diff.diff.assessment.grade.after}` )

退货

returns {
    status: true,
    findings: [],
    hasChanges: true,
    diff: {
        mcp: { /* delegated to McpServerValidator.compare() */ },
        a2a: { /* delegated to A2aAgentValidator.compare() */ },
        erc8004: {
            registration: { changed: {} },
            categories: { changed: {} }
        } | null,
        reputation: { changed: {} } | null,
        assessment: {
            grade: { before: 'B', after: 'A' },
            errorCount: { before: 0, after: 0 },
            warningCount: { before: 2, after: 0 },
            categories: {
                changed: {
                    supportsX402: { before: false, after: true }
                }
            }
        }
    }
}

密钥	类型	描述
status	boolean	始终 `true` 论成功
发现	数组	`CMP-*` 完整性查找对象 `{ code, severity, location, message }` （例如端点不匹配）
hasChanges	布尔值	`true` 如果检测到任何差异
diff	object	每层diff:mcp、a2a、erc8004、信誉、评估（在结构上键入，从不打开 `findings[].code`)

比较器仅应用正向 LegacyCodeAlias 在diff时间，所以是预重绑定快照（传统通用 VAL-001)与退赛后相比，仍然很干净(VAL-201)；冰冻的快照永远不会被重写。

严重性系统

每个发现都带有INLINE小写严重性（来源于寻路器目录，而不是派生在聚合时间）。三个级别决定了整体成绩：

级别	影响	示例
`error`	A/B级区块	连接失败，付款要求无效
`warning`	A级块	缺少可选字段，规格偏差
`info`	无影响	已发现工具，检测到功能

SeverityClassifier 不再从复合中分配严重性 (layer, code) 地图——它盖章评估等级 layer 并充当引擎拥有的代码的寻路器的一致性镜像。

查找代码前缀

代码遵循以下模式 {PREFIX}-{NUMBER} (^[A-Z]{3,4}-\d{3}$)并且是全球独一无二的。两者通用前缀VAL和CON被重新绑定到不相交的每个验证器编号带中，因此没有两个验证器发出相同的代码：

前缀	频带	范围
`HTTP-*`	*	传输/TLS预检查（第0层）
`CON-*`	`1xx` a2a· `2xx` x402· `5xx` mcp应用程序	连接/协议问题
`VAL-*`	`1xx` a2a· `2xx` x402· `3xx` erc8004· `5xx` mcp应用程序	输入验证问题
`PAY-` / `PRB-` / `AUTH-*`	*	支付/探测/OAuth（x402）
`CSV-*`	*	代理卡验证问题（A2A）
`REG-` / `EVT-` / `URI-*`	*	注册/事件/URI（ERC-8004）
`RPC-*`	`00x` erc8004· `01x` 信誉	RPC节点问题
`REP-*`	*	声誉数据问题
`UIR-` / `UIV-`	*	UI资源/验证（MCP应用程序）
`OASF-*`	*	OASF模式验证
`CMP-*`	*	`compare()` 快照完整性注意事项
`ASM-*`	*	评估输入验证

评分

等级	状况
A	无错误和警告
B	没有错误，但有警告
C	有错误

四层管道

评估贯穿四个层次，它们之间存在依赖关系：

层	协议	源	必填
1	MCP+x402	`x402-mcp-validator`	总是
2	A2A代理卡	`a2a-agent-validator`	总是
3	ERC-8004	`.well-known/agent-registration.json` +链上	仅当 `erc8004` 提供的参数
4	声誉	连锁 `getMetadata()`	仅当第3层找到agentId时

执行：

第1层和第2层并行运行
第3层取决于配置(erc8004 参数）
第4层取决于第3层的结果（需要agentId）

类别参考

评估返回22个布尔标志，对服务器功能进行分类：

第1层（MCP+x402）

标志	描述
isReachable	服务器响应请求
supportsMcp	有效的MCP协议握手
hasTools	服务器公开工具
hasResources	服务器公开资源
hasPrompts	服务器公开提示
supportsX402	至少有一个工具具有x402付款
hasValidPaymentRequirements	付款要求通过验证
supportsExactScheme	使用精确的支付方案
supportsEvm	支持EVM网络
支持索拉纳	支持索拉纳网络
支持任务	支持MCP任务能力
支持MCPApps	支持MCP Apps协议

第2层（A2A）

标志	描述
已找到A2A卡
hasA2aValidStructure	代理卡具有有效结构
hasA2aSkills	代理卡声明技能
supportsA2aStreaming	代理支持流媒体

第3层（ERC-8004）

标志	描述
已注册	`.well-known/agent-registration.json` 已找到
hasErc8004注册	存在链上注册
isErc8004OnChain已验证	链上所有权已验证
是否符合Erc8004规范	注册遵循ERC-8004规范

第4层（声誉）

标志	描述
hasOnChain计算	存在链上信誉数据

总体上

标志	描述
总体健康	否 `error`-所有层的严重性发现

验证码

每个发现都带有内联小写严重性(error, warning, info)来源于寻路者目录； SeverityClassifier 镜像发动机拥有代码的寻路器，并在评估上盖章 layerThe ASM-* 在管道运行之前，在下面输入验证代码。

ASM——评估输入验证

代码	严重性	描述
ASM-001	错误	端点：缺少值
ASM-002	错误	端点：必须是字符串
ASM-003	错误	端点：不能为空
ASM-004	错误	端点：必须是有效的URL
ASM-005	错误	超时：必须是数字
ASM-006	错误	超时：必须大于0
ASM-010	错误	erc8004:必须是对象
ASM-011	错误	erc8004.rpc节点：缺少值
ASM-012	错误	erc8004.rpcNodes：必须是对象
ASM-013	错误	erc8004.rpcNodes：必须至少有一个条目
ASM-014	错误	erc8004.rpcNodes：密钥必须是非空字符串
ASM-015	错误	erc8004.rpcNodes：值必须是非空字符串
ASM-016	错误	erc8004.rpcNodes：必须是有效的URL
ASM-020	错误	之前：缺少值
ASM-021	错误	之前：必须是对象
ASM-022	错误	之前：缺少类别或条目
ASM-023	错误	之后：缺少值
ASM-024	错误	之后：必须是对象
ASM-025	错误	之后：缺少类别或条目

REG--ERC-8004注册中心

代码	严重性	描述
REG-001	信息	众所周知：找不到或无法访问文件
REG-002	警告	众所周知：响应不是有效的JSON
REG-003	警告	众所周知：缺少或无效的“注册”数组
REG-020	警告	agentId:缺少必填字段
REG-021	警告	agentRegistry：缺少必填字段
REG-022	警告	chainId:缺少或未知的链标识符
REG-030	警告	规范：链上数据中的验证问题

RPC——链上RPC

代码	严重性	描述
RPC-001	错误	rpcNodes：没有为链配置RPC节点
RPC-002	错误	eth_call:RPC调用失败
RPC-003	警告	注册表：在链上注册表中找不到代理
RPC-010	错误	信誉：RPC调用失败

REP——声誉

代码	严重性	描述
REP-001	信息	未找到信誉数据

CON--连接（第1层/5层）

代码	严重性	描述
CON-001	错误	端点：无法访问服务器

CMP——比较

代码	严重性	描述
CMP-001	警告	快照之间的端点不同
CMP-002	警告	快照前缺少时间戳
CMP-003	警告	快照后比快照前旧

贡献

欢迎PR！请确保：

所有公共方法都有测试
覆盖率保持在70%以上
代码遵循格式标准（4个空格，没有分号，括号内有空格）
提交消息参考问题编号

许可证

麻省理工学院