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/catchin tool logic - Use
ctx.logfor 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.