@cyanheads/shift-mcp-server

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

2 Tools · 1 Resource

Version License

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`

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.

@cyanheads/shift-mcp-server