使用说明

MCP验证器

📋 目录

A.概况
连接Cursor IDE
环境变量
MCP工具
MCP提示
MCP资源
HTTP 模式
交互式验证
CLI 模式
局部起动
工艺堆栈
追加资源

A.概况

版本： 0.5.11

MCP验证器是一个使用模型上下文协议（MCP）通过人工智能验证代码、测试、体系结构和插件的工具。

建筑： 这个项目是建立在建筑的基础上的。 layered_library 明确划分层（服务器、工具、代理、服务、模型、lib）。详细结构描述于 architecture.xml.

✨ 机会

✅ 代码验证 -测试TypeScript、JavaScript、Go、Python、Rust和其他语言
🧪 测试验证 -测试涂层的质量和完整性分析
🏗️ 体系结构验证 -验证建筑解决方案
🔒 安全检查 -搜索代码中的漏洞
⚡ 性能分析 -优化建议
📝 文件验证 -检查文件的质量和完整性
🎯 脉冲验证 -人工智能插件的质量控制
📋 任务验证 -要求和规格分析
🤖 初始化测试 并行一致性测试（3-10次）

支持的语言： TypeScript、JavaScript、Go、Python、Rust、Java、C#、PHP、Ruby、Swift、Kotlin

要求

Node.js>=16.0.0（支持Node.js 16+版本0.5.9）
API开放路由器(免费获得)

备注： 与Node.js 16+兼容 undici 代替内置 fetch环境变量通过 dotenv.

🚀 快速启动

1.获取OpenRouter API密钥：

转到开放路由
创建新的API密钥

2.配置Cursor IDE：

将配置添加到 ~/.cursor/mcp.json

{
    "mcpServers": {
        ... // другие MCP серверы
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE"
            }
        }
    }
}

替换 YOUR_OPENROUTER_API_KEY_HERE 您的 OpenRouter API 密钥
重新启动Cursor IDE

3.第一次验证：

请Cursor的AI助理通过 mcp-validator
如果设置正确，将自动调用MCP工具，该工具将分析文件并返回详细报告。

🔑 获取密钥API

转到开放路由
注册或登录您的帐户
转到分区钥匙
创建新的API密钥
复制要在配置中使用的密钥

模型建议

默认情况下，工具使用模型 openai/gpt-oss-20b:free.

推荐型号：

openai/gpt-oss-20b:free （默认）-质量好的免费模型
openai/gpt-oss-120b 更强大的模型，用于复杂的任务
openai/gpt-4o-mini -OpenAI的快速经济模型
openai/gpt-4o -最大质量的最强大型号

您可以通过环境变量指定模型 AI_MODEL 在MCP服务器配置中。

连接Cursor IDE

配置MCP服务器

添加到MCP配置中（~/.cursor/mcp.json):

扩展配置

要使用其他选项完全配置：

{
    "mcpServers": {
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "API_KEY": "sk-or-v1-xxxxxxxxxxxxxx",
                "API_URL": "https://openrouter.ai/api/v1",
                "API_PROVIDERS": "Cerebras",
                "LOG_LEVEL": "DEBUG",
                "AI_MODEL": "openai/gpt-oss-20b:free",
                "AI_MAX_TOKENS": "50000",
                "AI_TEMPERATURE": "0.7",
                "TIMEOUT_API_REQUEST": "30000",
                "TIMEOUT_VALIDATION": "60000",
                "PROMPTS_PATH": "./custom-prompts"
            }
        }
    }
}

连接检查

设置后 mcp.json:

重新启动Cursor IDE 下载新配置
检查状态 在MCP面板（通常在IDE的底部）
使用工具 通过cursor命令或自动完成

解决连接问题

如果MCP服务器未连接：

# Проверьте, что пакет установлен
npx mcp-validator --version

# Проверьте конфигурацию
cat ~/.cursor/mcp.json | jq '.mcpServers["mcp-validator"]'

# Проверьте логи в Cursor
# Откройте Developer Tools (Cmd+Option+I) и посмотрите консоль

光标规则

Cursor IDE的现成规则和工作流程可以在单独的存储库中找到：

👉 赛博海象/光标规则

存储库包括：

工作流程规则（Code，Prompt，AI-Docs，Critique）
架构模板（FSD，Layered Library等）
编码和文件标准
git workflow命令

环境变量

🔑 强制性

变种描述举例 | -------------------- | ----------------------- | ------------------------- | | OPENROUTER_API_KEY OpenRouter的API密钥 sk-or-v1-xxxxxxxxxxxxxx |

⚙️ 基本设置

≫变量≫描述≫默认值≫可能值≫ | -------------- | -------------------------------- | ------------- | ----------------------------------- | | NODE_ENV 周三执行。 development | development, production, test | | LOG_LEVEL 日志级别 INFO | DEBUG, INFO, WARN, ERROR | | PROMPTS_PATH 通往用户的道路 prompts 任何路径到文件夹

🤖 AI模型设置

≫变量≫描述≫默认≫范围≫ | ---------------- | ------------------------------- | ------------------------- | ------------------------------------------- | | AI_MODEL AI模型用于验证 openai/gpt-oss-20b:free 任何OpenAI兼容的供应商模型 | AI_MAX_TOKENS 最大数量的代币 100000 | 1-1000000 | | AI_TEMPERATURE 产生温度 0.5 | 0.0-2.0 |

🌐 API设置

≫变量≫描述≫默认值≫示例值≫ | --------------- | ------------------------------------------- | ------------------------------ | ----------------------------- | | API_KEY OpenAI兼容提供商的API密钥 sk-or-v1-xxx 任何有效的钥匙 | API_URL OpenAI兼容API的URL https://openrouter.ai/api/v1 任何有效的URL | API_PROVIDERS OpenRouter供应商列表以逗号分隔。 Cerebras, Cerebras,OpenAI |

支持的提供商：

开放路由 （默认）： https://openrouter.ai/api/v1
- API_程序：允许您明确指定OpenRouter提供程序（Cerebras、OpenAI、QWEN、Meta）
- 如果未指定，OpenRouter将自动选择提供商
开放人工智能: https://api.openai.com/v1
安thropic克劳德: https://api.anthropic.com/v1
其他OpenAI兼容的API

⏱️ 超时设置

变量→描述→默认值→ | --------------------- | ------------------------------ | ------------ | ------------ | | TIMEOUT_API_REQUEST –请求API超时。 30000 毫秒。 | TIMEOUT_VALIDATION 验证过程超时。 30000 毫秒。

🔧 MCP服务器设置

变量描述为默认值。 | ------------------------ | -------------------- | -------------------------------- | | MCP_SERVER_NAME MCP服务器名称 mcp-validator | | MCP_SERVER_DESCRIPTION 服务器描述 Production-ready MCP validator | | MCP_PROTOCOL_VERSION MCP协议版本 2024-11-05 | | MCP_SERVER_VERSION 服务器版本 package.json |

🧪 开发设置

变量描述默认值→ | -------------- | --------------------------- | ------------ | --------------- | | MCP_E2E_TEST E2E测试标志 false | true, false | | NODE_PATH 解决模块的方法 "" 去文件夹的路

🚀 高级设置

变量→描述→默认值→ | ----------------------- | ------------------------------ | ------------ | ------------ | | MAX_PARALLEL_REQUESTS 最大的并行请求 5 数量。 | HEARTBEAT_INTERVAL 心跳间隔 30000 毫秒。 | REQUEST_BUFFER_SIZE 查询缓冲区大小 1048576 字节（1MB）

🔧 隐藏/内部变量

这些变量由内部系统使用，通常不需要配置：

ÐÐÐÐÐÐÐÐÐÐÐÐÐ | ----------------------------- | ----------------------------- | ----------------------------------------- | ---------------- | | OPENROUTER_MOCK_CLIENT_PATH –通往测试客户MOC的道路→ end-to-end/mocks/openrouter-test-client e2e测试

MCP工具

成功连接MCP服务器后，Cursor IDE将提供以下工具：

💡 如何使用： 在Cursor IDE中，MCP工具可通过以下方式获得：

自动补充 -开始打印工具名称

命令 -使用 @ 调用工具

上下文菜单 -右键单击文件/代码

1️⃣ 通用验证

验证代码：

{
  "validationType": "code",
  "input": {
    "type": "content",
    "data": "export function test() { return 42; }"
  },
  "language": "typescript"
}

测试验证：

{
  "validationType": "tests",
  "input": {
    "type": "file",
    "data": "/path/to/test.spec.ts"
  },
  "language": "typescript"
}

自定义验证：

{
  "validationType": "custom",
  "input": {
    "type": "content",
    "data": "Your content here"
  },
  "customPrompt": "Check if this code follows our team conventions",
  "language": "typescript"
}

2️⃣ Test-Prompt-一致性测试

{
  "prompt": "Напиши функцию сортировки массива",
  "iterations": 5,
  "context": "Тест консистентности ответов",
  "timeout": 30000
}

结果将显示：

响应一致性（score 0-100）
运行时异常
重复的响应模式
每个迭代的详细报告

3️⃣ 验证信息

{
  "input": {
    "type": "content",
    "data": "TypeScript был создан Microsoft в 2012 году"
  },
  "context": "Проверка исторических фактов"
}

通过三个并行的人工智能检查和一个组合报告来验证信息的可靠性。

4️⃣ 验证-交互式验证

{
  "filePath": "/path/to/file.ts",
  "language": "typescript"
}

启动交互式模式，通过Elicitation（IDE中的对话框）选择验证类型。

MCP提示

MCP验证器提供5个现成的插件，以快速启动验证：

#22312；的描述，论据。 | --- | --- | --- | | validate-code 验证代码 filePath, focus （质量/安全/性能/全部）| | validate-tests 验证测试 filePath | | validate-architecture 建筑认证 filePath | | test-consistency | Тест консистентности промпта | prompt, iterations (3-10) | | verify-facts 核实事实。 text |

使用Cursor：

/validate-code filePath=/src/utils.ts focus=quality

MCP资源

MCP验证器提供4种资源来获取信息：

ÐURIÐÐÐÐÐÐÐÐÐÐÐ | --- | --- | --- | | validator://config 当前验证器配置 application/json | | validator://prompts/{type} –用于指定验证类型的PROMPT。 text/markdown | | validator://languages 支持的语言列表 application/json | | validator://help 工具的帮助 text/markdown |

资源读取示例：

// Получить конфигурацию
const config = await client.readResource("validator://config");

// Получить промпт валидации кода
const prompt = await client.readResource("validator://prompts/code");

HTTP 模式

MCP验证器支持流式HTTP传输，以便与Web应用程序集成。

设置HTTP模式：

{
    "mcpServers": {
        "mcp-validator": {
            "command": "npx",
            "args": ["-y", "mcp-validator"],
            "env": {
                "OPENROUTER_API_KEY": "sk-or-v1-xxx",
                "MCP_TRANSPORT": "http",
                "MCP_HTTP_PORT": "8080",
                "MCP_HTTP_HOST": "0.0.0.0"
            }
        }
    }
}

Endpoints：

方法，道路，描述。 | --- | --- | --- | | POST | /mcp –JSON-RPC请求MCP服务器› | GET | /mcp #24212；的活动。 | DELETE | /mcp 会议闭幕。 | GET | /health 检查服务器状态。

查询示例：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

交互式验证

工具 validate-interactive 使用MCP Elicitation进行交互式验证类型选择。

它是如何工作的：

使用文件路径调用工具
IDE将显示一个对话框，选择验证类型
选择所需的类型（代码、测试、体系结构、Prompts、文档）
验证将自动启动

优点：

不需要记住验证类型
通过UI快速选择
支持取消操作

使用示例：

{
  "filePath": "/src/components/Button.tsx",
  "context": "Проверка компонента перед коммитом"
}

如果验证类型为显式（validationType），不会出现对话框。

CLI 模式

# Показать справку
mcp-validator --help

# Показать версию
mcp-validator --version

局部起动

安装

npm install mcp-validator
# или
yarn add mcp-validator

配置环境变量

创建文件 .env 在项目的根：

# Обязательные настройки
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxx

# Основные настройки
NODE_ENV=production
LOG_LEVEL=INFO
PROMPTS_PATH=./custom-prompts

# Настройки AI
DEFAULT_AI_MODEL=openai/gpt-4o-mini
AI_MAX_TOKENS=50000
AI_TEMPERATURE=0.7

# Таймауты
VALIDATION_TIMEOUT=60000
PARALLEL_TEST_TIMEOUT=180000

# MCP сервер
MCP_SERVER_NAME=my-validator
MCP_SERVER_DESCRIPTION="Custom MCP validator for my project"

启动MCP服务器

# Запуск через npx (рекомендуется)
npx mcp-validator

# Или установка глобально
npm install -g mcp-validator
mcp-validator

# Локальная разработка
yarn start

工艺堆栈

TypeScript 5.9.3 -整个代码库的严格类型化
Node.js 16+ 支持通过 undici （HTTP客户端）和 dotenv （环境变量）
@模型上下文协议/sdk 1.20.0 官方MCP SDK与Cursor集成
OpenAI SDK 6.3.0 简化代理架构
十一 5.28.4 -与Node.js 16+兼容的HTTP客户端（取代内置客户端） fetch)
Dotenv 17.2.3 -从环境变量加载 .env 文件
zod 4.1.12 -使用TypeScript类型运行时验证电路

追加资源

模型上下文协议
OpenRouter文档
光标IDE
光标规则 -Cursor IDE的现成规则和工作流程
更新日志 -变化历史