wip MCP

会话领MCP

一种与提供者无关的模型上下文协议（MCP）服务器，当多个代理会话同时在同一代码库上工作时，可以防止冲突。

问题

使用并行编码代理会话或多代理工作流时：

• 会话A正在重构一些代码
• 会话B不知道并认为代码“有问题”-删除或还原它
• 会话A的工作消失

根本原因：会话之间没有“工作意图”的同步机制。

解决方案

会话协作MCP提供 在制品（WIP）注册表 这允许会话：

1. 声明 -宣布要修改的文件
2. 检查 -验证没有其他会话正在处理相同的文件
3. 坚持 -保存在上下文压缩后仍然存在的上下文
4. 保护 -保护关键文件免受意外更改
5. 发布 -完成后免费提供文件

定位

session-collab-mcp 有两层：

• 核心服务器：通过stdio或HTTP JSON-RPC提供与提供者无关的MCP服务器
• 可选集成：提供程序特定的打包，例如中的Claude Code插件 plugin/

核心服务器应该是默认的心智模型。Claude Code是一个集成目标，而不是产品边界。

安装

选项1：通过stdio的通用MCP客户端

将此功能用于任何可以启动本地stdio服务器的MCP客户端：

{
  "mcpServers": {
    "session-collab": {
      "command": "npx",
      "args": ["-y", "session-collab-mcp@latest"]
    }
  }
}

确切的配置包装器取决于您的MCP客户端，但服务器契约是相同的。

选项2:HTTP服务器+CLI

当您的客户端更喜欢MCP而不是HTTP JSON-RPC时，或者当您想要一个通用的shell友好包装器时，请使用此选项：

# Start HTTP server
session-collab-http --host 127.0.0.1 --port 8765

# CLI wrapper (convenience REST client)
session-collab health
session-collab tools
session-collab call --name collab_session_start --args '{"project_root":"/repo","name":"demo"}'

对于MCP over HTTP客户端，请使用 POST /mcp 使用JSON-RPC请求。这 /v1/* 端点是轻量级自动化和shell使用的便利REST外观。

选项3:Claude代码插件（可选集成）

仅当Claude Code是您的MCP客户端并且您需要自动服务器设置、挂钩和技能时，才作为Claude Code插件安装：

# Add marketplace
/plugin marketplace add leaf76/session-collab-mcp

# Install plugin
/plugin install session-collab@session-collab-plugins

该插件包括：

• MCP服务器：自动配置
• 钩子：会话启动、停止和预压缩提醒
• 技能: collab-start 用于完全初始化
• 命令: /session-collab:status 和 /session-collab:end

选项4：全局安装

npm install -g session-collab-mcp

特性

引导式会话工作流

MCP工具为您提供跨提供商的稳定协作工作流程：

1. 开始会话 collab_session_start
2. 检查文件 collab_claim(action="check")
3. 使用以下方式保留文件 collab_claim(action="create")
4. 使用保存重要上下文 collab_memory_save
5. 以结束会话 collab_session_end

工作记忆

在上下文压缩中幸存下来的上下文持久性：

• 研究结果：错误根源、调查结果
• 决策：架构选择、设计决策
• 状态：当前实施状况
• 待办事项：行动项目和任务
• 重要：要保存的关键信息
• 上下文：会议背景

文件保护

保护重要计划文件或创建的文件免受意外删除：

• 向注册受保护的计划 collab_protect(action="register", type="plan", ...)
• 使用注册创建的文件 collab_protect(action="register", type="file", ...)
• 在删除或替换文件之前检查保护状态

冲突处理模式

使用配置行为 collab_config:

自动释放选项

MCP工具参考

会话管理（5个工具）

索赔（1个统一工具）

工作记忆（3个工具）

保护（1个统一工具）

状态监控

HTTP API（v1）

/v1/* 端点1:1映射到MCP工具，并返回JSON响应 trace_id 关于失败：

• POST /v1/sessions/start → collab_session_start
• POST /v1/sessions/end → collab_session_end
• GET /v1/sessions → collab_session_list
• POST /v1/config → collab_config
• GET /v1/status → collab_status
• POST /v1/claims → collab_claim （创建）
• POST /v1/claims/check → collab_claim （检查）
• POST /v1/claims/release → collab_claim （释放）
• GET /v1/claims → collab_claim （列表）
• POST /v1/memory/save → collab_memory_save
• POST /v1/memory/recall → collab_memory_recall
• POST /v1/memory/clear → collab_memory_clear
• POST /v1/protect/register → collab_protect （注册）
• POST /v1/protect/check → collab_protect （检查）
• GET /v1/protect/list → collab_protect （列表）
• POST /v1/tools/call / GET /v1/tools （通用访问）

基于HTTP的MCP

• POST /mcp 接受JSON-RPC initialize, tools/list，以及 tools/call 请求：
• GET /mcp 当前返回一个明确的“不支持流”响应，而不是假装是完整的流式HTTP SSE
• 本地主机绑定强制执行主机和源验证
• 非本地绑定需要两者 SESSION_COLLAB_HTTP_TOKEN 以及允许的主机列表 SESSION_COLLAB_ALLOWED_HOSTS 或重复 --allowed-host

使用示例

基本工作流程

# Session A starts working
collab_session_start(project_root="/my/project", name="feature-auth")
collab_claim(session_id="session-a", action="create", files=["src/auth.ts"], intent="Adding JWT support")

# Session B checks before editing
collab_claim(session_id="session-b", action="check", files=["src/auth.ts"])
# Result: "CONFLICT: src/auth.ts is claimed by 'feature-auth'"

# If you want to include your own claims in the check
collab_claim(session_id="session-a", action="check", files=["src/auth.ts"], exclude_self=false)

# Session A finishes
collab_claim(session_id="session-a", action="release", claim_id="...")

工作记忆

# Save a finding
collab_memory_save(
  session_id="abc123",
  category="finding",
  key="auth_bug_root_cause",
  content="Missing token validation in refresh flow",
  priority=80
)

# Recall active memories
collab_memory_recall(session_id="abc123", active=true)

文件保护

# Protect a plan document
collab_protect(
  action="register",
  session_id="abc123",
  type="plan",
  file_path="docs/feature-plan.md",
  title="Feature plan",
  content_summary="Steps, risks, and rollout notes"
)

# Check before editing
collab_protect(
  action="check",
  session_id="abc123",
  file_path="docs/feature-plan.md"
)
# Result: "Protected (plan). Confirm before deleting."

状态监控

# Get session status
collab_status(session_id="abc123")
# Result: {
#   session: { id: "abc123", name: "feature-auth", status: "active" },
#   claims: [...],
#   other_sessions: 1,
#   message: "Session active. 2 claim(s), 5 memories."
# }

从v1.x迁移

2.0版通过简化的API引入了突破性的更改。看 MIGRATION.md 有关详细的迁移说明。

关键变化

• 工具整合：50多种工具→ 10 核心工具
• 基于动作的界面：具有多个操作的单个工具
• 简化响应：更简洁、更平坦的响应格式
• 已删除功能：LSP集成、消息传递、通知、排队

数据存储

所有数据都存储在本地 ~/.claude/session-collab/collab.db （SQLite）。

• 无需远程服务器
• 本地主机HTTP使用在没有API令牌的情况下有效
• 非本地HTTP绑定需要 SESSION_COLLAB_HTTP_TOKEN
• 离线工作
• 使用WAL模式实现多过程安全

发展

先决条件

• Node.js 18+
• npm或纱线

设置

npm install
npm run build

传统版本（可选）

传统模式/查询不在默认捆绑包中。要包含旧版条目以实现兼容性，请执行以下操作：

SESSION_COLLAB_INCLUDE_LEGACY=true npm run build

维护说明：遗留导出仅用于向后兼容性，不会在v2工具列表中公开。

脚本

npm run build        # Build with tsup
npm run start        # Start the MCP server
npm run start:dev    # Start in development mode
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint
npm run test         # Run tests with Vitest

HTTP集成测试

HTTP集成测试需要本地侦听端口。请使用以下命令启用它们：

SESSION_COLLAB_HTTP_TESTS=true npx vitest run src/http/__tests__/server-integration.test.ts

历史笔记

下面的变更日志条目记录了历史里程碑，包括在当前v2 API之前删除的工具和工作流。将上述工具表和示例视为当前公共表面的真实来源。

项目结构

session-collab-mcp/
├── bin/                    # Executable entry point
├── migrations/             # SQLite migration files
├── plugin/                 # Optional Claude Code integration
├── src/
│   ├── cli.ts             # CLI entry point
│   ├── constants.ts       # Version and server instructions
│   ├── db/                # Database layer
│   ├── mcp/               # MCP protocol implementation
│   │   ├── tools/         # Tool implementations
│   │   │   ├── session.ts # Session management
│   │   │   ├── claim.ts   # File/symbol claims
│   │   │   ├── memory.ts  # Working memory
│   │   │   └── protection.ts # File protection
│   │   └── ...
│   └── utils/
└── package.json

更新日志

v2.1.0

• 添加HTTP服务器+CLI包装器，以实现通用的AI CLI使用
• 添加HTTP API端点和utils测试
• 为已弃用的模式/查询添加旧条目（可选构建）
• 提高索赔冲突的准确性和发布摘要
• 扩展MCP工具和DB流的测试覆盖范围

v2.0.0（中断）

• 主要简化：从50多种工具减少到10种核心工具
• 基于行动的设计：具有操作参数的统一工具
• 已删除功能：LSP集成、消息传递、通知、排队、决策跟踪
• 改进的性能：更快的启动速度和更低的复杂性
• 更好的测试：所有工具操作的全面测试覆盖
• 迁移指南：v1.x的详细升级路径

v0.8.0

• 添加工作记忆系统以实现上下文持久化(collab_memory_* 工具）
• 添加计划保护(collab_plan_register, collab_plan_update_status)
• 添加文件保护(collab_file_register, collab_file_check_protected)
• 记忆类别：发现、决策、状态、待办事项、重要、上下文
• 固定的记忆在上下文压缩中幸存下来
• 计划生命周期：草稿→ 批准→ 正在进行中→ 完成→ 归档

v0.7.1

• 添加 collab_auto_release 编辑后发布索赔的工具
• 添加自动发布配置选项： auto_release_immediate, auto_release_stale
• 添加 cleanupStaleClaims() 用于自动清除过期索赔
• 添加PostTool使用钩子提醒编辑/写入后自动释放

v0.7.0

• 为索赔添加优先级系统（0-100，级别：严重/高/正常/低）
• 添加索赔队列系统(collab_queue_join, collab_queue_leave, collab_queue_list)
• 添加通知系统(collab_notifications_list, collab_notifications_mark_read)
• 添加审计历史跟踪(collab_history_list)
• 添加 collab_claim_update_priority 紧急工作不断升级

v0.6.0

• 使用复合索引优化数据库查询
• 提取共享实用程序（加密、响应构建器）
• 删除未使用的身份验证和令牌模块
• 使用预编译的JS，启动速度提高15倍
• 修复多值查询的GROUP_CONCAT分隔符
• 跨工具添加统一的Zod验证

v0.5.0

• 添加参考跟踪和影响分析（第3阶段）
• 添加符号级声明和LSP集成
• 修复多进程MCP服务器的SQLite WAL同步问题
• 添加 collab_config 冲突处理模式工具

许可证

麻省理工学院