shift-mcp-server

---

概述

为同时在同一代码库上工作的多个 AI Agent 提供协调层。提交任务概要和预计要修改的文件进行签到，查看所有活跃协作者，并在完成后签出。

工具

工具	描述
shift_check_in	注册或更新工作会话。返回工作者 ID、协调协议和活跃协作者。
shift_check_out	结束工作会话，并将其从活跃工作者列表中移除。

资源

资源	描述
shift://status	所有当前活跃工作者及其任务概要、声明的文件和签到时间戳。
shift://status{?workspace}	指定工作区的人员名单；请使用任一工具返回的 statusUri。

shift_check_in 也会直接返回同一份人员名单。现代 subscriptions/listen 流会在每次签到提交、会话更新或实际移除时，通过带工作区限定的 URI 接收一次更新；对于服务器的默认工作区，也会发布不带限定的别名。两个协议版本产生的变更都会通过同一服务器事件总线发布。此框架的旧版传递适配器需要轮询；这并非 2025 协议本身的限制。通知仅在单个进程内传递；读取始终会反映其他进程已提交的状态。

功能参考

shift_check_in _工具

• 必需参数为 gist，可选参数为 files、workspace 和 workerId（六位 ASCII 字母或数字，不区分大小写），用于更新会话。ID 会以大写形式存储并返回。
• 返回你的会话、activeWorkers、解析后的 workspace 和限定的 statusUri。更新会保留未提供的 files 和原始 checkedInAt；显式传入空的 files 数组会清除文件声明。
• 协调协议和适用的单人工作者提示会以结构化输出中的 notice 和文本附注的形式各发送一次。
• 未知的 workerId 会失败，原因是 unknown_worker（NotFound），并附带恢复提示和当前名册。

---

shift_check_out _工具

• 必需参数为 workerId（六位 ASCII 字母或数字，不区分大小写），可选参数为 workspace 和一句话的 summary。
• 返回 removed、解析后的 workspace、限定的 statusUri 以及 ID 和摘要。未知或已移除的 ID 会成功返回 removed: false，并指向该名册，但不会猜测 ID 缺失的原因。
• 仅当会话实际存在且已被移除时，才会发布资源更新。

---

shift://status _资源

• 返回 text/markdown——活跃工作者表格；若名册为空，则返回“No agents are currently active.”
• workerId 来自 shift_check_in
• 不带限定符的资源会读取进程默认工作区。限定模板会读取其 URI 中编码的确切标识符。
• 表格单元格中的反斜杠和竖线会进行转义，CRLF/LF/CR 会被压平；存储值和结构化输出保持不变。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志记录。

协调专属功能：

• 按用户划分的 SQLite 名册可在进程间共享，按工作区隔离，并持久保存，直到显式签出
• 每次签入响应都会附带协调协议，因此无需客户端配置即可将基本规则传达给 Agent
• 每次签入都会附带活跃工作者表格，便于了解当前情况
• 会话更新采用补丁语义——仅修改已提供的字段

面向 Agent 的输出：

• 两种客户端界面都携带相同数据——来自输出架构的 structuredContent，以及来自 format() 的 Markdown
• shift_check_in 声明了类型化错误契约，因此未知工作者 ID 会附带 data.reason 和恢复提示
• 失败响应中包含当前名册，因此 Agent 无需再次调用来了解情况，即可在同一轮中恢复

入门

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/shift-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SHIFT_WORKSPACE": "my-project"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/shift-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SHIFT_WORKSPACE": "my-project"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SHIFT_WORKSPACE=my-project",
        "-v", "shift-state:/var/lib/shift-mcp-server",
        "ghcr.io/cyanheads/shift-mcp-server:latest"
      ]
    }
  }
}

让所有协作的 Agent 使用相同的 SHIFT_WORKSPACE 和状态目录。默认情况下，同一 OS 用户启动的原生进程会共享 ~/.local/state/shift-mcp-server。显式标识符是不透明的，且必须完全匹配：my-project 和 /path/my-project 属于不同的命名空间。原生客户端和 Docker 客户端可以通过将原生状态目录绑定挂载到容器中来共享成员列表，而不是使用命名卷。

未设置 SHIFT_WORKSPACE 时，两种传输方式都会使用所在 Git 工作树根目录的真实路径；若不在 Git 仓库中，则使用启动时的工作目录。工具的工作区选择器为空时，也会使用此默认值；非空标识符则必须完全匹配。从子目录或符号链接启动时，最终都会指向同一个根目录。桌面客户端和安装徽章可能会在项目目录之外启动：安装后配置 SHIFT_WORKSPACE，或在每次工具调用中传入 workspace。桌面版会提示选择工作区。Codex 插件会转发环境中的 SHIFT_WORKSPACE 和 SHIFT_STATE_DIR；Claude 插件则提供对应的配置选项。

共享的 HTTP 进程会将自身的启动目录用作默认值；多路复用的客户端必须为各自的项目传入显式的 workspace：

SHIFT_WORKSPACE=my-project MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.3 或更高版本（或 Node.js v24+）。
• 无需 API 密钥、账户或外部服务。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/shift-mcp-server.git

2. 进入目录：

cd shift-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you need to override a framework default

配置

成员列表独立于框架的 STORAGE_PROVIDER_TYPE 使用 SQLite。状态会一直保留到签出为止；重启不会清除被遗弃的会话。没有 TTL 或自动清理机制。工作区名称和工作者 ID 是协作选择器，并非身份验证边界。

WAL 和 BEGIN IMMEDIATE 会串行处理变更、ID 分配和返回的成员列表快照。启动时会在 3 秒的时限内重试 SQLite 锁竞争；繁忙的变更操作也最多等待 3 秒。存储繁忙、损坏或不可写时，会明确报错，不会回退到内存存储。共享状态目录应使用支持 SQLite 锁定的本地文件系统。

变量	描述	默认值
SHIFT_WORKSPACE	不透明的默认工作区命名空间；工具可覆盖此值。	Git 根目录的真实路径或启动时的工作目录
SHIFT_STATE_DIR	包含 roster.sqlite 的共享可写本地目录。	~/.local/state/shift-mcp-server
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机名。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话处理方式：auto、stateful 或 stateless。由于没有处理器需要会话，服务会在 createApp() 中声明为 stateless；设置此变量可覆盖该值。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅适用于 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 检测。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, packaging
  bun run test       # Vitest suites: unit, smoke, integration, fuzz
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t shift-mcp-server .
docker run --rm -p 127.0.0.1:3010:3010 -e SHIFT_WORKSPACE=my-project -v shift-state:/var/lib/shift-mcp-server shift-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，将日志写入 /var/log/shift-mcp-server，并将名册状态存储在 /var/lib/shift-mcp-server。所有协同容器都应复用同一个可写卷和工作区。主机绑定挂载必须允许镜像中的 bun 用户写入。默认会安装 OpenTelemetry 对等依赖项；如要省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 定义、存储设置与清理、服务通知。
src/config	存储目录和默认工作区配置。
src/mcp-server/tools	工具定义（check-in.tool.ts、check-out.tool.ts）。
src/mcp-server/resources	静态默认名册和限定工作区的模板。
src/services/worker-store	事务型 SQLite 员工存储和表格格式化。
tests/	与 src/ 结构对应的单元、冒烟、集成和模糊测试套件。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简而言之：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围的日志记录，使用 ctx.state 进行租户范围的存储
• 在 src/index.ts 中注册新的工具和资源
• format() 必须呈现输出架构中的每个字段 — 两种客户端界面都包含相同的数据

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。