Claude Subagent Communication

Claude子代理通信MCP

模型上下文协议（MCP）服务器，使Claude Code子代理能够维护持久上下文，并在单个项目中的会话之间共享知识。

概述

Claude子代理通信MCP解决了每个子代理在不了解先前工作的情况下启动的上下文隔离问题。它提供：

• 上下文连续性：子代理从以前的会话中继承相关知识
• 模式复用：成功的方法被记录并重新应用
• 减少数据重复：避免重新解释项目架构和惯例
• 学习积累：项目知识随着时间的推移而增长
• 智能体感知：利用中定义的实际子代理 .claude/agents/

主要特点

🤖 代理管理

• 自动检测来自的代理 .claude/agents/*.md 文件
• 自动将MCP访问指令添加到代理文件
• 跟踪代理绩效和专业化

🧠 上下文智能

• 基于代理历史和任务关键字的智能相关性评分
• 基于跨代理学习的特定代理上下文检索
• 令牌感知上下文格式化

📝 会话管理

• 基于模板的会话创建和验证
• 特定于代理的会话跟踪和完成
• 全面的会话元数据提取

🔄 模式管理

• 从成功会话中自动提取模式
• 跨代理模式共享与演化
• 模式适用性评分和建议

📊 性能监控

• 实时系统健康检查
• 代理性能分析
• 项目统计数据和见解

安装和设置

先决条件

• 紫外线的 包管理器(在此处安装)
• 克劳德代码CLI (在此处安装)

一个命令设置

# Production: Add from GitHub
claude mcp add --scope local claude-subagent-communication -- uvx --from git+https://github.com/cnguyen14/claude-subagent-communication claude-subagent-communication-mcp

# Local: Add from local directory (for development/testing)
claude mcp add --scope local claude-subagent-communication -- uvx --from /absolute/path/to/claude-subagent-communication claude-subagent-communication-mcp

# Alternative: Local development with uv run
git clone 
cd claude-subagent-communication  
uv sync
claude mcp add --scope local claude-subagent-communication uv run python claude_subagent_communication_mcp/server.py

验证安装

# Check if server was added
claude mcp list

# Test server health  
claude mcp get claude-subagent-communication

初始化您的项目

在要使用MCP的任何项目目录中，打开Claude Code并运行：

Initialize project context for this repository

⚠️ 重要：初始化后，重新启动子代理的Claude Code以访问MCP工具。

这将：

• 创建 .claude/ 目录结构
• 检测中的现有代理 .claude/agents/
• 将MCP指令添加到代理文件
• 设置模板和配置
• 使用上下文管理协议增强Claude.md

目录结构

初始化后，您的项目将具有：

project-root/
├── .claude/
│   ├── agents/                  # Sub-agent definitions (auto-enhanced with MCP)
│   │   ├── backend-dev.md      # Backend development specialist
│   │   ├── frontend-dev.md     # Frontend development specialist
│   │   └── ...                 # Other agents
│   ├── config.json             # MCP settings and agent metadata
│   ├── context.md              # High-level project overview
│   ├── sessions/               # Individual agent work logs
│   │   ├── backend-dev-2025-08-17-14-30-user-auth.md
│   │   └── ...
│   ├── patterns/               # Reusable approaches and solutions
│   │   ├── auth-patterns.md
│   │   └── ...
│   ├── summaries/              # Periodic knowledge rollups
│   └── templates/              # Standardized formats
├── Claude.md                   # Enhanced with MCP context management protocol
└── src/                        # Your actual project code

用法

对于家长代理人

在将任务分配给子代理之前，请使用以下工具：

// Scan available agents
const agents = await scan_agents();

// Get relevant context for a specific agent and task
const context = await get_relevant_context(
  "backend-dev",
  "Create user authentication endpoint", 
  ["src/auth/routes.py", "src/models/user.py"]
);

// Start a session for an agent
const session = await start_agent_session(
  "backend-dev",
  "Create user authentication endpoint",
  "creation"
);

对于子代理

子代理自动访问这些工具（启用MCP后）：

// Get your work history
const history = await get_agent_history("backend-dev", 30, true);

// Search for relevant context
const searchResults = await search_context(
  "authentication JWT", 
  ["session", "pattern"],
  "backend-dev"
);

// Get applicable patterns for your current task
const patterns = await get_applicable_patterns(
  "backend-dev",
  "creation", 
  ["auth", "jwt", "middleware"]
);

// Save a new pattern you discovered
await save_pattern(
  "jwt-middleware-pattern",
  "Implementation approach for JWT authentication middleware",
  "backend-dev",
  "creation",
  ["jwt", "auth", "middleware"]
);

// Complete your session with learnings
await complete_session(session_id, completed_session_content);

MCP工具参考

代理管理

• scan_agents() -检测.claude/agents中的代理/
• update_agent_instructions(agent_name) -向代理添加MCP指令
• ensure_all_agents_mcp_enabled() -为所有代理启用MCP
• init_project_context() -初始化目录结构

上下文检索

• get_relevant_context(agent_name, task_description, files) -获取特定于代理的上下文
• search_context(query, content_types, agent_name, time_range) -搜索所有上下文

会话管理

• start_agent_session(agent_name, task_description, domain) -创建新会话
• complete_session(session_id, session_data) -保存已完成的会话
• get_agent_history(agent_name, days, include_patterns) -获取代理工作历史记录

模式管理

• save_pattern(name, content, agent, domain, keywords) -保存可重用模式
• get_applicable_patterns(agent_name, domain, keywords) -查找相关模式

Claude.md增强

• enhance_claude_md() -使用MCP上下文管理协议升级Claude.md
• check_claude_md_status() -检查增强状态并获取建议

系统工具

• get_system_status() -系统健康和诊断

最佳实践

用于项目设置

1. 在中创建代理定义 .claude/agents/ 初始化前
2. 使用反映专业化的描述性代理名称
3. 文档代理能力和技术重点领域
4. 跑 init_project_context() 设置系统
5. 初始化后始终重新启动Claude Code

代理定义

• 包括明确的专业化描述
• 列出相关域（创建、修改、分析等）
• 指定技术重点领域
• 记录典型的方法和手段

用于会话管理

• 总是打电话 get_relevant_context() 开始工作前
• 使用描述性任务描述
• 完整填写所有模板部分
• 记录发现的新模式和方法
• 用标记完成的任务 [x] 在检查表中

用于模式开发

• 为任何可重用的方法创建模式
• 使用清晰、描述性的模式名称
• 包括成功的方法和失败案例
• 记录何时以及何时不使用图案
• 随着模式的演变而更新

故障排除

MCP服务器未出现

• 验证UV是否已安装： uv --version
• 检查MCP配置中的服务器路径是否正确
• 完全重新启动Claude代码
• 独立测试服务器： uv run python claude_subagent_communication_mcp/server.py

代理检测问题

• 确保 .claude/agents/ 目录存在
• 验证代理文件是否在 .md 格式
• 检查文件权限和访问权限
• 跑 scan_agents() 查看检测到的代理

子代理无法访问MCP工具

• 最常见的问题：初始化后需要重新启动Claude Code
• 检查代理frontmatter是否具有中列出的MCP工具 tools: 章节
• 验证代理是否已更新 ensure_all_agents_mcp_enabled()

上下文检索问题

• 验证会话和模式目录是否存在
• 检查会话是否遵循模板格式
• 确保有足够的内容进行相关性评分
• 使用 search_context() 用于调试

性能问题

• 监控会话和模式文件计数
• 检查中的磁盘空间 .claude/ 目录
• 审查效率的相关性评分
• 考虑归档旧会话

开发命令

# Install development dependencies
uv sync

# Run tests
uv run python -m pytest tests/

# Run server standalone for testing
uv run python claude_subagent_communication_mcp/server.py

# Check code style
uv run ruff check .

贡献

该项目遵循PRD中概述的实施计划。主要贡献领域：

1. 增强相关性评分 -改进上下文选择算法
2. 性能优化 -添加缓存和延迟加载
3. 模式智能 -增强模式发现和演化
4. 跨代理学习 -改进知识共享机制
5. 分析和见解 -添加项目分析和建议

许可证

该项目是Claude Code生态系统的一部分，遵循Anthropic的使用指南。

支持

有关问题和功能请求，请参阅相应存储库中的Claude Code文档或文件问题。