Shadow Runner MCP服务器
Shadow Runner MCP服务器是一个与模型上下文协议（MCP）兼容的后端，它安全地封装了 shadow-runner 图书馆。它为人工智能代理和外部客户端公开了一个HTTP API，以便在没有用户风险的情况下以静默方式评估实验代码更改。
______________________________________________________________________
📖 目录
______________________________________________________________________
🔍 概述与架构
该架构由两个主要层组成：
- 传输层（Express.js）：轻量级、快速的Node.js HTTP服务器映射
POST /mcp/compare端点。 - Diff发动机(
mcp/tools.js)：一种深度移植的差分算法，可以分解返回的执行输出中的结构差异。
该系统保证未经测试的更改（“newOutput”）可以与当前规范输出（“oldOutput”）一起安全地通过线路发送并进行差异化。任何不匹配都会被检测到并在结构上报告。
______________________________________________________________________
🚀 分步安装
按照以下步骤在本地设置服务器或为生产做好准备。
步骤1：克隆存储库
将此目录克隆到您的安全环境中。由于这会处理内部系统评估，请将此代码库保存在私有存储库或安全的网络边界内。
git clone https://github.com/devmubs/shadow-runner-mcp.git
cd shadow-runner-mcp步骤2：安装节点依赖关系
确保您的系统上安装了Node.js（v16.0.0或更高版本）。
npm install*这将安装Express（用于路由）和dotenv（用于秘密注入）。*
步骤3：配置环境变量
创建一个 .env 根目录中的文件。 切勿将此文件提交到版本控制。
touch .env填充 .env 使用您的特定配置文件：
PORT=3000
API_KEY=your_highly_secure_token_here步骤4：启动服务器
启动服务器进程。
node server.js控制台将确认它正在监听： Shadow-Runner MCP Server listening on port 3000
______________________________________________________________________
🛠 使用指南
公开的API简单且无状态。
单端点 POST /mcp/compare
发送一个JSON有效载荷，其中包含旧的已知良好输出和新的实验输出。
请求示例：
curl -X POST http://localhost:3000/mcp/compare \
-H "Authorization: Bearer your_highly_secure_token_here" \
-H "Content-Type: application/json" \
-d '{
"oldOutput": {
"status": "success",
"data": { "id": 1, "active": true }
},
"newOutput": {
"status": "success",
"data": { "id": "1", "active": true }
}
}'示例响应：
{
"match": false,
"diffCount": 1,
"diffs": [
{
"path": "$.data.id",
"oldValue": 1,
"newValue": "1"
}
]
}______________________________________________________________________
🧠 深潜：它是如何工作的
Shadow Runner MCP服务器由两个主要支柱组成： server.js 和 mcp/tools.js.
1.HTTP层(server.js)
- 快速实例化：服务器使用Express
express.json({ limit: '10mb' })以安全地解析传入的高度嵌套的有效载荷比较，而不会崩溃。 - 身份验证保护：自定义中间件检查
Authorization头球请求缺少有效Bearer立即收到401 Unauthorized，保护内部应用程序状态免受公共探测。 - 有效载荷验证：The
/mcp/compare控制器断言两者oldOutput和newOutput明确存在于req.body以防止在上进行不必要的处理或假阳性匹配undefined价值观。
2.Diff发动机(mcp/tools.js)
核心功能由递归驱动 deepDiff(oldVal, newVal, path) 机制：
- 引用相等：通过以下方式立即评估琐碎的相同对象结构
Object.is(). - 类型防护：如果原始数据类型完全不匹配，则进行短路比较（例如。，
Number对比String). - 日期和正则表达式：自定义解析器检查严格格式化的实例。通过纪元计时进行日期匹配
getTime()，以及RegEx通过.toString(). - 数组：按索引递增地评估两个集合。它固有地支持可变长度数组，并发出严格映射到缺失边界的差异，识别
undefined边界不匹配值$[4]. - 嵌套对象：构建针对两个输入映射的统一密钥集。它通过连接字符串路径递归遍历树(
$.user.profile.age).任何域中缺少的任何密钥都会明确导致检测到的差异。
所有递归识别的结构不一致性都会按顺序冒泡并绑定到 compareOutputs，用 try/catch 安全逻辑，以确保Node进程在任意树序列化过程中永远不会崩溃。
______________________________________________________________________
📜 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。