Pipewrench (Yak Stacks)

🔧 管钳

MCP和编排诊断与调试工具

PipeWrench诊断您的MCP（模型上下文协议）服务器未连接的原因，并对Maestro编排器安装进行故障排除。它测试stdio管道，检测成帧问题，验证协议握手，检查编排器配置，并告诉您发生了什么故障。

╔══════════════════════════════════════════════════════════════╗
║                         PipeWrench                           ║
║           MCP Connection Diagnostic & Debug Tool             ║
╚══════════════════════════════════════════════════════════════╝

为什么选择PipeWren？

MCP服务器通过stdio进行通信，以及 Windows上的stdio已损坏 在许多环境中：

• 电子应用程序在生成子进程时损坏了管道
• npx 添加破坏stdio缓冲的层
• 不同的服务器使用不同的消息框架（行分隔与内容长度）
• 错误是无声的-服务器启动但从不响应

管钳告诉你到底出了什么问题：

✓ PASS  Server process spawned
✓ PASS  No stdout pollution detected
✓ PASS  Framing detected: line-delimited
✗ FAIL  Initialize response received
        → Timeout after 15000ms
        💡 Server may expect Content-Length framing

快速开始

# Clone the repo
git clone https://github.com/YakStacks/Pipewrench.git
cd Pipewrench

# Test an MCP server
node cli.js doctor "mcp-stdio:npx -y @modelcontextprotocol/server-memory"

或全局安装：

npm install -g pipewrench
pipewrench doctor "mcp-stdio:npx -y @modelcontextprotocol/server-memory"

命令

doctor -诊断连接问题

对任何目标运行全面的诊断：

# MCP server over stdio
pipewrench doctor "mcp-stdio:npx -y @modelcontextprotocol/server-memory"

# MCP server with arguments
pipewrench doctor "mcp-stdio:npx -y @modelcontextprotocol/server-filesystem C:\Projects"

# MCP server over HTTP
pipewrench doctor "mcp-http:http://localhost:3000/mcp"

# Generic HTTP endpoint
pipewrench doctor "http://localhost:8080/health"

# Any command
pipewrench doctor "cmd:node server.js"

# Maestro orchestrator installation
pipewrench doctor "maestro:C:\Orchestrator"

输出：

🔧 PipeWrench MCP Diagnostics
═══════════════════════════════════════════════════════════════

Target: mcp-stdio:npx -y @modelcontextprotocol/server-memory
Status: ✅ PASSED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Connection Test Results:

  ✅ Server Spawn
     Process spawned successfully

  ✅ Stdio Pollution  
     No stderr pollution detected

  ✅ MCP Framing
     Framing: line-delimited

  ✅ JSON-RPC Validity
     JSON-RPC messages are valid

  ✅ MCP Initialize
     Protocol version: 2024-11-05
     Initialize succeeded in 1273ms

  ✅ MCP Tools List
     9 tools available

  ✅ Response Timing
     Total: 1282ms, TTFB: 1273ms

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Available Tools:
  • create_entities - Create multiple new entities in the knowledge graph
  • create_relations - Create multiple new relations between entities
  • add_observations - Add new observations to existing entities
  • delete_entities - Delete multiple entities and their relations
  • delete_observations - Delete specific observations from entities
  • delete_relations - Delete multiple relations from the knowledge graph
  • read_graph - Read the entire knowledge graph
  • search_nodes - Search for nodes in the knowledge graph
  • open_nodes - Open specific nodes in the knowledge graph

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Server Info:
  Name: memory-server
  Version: 0.6.3
  Protocol: 2024-11-05
  Transport: stdio

Health Score: 100/100 ✅

Recommendations:
  ✅ All checks passed
  ✅ Server is responding normally  
  ✅ Ready for production use

trace -捕获协议详细信息

获取详细的I/O跟踪以进行调试：

pipewrench trace "mcp-stdio:npx -y @modelcontextprotocol/server-memory"

输出：

═══════════════════════════════════════════════════════════════
                         TRACE OUTPUT
═══════════════════════════════════════════════════════════════

⏱  TIMINGS
   Duration: 1247ms
   TTFB:     892ms

🔌 MCP PROTOCOL
   Transport:   stdio
   Framing:     line-delimited
   Initialized: yes
   Tools:       3

📨 FRAMES
   [recv] {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05"...
   [recv] {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"create_enti...

proxy -TCP代理服务器

对于不能直接执行stdio的Electron应用程序，请将PipeWrench作为代理运行：

pipewrench proxy --port 9999

然后通过TCP从您的应用程序连接并发送JSON命令：

const socket = net.connect(9999, "127.0.0.1");

// Connect to MCP server
socket.write(
  JSON.stringify({
    type: "connect",
    name: "memory",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-memory"],
  }) + "\n",
);

// Send MCP request
socket.write(
  JSON.stringify({
    type: "message",
    name: "memory",
    payload: { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} },
  }) + "\n",
);

选项

pipewrench  [target] [options]

Options:
  --json          Output as JSON (for CI/scripting)
  --timeout   Set timeout (default: 10000)
  --verbose, -v   Show detailed evidence for all checks
  --port       Port for proxy server (default: 9999)

目标类型

诊断规则

MCP规则

HTTP规则

命令规则

大师规则

工作台插件

PipeWrench包括一个插件 工作台:

安装

# Copy plugin to Workbench
cp -r workbench-plugin /path/to/Workbench/plugins/pipewrench

工具

安装后，您将在Workbench中获得三个工具：

debug.mcpDoctor -完整诊断报告

{ "target": "mcp-stdio:npx -y @modelcontextprotocol/server-memory" }

debug.mcpTrace -原始协议跟踪

{ "target": "mcp-stdio:npx -y @modelcontextprotocol/server-memory" }

debug.mcpTest -快速通过/失败测试

{ "command": "npx", "args": "-y @modelcontextprotocol/server-memory" }

聊天使用情况

在Workbench中询问Claude：

• “在内存服务器上运行MCP诊断程序”
• “测试文件系统MCP服务器是否正常工作”
• “为什么我的MCP服务器没有连接？”

常见问题和修复

“等待MCP响应超时”

原因： 服务器启动但从不响应初始化请求。

修复：

1. 尝试不同的框架：一些服务器期望 Content-Length headers，其他则需要行分隔的JSON
2. 检查stdout污染：响应中断解析前的非JSON输出
3. 在Windows上：使用代理模式绕过Electron stdio问题

“服务器进程已生成，但无响应”

原因： Stdio管道连接不正确（在Windows上的Electron中很常见）。

修复： 使用 pipewrench proxy 并通过TCP连接，而不是直接生成。

“找不到命令：npx”

原因： npx不在PATH中或shell上下文错误。

修复：

1. 使用完整路径： node C:\Users\...\node_modules\.bin\mcp-server-memory
2. 全局安装： npm install -g @modelcontextprotocol/server-memory

“检测到标准污染”

原因： 服务器将非协议消息（日志、横幅）打印到stdout。

修复： 这是一个服务器错误。服务器应该只将JSON-RPC消息写入stdout。日志应转到stderr。

退出代码

JSON 输出

对于CI/CD脚本，请使用 --json:

pipewrench doctor "mcp-stdio:npx -y @modelcontextprotocol/server-memory" --json

{
  "target": { "type": "mcp-stdio", "raw": "..." },
  "timestamp": "2024-02-04T14:30:00.000Z",
  "summary": { "passed": 6, "warned": 0, "failed": 0, "total": 6 },
  "score": 100,
  "rules": [
    { "id": "mcp-server-spawned", "status": "pass", "title": "Server process spawned", "evidence": [] },
    ...
  ]
}

为什么选择“管钳”？

因为它可以修复破裂的管道。 🔧

许可证

麻省理工学院

贡献

PR欢迎！尤其是：

• 新的诊断规则
• 额外的MCP服务器兼容性
• 跨平台测试
• 文档改进

相关项目

• 工作台 -本地首个AI自动化平台
• 模型上下文协议 -PipeWrench诊断协议