@cyanheads/shift-mcp-server

Lightweight coordination layer for multiple AI agents working on the same codebase. STDIO & Streamable HTTP

2 Tools · 1 Resource

---

Tools

Two tools for multi-agent coordination:

Tool Name	Description
shift_check_in	Register or update a worker session. Returns worker ID, coordination instructions, and active peers.
shift_check_out	End a working session. Removes from active worker list.

shift_check_in

Register a new worker or update an existing session. Called at the start of every working session.

• Accepts a gist of current work and optional file paths being modified
• Returns a 6-character worker ID, coordination protocol, and the full active workers table
• Pass an existing worker ID to update your session (patch semantics — omitted fields preserved)
• Error responses include the active workers table so agents can self-identify or start fresh

---

shift_check_out

End a working session and remove from the active worker list.

• Accepts a worker ID and optional summary of what was accomplished
• Idempotent — succeeds silently if the worker ID doesn't exist or was already checked out

Resources

URI	Description
shift://status	All currently active workers with gists, declared files, and timestamps.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Structured logging with request-scoped context
• Runs locally (stdio/HTTP) from the same codebase

Coordination-specific:

• In-memory worker session store — no database, no filesystem writes, clears on restart
• Coordination protocol injected on every check-in so agents know how to behave
• Active workers table returned with every response for situational awareness
• Patch semantics on session updates — only provided fields change

Getting Started

MCP Client Config

Add to your MCP client config (e.g., claude_desktop_config.json):

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

Prerequisites

• Bun v1.2.0 or higher

Installation

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

Configuration

No server-specific environment variables required. Framework defaults:

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_HTTP_HOST	Hostname for HTTP server.	127.0.0.1
MCP_LOG_LEVEL	Log level (RFC 5424).	info

Running the Server

Local Development

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

Dev mode with watch:

bun run dev:stdio     # or dev:http

Checks and tests:

bun run devcheck      # Lints, formats, type-checks
bun test              # Runs test suite

Docker

docker build -t shift-mcp-server .
docker run -p 3010:3010 shift-mcp-server

Project Structure

Directory	Purpose
src/index.ts	Entry point — registers tools and resources with createApp().
src/mcp-server/tools/definitions/	Tool definitions (check-in.tool.ts, check-out.tool.ts).
src/mcp-server/tools/definitions/worker-store.ts	In-memory worker session store and formatting utilities.
src/mcp-server/resources/definitions/	Resource definitions (status.resource.ts).

Development Guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• Register new tools and resources in src/index.ts

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun test

License

Apache-2.0 — see LICENSE for details.