Tools

Two tools bracketing a working session — one to announce it, one to end it:

shift_check_in

Called at the start of every working session, and again whenever the scope changes.

• Takes a gist of the current work plus optional files the agent expects to modify
• Returns a 6-character worker ID, the coordination protocol, and the full active-workers table
• Pass an existing workerId to update the session — patch semantics, so omitted fields and the original check-in timestamp are preserved
• An unknown workerId fails with reason: "unknown_worker" and embeds the active-workers table so the caller can self-identify or start fresh

shift_check_out

Ends a working session.

• Takes a workerId and an optional one-sentence summary
• Idempotent — an unknown or already-checked-out ID succeeds silently

Resources

The same roster is returned inline by shift_check_in, so tool-only clients see it without reading the resource. Subscribers to shift://status receive notifications/resources/updated on every check-in, session update, and check-out.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — one file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Structured logging with request-scoped context and optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports, serving MCP protocol revisions 2025 and 2026-07-28

Coordination-specific:

• In-memory worker session store — no database, no filesystem writes, cleared on restart
• The coordination protocol ships in every check-in response, so ground rules reach the agent without client-side configuration
• The active-workers table rides along with every check-in for situational awareness
• Patch semantics on session updates — only the fields provided change

Agent-friendly output:

• Both client surfaces carry the same data — structuredContent from the output schema, markdown from format()
• shift_check_in declares a typed error contract, so an unknown worker ID arrives with data.reason and a recovery hint
• Failure responses embed the current roster, so an agent recovers in the same turn instead of calling again to orient

Getting started

Add the following to your MCP client configuration file:

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

Or with npx (no Bun required):

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

Or with Docker:

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

Every agent sharing a codebase must reach the same server process for the roster to be shared. Over stdio each client spawns its own process, so point concurrent agents at one Streamable HTTP instance instead:

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

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• No API keys, accounts, or external services.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd shift-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

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

Configuration

No server-specific environment variables. Framework defaults worth knowing:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  sh

  Copy

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

• Run checks and tests:

  sh

  Copy

  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 3010:3010 shift-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/shift-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.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, ctx.state for tenant-scoped storage
• Register new tools and resources in src/index.ts
• format() must render every field in the output schema — both client surfaces carry the same data

License

Apache-2.0 — see LICENSE for details.