Meshseeks

🚀 🟦 MeshSeeks - 我是MeshSeeks，看过来！

MeshSeeks 能够生成专门的 AI 代理，这些代理可以并行工作，以解决复杂的编码问题。就像启发我们命名的那些乐于助人的蓝色生物一样，每个代理都只有一个目的：完成分配给它们的任务，并帮助你取得成功。它基于 grahama1970/claude-code-mcp-enhanced 构建，其分布式智能灵感源自 Claude Research。

🚀 快速开始

60 秒快速体验

想立即看到 MeshSeeks 的实际效果吗？ 以下是最快的途径：

# 1. 克隆并构建（30 秒）
git clone https://github.com/twalichiewicz/meshseeks.git && cd meshseeks && npm install && npm run build

# 2. 获取配置文件路径
echo "添加到: $(echo ~/Library/Application\ Support/Claude/claude_desktop_config.json)"

# 3. 复制此配置（修改路径）
echo '{
  "mcpServers": {
    "meshseeks": {
      "command": "node",
      "args": ["'$(pwd)'/dist/mesh-server.js"]
    }
  }
}'

然后重启 Claude Desktop 并尝试："Use mesh_status to check MeshSeeks"

完整安装指南：跳转至快速开始（5 分钟）

5 分钟快速开始

前提条件

1. Node.js v20+ - 通过 nvm 或 fnm 进行安装。
2. Claude CLI - 安装并使用权限运行一次：

npm install -g @anthropic-ai/claude-code
claude --dangerously-skip-permissions  # 运行一次并接受条款

安装 MeshSeeks

选项 1：从 GitHub 安装（推荐）

# 克隆并构建
git clone https://github.com/twalichiewicz/meshseeks.git
cd meshseeks
npm install
npm run build

# 添加到你的 MCP 配置（见以下路径）

选项 2：直接从 npm 安装（即将推出）

# 注意：该包将以 @twalichiewicz/meshseeks 发布
npm install -g @twalichiewicz/meshseeks

配置客户端

将 MeshSeeks 添加到你的 MCP 配置文件中： 查找配置文件：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（Mac）
• Cursor：~/.cursor/mcp.json
• Windsurf：~/.codeium/windsurf/mcp_config.json

添加此配置：

{
  "mcpServers": {
    "meshseeks": {
      "command": "node",
      "args": ["/absolute/path/to/meshseeks/dist/mesh-server.js"],
      "env": {
        "MCP_MESH_MAX_AGENTS": "5",
        "MESHSEEKS_CATCHPHRASE": "true"
      }
    }
  }
}

提示：将 /absolute/path/to/meshseeks 替换为你克隆步骤中的实际路径。

验证安装

1. 重启客户端（Claude Desktop、Cursor 或 Windsurf）
2. 测试 MeshSeeks：在新聊天中输入：

Use the mesh_status tool to show me the MeshSeeks network status

3. 查看实际效果：

Use mesh_solve_problem to create a simple Python calculator with tests

这样就完成了！MeshSeeks 已准备好加速你的编码任务。🎉

首个任务建议

尝试以下命令，体验并行代理的强大功能：

• "Use mesh_analyze_problem to analyze the architecture of [your project]"
• "Use mesh_execute_tasks to implement a REST API with full CRUD operations"
• "Use mesh_solve_problem to refactor this code with tests and documentation"

✨ 主要特性

代理网状网络

• 并行处理：多个 Claude 代理可同时处理不同方面的任务。
• 专业角色：包括分析、实现、测试、文档编写和调试等代理。
• 4 倍上下文容量：每个代理都有自己的 200k 令牌上下文窗口。
• 智能协调：进行依赖管理和智能任务分配。
• 结果合成：自动聚合结果并解决冲突。
• 🆕 实时状态面板：实时可视化反馈可防止出现“卡顿”现象。

增强的 MCP 工具

除了 Graham 的增强工具外，网状网络还提供以下功能：

• mesh_analyze_problem - 将复杂问题分解为代理任务。
• mesh_execute_tasks - 执行带有依赖管理的任务。
• mesh_solve_problem - 使用多种策略进行端到端问题解决。
• mesh_status - 监控网络性能和代理指标。

🆕 实时状态面板

不再有黑屏！新的状态面板提供以下功能：

• 实时更新：每秒刷新一次可视化进度。
• 代理跟踪：查看哪些代理处于活动状态以及它们正在处理的任务。
• 任务进度：进度条和依赖关系可视化。
• 性能指标：吞吐量、计时和成功率。
• 活动日志：最近的事件和状态变化。 运行 npm run demo:status 查看实际效果！

📦 安装指南

详细安装指南

如需高级配置选项、故障排除或手动设置，请参阅我们的 全面安装指南。

重要的首次设置：接受权限

在 MCP 服务器能够成功使用 claude_code 工具之前，你必须首先手动运行一次 Claude CLI，并使用 --dangerously-skip-permissions 标志，登录并接受条款。 这是 Claude CLI 的一次性要求。

npm install -g @anthropic-ai/claude-code

claude --dangerously-skip-permissions

按照提示接受条款。完成此操作后，MCP 服务器将能够以非交互方式使用该标志。 macOS 可能会在工具首次运行时要求各种文件夹权限，首次运行可能会失败。后续运行将正常工作。

连接到 MCP 客户端

设置服务器后，你需要配置 MCP 客户端（如 Cursor、Claude Desktop 或其他使用 mcp.json 或 mcp_config.json 的客户端）。

示例 MCP 配置文件

以下是如何将 Claude Code MCP 服务器添加到 .mcp.json 文件的示例：

{
  "mcpServers": {
    "Local MCP Server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "dist/server.js"
      ],
      "env": {
        "MCP_USE_ROOMODES": "true",
        "MCP_WATCH_ROOMODES": "true",
        "MCP_CLAUDE_DEBUG": "false"
      }
    },
    "other-services": {
      // 你的其他 MCP 服务
    }
  }
}

MCP 配置位置

配置通常在 JSON 文件中完成。文件名和位置可能因客户端而异。

• Cursor：
  • macOS：~/.cursor/mcp.json
  • Windows：%APPDATA%\\Cursor\\mcp.json
  • Linux：~/.config/cursor/mcp.json
• Windsurf：
  • macOS：~/.codeium/windsurf/mcp_config.json
  • Windows：%APPDATA%\\Codeium\\windsurf\\mcp_config.json
  • Linux：~/.config/.codeium/windsurf/mcp_config.json

（注意：在某些混合设置中，如果也安装了 Cursor，这些客户端可能会回退到使用 Cursor 的 ~/.cursor/mcp.json 路径。如果使用 Codeium 扩展，请优先使用 Codeium 特定的路径。） 如果文件不存在，请创建它。

💻 使用示例

基础用法

# 查看 MeshSeeks 网络状态
Use the mesh_status tool to show me the MeshSeeks network status

# 创建一个简单的 Python 计算器并进行测试
Use mesh_solve_problem to create a simple Python calculator with tests

高级用法

网状网络使用示例

基本问题分析

Use mesh_analyze_problem to plan how to implement a REST API with authentication, database integration, and tests.
workFolder: /path/to/project

端到端问题解决

Use mesh_solve_problem to create a complete e-commerce backend with:
- User authentication and authorization
- Product catalog with categories
- Shopping cart functionality  
- Order processing
- Payment integration
- Unit and integration tests
- API documentation

workFolder: /path/to/project
approach: analysis_first

协调策略

• 分析优先（默认）：适用于需要系统方法的明确定义的问题。
• 并行探索：适用于需要多个视角的研究任务：

approach: parallel_exploration

• 迭代改进：适用于具有反馈循环的复杂重构任务：

approach: iterative_refinement

任务转换器使用示例

创建任务文件（tasks/api_validation.md）

# Task 001: API Endpoint Validation

## Objective
Validate all API endpoints work with real database connections.

## Requirements
1. [ ] All endpoints must use real database
2. [ ] No mock data in validation

## Core API Tasks
- [ ] Validate `api/users.py`
  - [ ] Change directory to project and activate .venv
  - [ ] Test user creation endpoint
  - [ ] Test user retrieval endpoint
  - [ ] Verify JSON responses

转换为 MCP 任务

{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/project/tasks/api_validation.md"
  }
}

转换器显示实时进度

[Progress] Loading task file...
[Progress] Validating markdown structure...
[Progress] Converting 27 validation tasks...
[Progress] Task 1/27: Converting core/constants.py
[Progress] Task 2/27: Converting core/arango_setup.py
...
[Progress] Conversion complete!

转换器将通用指令转换为精确命令

• “Change directory to project and activate .venv” 变为：

cd /home/user/project && source .venv/bin/activate

• 所有路径都解析为绝对路径，所有命令都可完全执行，无歧义。

执行转换后的任务

返回的任务包含精确的可执行命令，可使用 claude_code 工具按顺序执行。

任务编排模式使用示例

回旋镖模式（Claude Desktop ⟷ Claude Code）

// 任务 1 - 查找食谱
{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Search for a classic chocolate cake recipe. Find one with good reviews.",
    "parentTaskId": "cake-recipe-123",
    "returnMode": "summary",
    "taskDescription": "Find Chocolate Cake Recipe"
  }
}

// 任务 2 - 转换测量单位
{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Convert the measurements in this recipe from cups to grams:\n\n- 2 cups flour\n- 1.5 cups sugar\n- 3/4 cup cocoa powder",
    "parentTaskId": "cake-recipe-123",
    "returnMode": "summary",
    "taskDescription": "Convert Recipe Measurements"
  }
}

自我编排模式（Claude Code 作为编排器）

详细实现指南及示例脚本和任务结构，请参阅 Self-Orchestration with Claude Code。

Roo 模式集成使用示例

// 配置 .roomodes 文件
{
  "customModes": [
    {
      "slug": "coder",
      "name": "💻 Coder",
      "roleDefinition": "You are a coding specialist who writes clean, efficient code.",
      "apiConfiguration": {
        "modelId": "claude-3-sonnet-20240229"
      }
    },
    {
      "slug": "designer", 
      "name": "🎨 Designer",
      "roleDefinition": "You are a design specialist focused on UI/UX solutions."
    }
  ]
}

// 使用模式进行请求
{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
    "workFolder": "/path/to/project",
    "mode": "coder"
  }
}

📚 详细文档

工具说明

claude_code 💬

使用 Claude Code CLI 直接执行提示，并使用 --dangerously-skip-permissions。 参数：

• prompt（字符串，必需）：要发送给 Claude Code 的提示。
• workFolder（字符串，可选）：Claude CLI 执行的工作目录，使用文件操作或引用任何文件时必需。
• parentTaskId（字符串，可选）：创建此任务的父任务 ID（用于任务编排/回旋镖模式）。
• returnMode（字符串，可选）：结果返回方式：'summary'（简洁）或 'full'（详细）。默认为 'full'。
• taskDescription（字符串，可选）：任务的简短描述，用于在编排工作流中更好地组织和跟踪。
• mode（字符串，可选）：当 MCP_USE_ROOMODES=true 时，指定要使用的 Roo 模式（例如，"boomerang-mode"、"coder"、"designer" 等）。

health 🩺

返回 Claude Code MCP 服务器的健康状态、版本信息和当前配置。 示例健康检查请求：

{
  "toolName": "claude_code:health",
  "arguments": {}
}

示例响应：

{
  "status": "ok",
  "version": "1.12.0",
  "claudeCli": {
    "path": "claude",
    "status": "available"
  },
  "config": {
    "debugMode": true,
    "heartbeatIntervalMs": 15000,
    "executionTimeoutMs": 1800000,
    "useRooModes": true,
    "maxRetries": 3,
    "retryDelayMs": 1000
  },
  "system": {
    "platform": "linux",
    "release": "6.8.0-57-generic",
    "arch": "x64",
    "cpus": 16,
    "memory": {
      "total": "32097MB",
      "free": "12501MB"
    },
    "uptime": "240 minutes"
  },
  "timestamp": "2025-05-15T18:30:00.000Z"
}

convert_task_markdown 📋

将 markdown 任务文件转换为 Claude Code MCP 兼容的 JSON 格式。 参数：

• markdownPath（字符串，必需）：要转换的 markdown 任务文件的路径。
• outputPath（字符串，可选）：保存 JSON 输出的路径。如果未提供，则直接返回 JSON。 示例请求：

{
  "toolName": "claude_code:convert_task_markdown",
  "arguments": {
    "markdownPath": "/home/user/tasks/validation.md",
    "outputPath": "/home/user/tasks/validation.json"
  }
}

示例使用场景

基本代码操作

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nRefactor the function foo in main.py to be async.",
    "workFolder": "/path/to/project"
  }
}

任务编排（回旋镖模式）

// 父任务请求
{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nOrchestrate the implementation of a new API endpoint with the following subtasks:\n1. Create database models\n2. Implement API route handlers\n3. Write unit tests\n4. Document the API",
    "workFolder": "/path/to/project"
  }
}

// 子任务请求（由父任务生成）
{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate database models for the new API endpoint as specified in the requirements.",
    "workFolder": "/path/to/project",
    "parentTaskId": "task-123",
    "returnMode": "summary",
    "taskDescription": "Database model creation for API endpoint"
  }
}

特殊模式请求

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
    "workFolder": "/path/to/project",
    "mode": "coder"
  }
}

🔧 技术细节

性能基准 - 快 3.64 倍！

实时测试结果：MeshSeeks 在 14.0 秒 内完成了一个复杂的电子商务 API 开发任务，而顺序执行的 Claude Code 则需要 51.0 秒 - 性能提升了 3.64 倍！🚀

最新基准测试结果（真实测试数据）

指标	MeshSeeks	顺序执行的 Claude	优势
执行时间	14.0s	51.0s	快 3.64 倍 ⚡
节省时间	-	-	37.0 秒 ⏰
效率提升	3.3 倍并行	1.0 倍串行	+264% 📈
成功率	100%	100%	质量相同 ✅
使用的代理	5 个并行	5 个顺序	相同工作，更短时间 🎯

按复杂度划分的性能表现

问题类型	单代理	网状网络	加速比
代码分析	2 - 5 分钟	30 - 60 秒	3 - 5 倍
功能实现	10 - 20 分钟	3 - 8 分钟	2 - 4 倍
全面重构	30 - 60 分钟	8 - 15 分钟	4 - 6 倍
完整项目设置	45 - 90 分钟	12 - 25 分钟	3 - 5 倍

📊 查看完整性能分析 | 📈 查看可视化图表

MeshSeeks 更快的原因

• 并行处理：5 个专业代理同时工作，而不是排队等待。
• 专家专业化：每个代理针对特定任务进行优化（分析、实现、测试、文档编写、安全）。
• 上下文效率：通过每个代理的分布式 200k 令牌上下文实现 4 倍有效容量。
• 智能合成：智能组合专业输出。
• 错误隔离：单个代理失败不会导致整个流程崩溃。

运行你自己的基准测试

git clone git@github.com:twalichiewicz/meshseeks.git
cd meshseeks
npm install
node benchmarks/scripts/mesh-performance-test.js

增强的可靠性特性

1. 心跳机制与超时预防

为防止长时间运行操作期间客户端超时：

• 添加了可配置的心跳机制，每 15 秒发送一次进度更新。
• 实现了执行时间跟踪和报告。
• 通过环境变量添加了可配置的超时参数。

2. 强大的错误处理与重试机制

为瞬态错误添加了智能重试逻辑：

• 实现了具有可配置参数的自动重试。
• 添加了错误分类以识别可重试问题。
• 创建了详细的错误报告和跟踪。

3. 请求跟踪系统

实现了全面的请求生命周期管理：

• 为每个请求添加了唯一 ID。
• 创建了进行中请求的跟踪。
• 确保在完成或失败时进行适当的清理。

4. 优雅关机

添加了适当的进程终止处理：

• 为 SIGINT 和 SIGTERM 实现了信号处理程序。
• 添加了进行中请求的跟踪。
• 创建了等待逻辑以实现干净关机。
• 确保在退出时进行适当的清理。

5. 配置缓存与热重载

为配置添加了性能优化：

• 实现了 roomodes 文件的缓存。
• 根据文件更改添加了自动失效机制。
• 创建了可配置的文件监视机制。

配置选项

服务器的行为可以使用以下环境变量进行自定义：

变量	描述	默认值
CLAUDE_CLI_PATH	Claude CLI 可执行文件的绝对路径	自动检测
MCP_CLAUDE_DEBUG	启用详细的调试日志记录	false
MCP_HEARTBEAT_INTERVAL_MS	进度报告之间的间隔	15000（15 秒）
MCP_EXECUTION_TIMEOUT_MS	CLI 执行的超时时间	1800000（30 分钟）
MCP_MAX_RETRIES	瞬态错误的最大重试次数	3
MCP_RETRY_DELAY_MS	重试尝试之间的延迟	1000（1 秒）
MCP_USE_ROOMODES	启用 Roo 模式集成	false
MCP_WATCH_ROOMODES	文件更改时自动重新加载 .roomodes	false
网状网络变量
MCP_MESH_MAX_AGENTS	最大并发代理数	5
MCP_MESH_TIMEOUT	代理执行超时时间	300000（5 分钟）
MCP_MESH_VERBOSE	启用详细的代理日志记录	false

这些变量可以在你的 shell 环境中设置，也可以在 mcp.json 服务器配置的 env 块中设置。

🎯 关键用例

本服务器通过其统一的 claude_code 工具，为你的 AI 直接提供对 Claude Code CLI 的访问，从而解锁了广泛的强大功能。以下是一些你可以实现的示例：

1. 代码生成、分析与重构：
   • "Generate a Python script to parse CSV data and output JSON."
   • "Analyze my_script.py for potential bugs and suggest improvements."
2. 文件系统操作（创建、读取、编辑、管理）：
   • 创建文件："Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db"
   • 编辑文件："Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'."
   • 移动/复制/删除："Your work folder is /Users/steipete/my_project\n\nMove the file 'report.docx' from the 'drafts' folder to the 'final_reports' folder and rename it to 'Q1_Report_Final.docx'."
3. 版本控制（Git）：
   • "Your work folder is /Users/steipete/my_project\n\n1. Stage the file 'src/main.java'.\n2. Commit the changes with the message 'feat: Implement user authentication'.\n3. Push the commit to the 'develop' branch on origin."
4. 运行终端命令：
   • "Your work folder is /Users/steipete/my_project/frontend\n\nRun the command 'npm run build'."
   • "Open the URL https://developer.mozilla.org in my default web browser."
5. 网络搜索与总结：
   • "Search the web for 'benefits of server-side rendering' and provide a concise summary."
6. 复杂的多步骤工作流：
   • 自动化版本升级、更新变更日志和标记发布："Your work folder is /Users/steipete/my_project\n\nFollow these steps: 1. Update the version in package.json to 2.5.0. 2. Add a new section to CHANGELOG.md for version 2.5.0 with the heading '### Added' and list 'New feature X'. 3. Stage package.json and CHANGELOG.md. 4. Commit with message 'release: version 2.5.0'. 5. Push the commit. 6. Create and push a git tag v2.5.0."
7. 修复有语法错误的文件：
   • "Your work folder is /path/to/project\n\nThe file 'src/utils/parser.js' has syntax errors after a recent complex edit that broke its structure. Please analyze it, identify the syntax errors, and correct the file to make it valid JavaScript again, ensuring the original logic is preserved as much as possible."
8. 与 GitHub 交互（例如，创建拉取请求）：
   • "Your work folder is /Users/steipete/my_project\n\nCreate a GitHub Pull Request in the repository 'owner/repo' from the 'feature-branch' to the 'main' branch. Title: 'feat: Implement new login flow'. Body: 'This PR adds a new and improved login experience for users.'"
9. 与 GitHub 交互（例如，检查 PR CI 状态）：
   • "Your work folder is /Users/steipete/my_project\n\nCheck the status of CI checks for Pull Request #42 in the GitHub repository 'owner/repo'. Report if they have passed, failed, or are still running."

⚠️ 重要提示

请记住，在进行文件系统或 Git 操作的提示中，要提供当前工作目录（CWD）上下文（例如，"Your work folder is /path/to/project\n\n...your command..."）。

🧪 测试与开发

全面测试套件

MeshSeeks 包含一个完整的测试框架，包括：

• 单元测试 - 测试核心协调器功能：

npm run test:unit

• 集成测试 - 测试 MCP 服务器工具：

npm run test:integration

• 错误处理测试 - 测试失败场景：

npm run test:errors

• 性能测试 - 测试可扩展性和并发性能：

npm run test:performance

• 运行所有测试 - 完整测试套件：

npm run test:all

状态面板演示

查看实时状态面板的实际效果：

npm run demo:status

开发脚本

npm run dev:mesh       # 在开发模式下运行网状服务器
npm run build:mesh     # 为生产环境进行构建
npm run test:mesh      # 运行基本的网状测试

🔧 故障排除

• “Command not found”（claude-code-mcp）：如果全局安装，请确保 npm 全局 bin 目录在系统的 PATH 中。如果使用 npx，请确保 npx 本身正常工作。
• “Command not found”（claude 或 ~/.claude/local/claude）：确保 Claude CLI 已正确安装。运行 claude/doctor 或查看其文档。
• 权限问题：确保你已完成“重要的首次设置”步骤。
• 服务器的 JSON 错误：如果 MCP_CLAUDE_DEBUG 为 true，错误消息或日志可能会干扰 MCP 的 JSON 解析。将其设置为 false 以进行正常操作。
• ESM/导入错误：确保你使用的是 Node.js v20 或更高版本。
• 客户端超时：对于长时间运行的操作，服务器每 15 秒发送一次心跳消息以防止客户端超时