Initial Implementation: Core MCP Server for Session Coordination

[VirtueMe]

📊 Phase 1 Progress Tracking

Phase	Issue	Status	Assignee
1.1 Storage Adapter Layer	#3	✅ COMPLETED	Echo (CT-1409)
1.2 Configuration & Detection	#4	✅ COMPLETED	Tech (CT-9902)
1.3 MCP Server, Tools, Resources & Prompts	#5	✅ COMPLETED	Echo (CT-1409)
1.4 CLI & Entry Point	#6	✅ COMPLETED	Echo (CT-1409)
1.5 Testing & Documentation	#7	🔄 IN PROGRESS	Echo (CT-1409)
1.6 Packaging for Internal Use	#8	⏳ PENDING	Unassigned

Overall Progress: 4/6 phases complete (67%)

---

Overview

Build the Claude Session Coordinator MCP server - a flexible coordination layer that enables multiple Claude AI sessions to share state and coordinate work across machines.

Core Philosophy: Flexible Primitives + Self-Documenting Server

The MCP server provides simple, universal primitives (key-value storage with scopes) enhanced with resources and prompts that guide Claude automatically. No workflow opinions - just powerful building blocks.

What Makes This Different

1. Storage Adapter Pattern

Swap backends without changing client code:

• Phase 1: Local file storage (no dependencies)
• Phase 2+: Redis for cross-machine coordination
• Custom: Implement your own adapter

2. Self-Documenting via MCP

The server teaches Claude the workflow automatically:

• Resources: Provide current state (session://context, session://state/{id})
• Prompts: Guide startup and sign-off procedures
• Tool Descriptions: Explain usage inline

3. Future-Proof Scoping

Even in Phase 1 (local-only), scopes include machine:project for seamless multi-machine upgrade:

{machine}:{owner/repo}:{type}:{id}
laptop:BANCS-Norway/my-repo:session:claude_1

Core MCP Tools

Session Management

• sign_on(session_id?) - Claim instance, auto-detect machine/project
• sign_off() - Release instance

Data Operations

• store_data(scope, key, value) - Store any JSON-serializable data
• retrieve_data(scope, key) - Retrieve stored data
• delete_data(scope, key) - Remove specific data
• delete_scope(scope) - Remove entire scope

Discovery

• list_keys(scope) - Discover keys in a scope
• list_scopes(pattern?) - List scopes with optional filtering

MCP Resources (Auto-Context)

Claude reads these automatically to understand the environment:

session://context

{
  "machine": "laptop",
  "project": "BANCS-Norway/my-repo",
  "instances": {"claude_1": "available", "claude_2": "taken"},
  "active_sessions": [...],
  "first_available": "claude_1",
  "instructions": {
    "if_not_signed_on": "Call sign_on() to claim an instance",
    "when_done": "Call sign_off() to release your instance"
  }
}

session://state/{instance_id}

• Read-only view of another session's state
• Enables coordination between sessions

MCP Prompts (Auto-Guidance)

startup - Automatically shown when Claude connects:

You are starting a new session in: BANCS-Norway/my-repo
Available instances: ["claude_1", "claude_3"]
Active sessions: 1

Next Steps:
1. Sign on: Call sign_on() to claim instance claude_1
2. Check coordination: Read other sessions' state
3. Start work: Use store_data() to track progress
4. Sign off: When done, call sign_off()

Would you like me to sign on now?

sign-off - Reminds about incomplete tasks before releasing

Storage Adapter Architecture

All adapters implement the same interface:

```python
class StorageAdapter(ABC):
def store(scope: str, key: str, value: Any) -> None
def retrieve(scope: str, key: str) -> Any | None
def delete(scope: str, key: str) -> bool
def list_keys(scope: str) -> list[str]
def list_scopes(pattern: str | None) -> list[str]
def delete_scope(scope: str) -> bool
def close() -> None
```

Phase 1: Local File Adapter

• JSON files in .claude/session-state/
• One file per scope
• Simple, no external dependencies
• Perfect for single-machine use

Phase 2+: Redis Adapter

• Cross-machine coordination
• Atomic operations (SETNX, INCR)
• Built-in TTL for auto-cleanup
• Pub/sub for real-time updates

Custom Adapters

Users can implement their own (S3, PostgreSQL, etc.)

Configuration

Priority order:

1. CLAUDE_SESSION_COORDINATOR_CONFIG env var
2. ./.claude/session-coordinator-config.json (project-local)
3. ~/.config/claude-session-coordinator/config.json (user-global)
4. Built-in defaults

Example config:
```json
{
"server": {
"port": 9999,
"host": "localhost"
},
"storage": {
"adapter": "local",
"config": {
"base_path": ".claude/session-state"
}
},
"session": {
"machine_id": "auto",
"project_detection": "git"
}
}
```

Switching to Redis (future):
```json
{
"server": {
"port": 9999,
"host": "localhost"
},
"storage": {
"adapter": "redis",
"config": {
"url": "redis://localhost:6379/0",
"ttl": 86400
}
}
}
```

Phase 1: Core Implementation

Deliverables

• Monorepo structure
• Architecture documentation
• Implementation plan
• Storage adapter interface (Issue Phase 1.1: Storage Adapter Layer #3)
• Local file adapter (Issue Phase 1.1: Storage Adapter Layer #3)
• Configuration system (Issue Phase 1.2: Configuration & Detection #4)
• Machine/project detection (Issue Phase 1.2: Configuration & Detection #4)
• MCP server setup (Issue Phase 1.3: MCP Server, Tools, Resources & Prompts #5)
• 8 core tools: sign_on, sign_off, store/retrieve/delete data, list keys/scopes (Issue Phase 1.3: MCP Server, Tools, Resources & Prompts #5)
• 2 resources: context, session state (Issue Phase 1.3: MCP Server, Tools, Resources & Prompts #5)
• 2 prompts: startup, sign-off (Issue Phase 1.3: MCP Server, Tools, Resources & Prompts #5)
• CLI & Entry Point (Issue Phase 1.4: CLI & Entry Point #6)
• Comprehensive tests (Issue Phase 1.5: Testing & Documentation #7 - IN PROGRESS)
• Documentation (Issue Phase 1.5: Testing & Documentation #7 - IN PROGRESS)
• Package for internal use (Issue Phase 1.6: Packaging for Internal Use #8 - PENDING)

Success Criteria

• ✅ Installable via pip install -e .
• ✅ Works with Claude Code
• ✅ Multiple sessions can coordinate on same machine
• ✅ Claude automatically understands workflow via resources/prompts
• ✅ Easy to swap storage backend (adapter pattern)
• ✅ Scopes support future multi-machine use
• ⏳ All tests pass (>90% coverage) - IN PROGRESS

Technical Architecture

Language & Framework:

• Python 3.10+
• MCP SDK (official Python SDK)
• No external dependencies for Phase 1

Server Configuration:

• Default port: 9999
• Protocol: MCP over stdio/HTTP
• Host: localhost (Phase 1)

Project Structure:
```
packages/mcp-server/
├── src/claude_session_coordinator/
│ ├── server.py # MCP server
│ ├── config.py # Config loading
│ ├── detection.py # Machine/project detection
│ ├── adapters/
│ │ ├── base.py # StorageAdapter interface
│ │ ├── local.py # LocalFileAdapter
│ │ ├── redis.py # RedisAdapter (Phase 2)
│ │ └── factory.py # AdapterFactory
│ ├── resources.py # MCP resources
│ ├── prompts.py # MCP prompts
│ └── tools/
│ ├── session.py # sign_on, sign_off
│ ├── data.py # store, retrieve, delete
│ └── discovery.py # list_keys, list_scopes
├── tests/
├── examples/
└── docs/
```

Documentation

See the repository for detailed documentation:

• Architecture Overview - Complete design including storage adapters, MCP resources/prompts, scoping strategy
• Phase 1 Implementation Plan - Detailed breakdown with code examples, timeline, and acceptance criteria

Why This Approach?

Storage Adapters:

• Start simple (local files), upgrade later (Redis)
• No vendor lock-in
• Easy to test different backends

MCP Resources & Prompts:

• Claude doesn't need to memorize workflow
• Server provides context automatically
• Reduces user explanation needed
• Better onboarding for new users

Future-Proof Scoping:

• Phase 1 works locally
• Phase 2+ seamlessly adds multi-machine
• No migration needed - data model already supports it

Unopinionated Primitives:

• Users build their own workflows
• No forced patterns
• Maximum flexibility

Timeline

Phase 1.1 - Storage Layer: 2-3 days ✅ COMPLETED
Phase 1.2 - Config & Detection: 1-2 days ✅ COMPLETED
Phase 1.3 - MCP Server, Tools, Resources & Prompts: 4-5 days ✅ COMPLETED
Phase 1.4 - CLI & Entry Point: 1 day ✅ COMPLETED
Phase 1.5 - Testing & Documentation: 2-3 days 🔄 IN PROGRESS
Phase 1.6 - Packaging: 1-2 days ⏳ PENDING

Total: 11-16 days (4/6 phases complete - 67%)

Future Phases

Phase 2: Redis adapter, multi-machine coordination
Phase 3: Public launch with homepage and PyPI
Phase 4: VS Code extension, dashboard, CLI tools

Getting Started

See Phase 1 Implementation Plan for detailed implementation steps, code examples, and testing strategy.

---

Let's build flexible primitives that enable any workflow! 🚀