JustClone Coordination MCP Server

The AI-native operating system for your company.

A production-grade coordination hub that enables AI agents and human teams to work as a single organism — sharing tasks, context, decisions, and persistent memory across projects. Not AI for AI's sake, but AI integrated directly into company operations.

Built with FastMCP · PostgreSQL 16 · Docker Compose
31 MCP tools · 19 REST endpoints · 11 tables · 78 tests

Why This Matters

Most AI tooling treats agents as isolated chat sessions. Each agent starts from zero, asks the same questions, loses context between sessions. JustClone MCP solves this with three innovations:

1. Shared Project State — Tasks, plans, results, and context persist in PostgreSQL. Any agent picks up where another left off.
2. Inter-Agent Messaging — Agents coordinate directly: the coder tells the copywriter what's ready, marketing asks sales for numbers, all without human relay.
3. Two-Tier Agentic Memory — Inspired by Anthropic's productivity plugin architecture. A per-agent hot cache of knowledge loads automatically on session start. Deep storage holds everything else. Agents decode shorthand, recall people, terms, and decisions instantly — across sessions, across projects, across time.
4. Multi-Agent Authorship Tracking — Every mutation (context, task, plan, result, memory) is auto-tagged with the agent who made the change via MCP session tracking. Full audit trail across all agents.

Architecture

┌─────────────────────────────────────────────────────────┐ │ OpenClaw / Agents │ │ (Coder · Sales · Marketing · Copywriter · Researcher) │ └───────────────┬─────────────────────────────────────────┘ │ MCP Protocol (Streamable HTTP) ▼ ┌─────────────────────────────────────────────────────────┐ │ JustClone Coordination Server │ │ FastMCP + Starlette │ 31 Tools │ 19 REST endpoints │ ├─────────────────────────────────────────────────────────┤ │ PostgreSQL 16 │ │ projects · tasks · plans · results · context │ │ sessions · messages · memories · members │ │ project_members · memory_usage (per-agent tracking) │ └─────────────────────────────────────────────────────────┘

## Stack

| Component | Tech |
|-----------|------|
| MCP Server | FastMCP + Starlette (Streamable HTTP) |
| Database | PostgreSQL 16 + asyncpg (JSONB codec for auto-serialization) |
| Migrations | Alembic (6 migrations) |
| Dashboard | nginx on port 20080 |
| Runtime | Docker Compose |
| Tests | pytest-asyncio (78 tests) |

## Quick Start

```bash
# 1. Start the stack
docker compose up -d --build

# 2. Dashboard
open http://localhost:20080

# 3. MCP endpoint (connect any agent here)
# NOTE: trailing slash required — Starlette Mount redirects /mcp → /mcp/
http://localhost:8765/mcp/

Two-Tier Agentic Memory

The flagship feature. Every agent automatically receives a hot cache of knowledge when starting a session — no setup, no config, no "remind me what we're doing".

How It Works

Agent calls jc_start("antigravity", "kaoru-bot")
  ↓
Server returns:
  ✅ Protocol (how to coordinate)
  ✅ Active tasks
  ✅ Context keys
  ✅ Unread messages
  ✅ Memory hot cache (top 30 by usage)
      person: 🌐 fedor — Owner, Tech Lead
      term:   📁 archetype — Persona routing pattern
      client: 🌐 acme-corp — Enterprise deal, Q2 close

Scoping: Project + Global

Tiered lookup: agent asks for "fedor" → checks project first → falls back to global.

Categories

person · project · term · client · deal · process · preference · other

Per-Agent Hot Cache

Every jc_recall increments both global usage_count and per-agent memory_usage. The hot cache (jc_start response) returns the top 30 most-used memories personalized to the calling agent. Each agent's most-accessed knowledge floats to the top automatically — no manual curation needed.

MCP Tools (31)

Session & State

Tasks

Context

Plans & Results

Sessions & Messaging

Memory (Two-Tier)

Admin

Members & Assignment

Codebase Sync

REST API (19 endpoints)

Universal Agent Protocol

Any AI agent connecting via MCP receives the full coordination protocol automatically when calling jc_start. The protocol covers:

• Session lifecycle: jc_start → work → jc_end_session
• Task flow: backlog → todo → in_progress → done (or blocked)
• Context sharing: persistent key/value store for decisions, tech stack, blockers
• Inter-agent messaging: agents coordinate handoffs directly
• Two-tier memory: per-agent hot cache auto-loads on start, tiered lookup for everything else
• Authorship tracking: all mutations auto-tagged with the agent who made them

Multi-Agent Scenario

Session 1 — Coder (Antigravity):
  jc_start("antigravity", "kaoru-bot")
  → Sees hot cache: "archetype = persona routing pattern"
  → Works on the feature
  jc_remember("kaoru-bot", "term", "PSR", "Pipeline Status Report")
  jc_post_message(recipient="copywriter", content="Landing page copy ready for review")

Session 2 — Copywriter:
  jc_start("copywriter", "kaoru-bot")
  → Hot cache already includes "PSR" (auto-promoted by usage)
  → Unread message: "Landing page copy ready for review"
  → Starts work immediately, no context lost

Connecting Any Agent

Agents must be registered as members and assigned to projects before connecting. Use the dashboard at http://localhost:20080 to manage members.

1. Add the agent in the Dashboard's Members panel → enter skills + connection config JSON is generated automatically
2. Assign the agent to the relevant project(s)
3. The agent connects using the generated config and self-reports capabilities on each jc_start:

{
  "mcpServers": {
    "justclone-mcp": {
      "serverUrl": "http://localhost:8765/mcp/"
    }
  }
}

Note: The trailing slash in /mcp/ is required. Without it, Starlette returns a 307 redirect that some MCP clients don't follow.

Agent Skill

A dedicated skill ships with this server to teach agents correct coordination patterns:

skills/using-justclone-mcp/
  SKILL.md              # Session lifecycle, capabilities rule, context vs memory
  tools-reference.md    # Full reference: all 31 MCP tools
  rest-reference.md     # Full reference: all 19 REST endpoints

Install by copying to your agent's skill directory:

# Claude Code
cp -r skills/using-justclone-mcp ~/.claude/skills/

# Other agents — equivalent skill directory path

Capabilities format (the critical rule):

capabilities='[
  {"name":"systematic-debugging","desc":"Use when encountering bugs"},
  {"name":"brainstorming","desc":"Use before creative or feature work"}
]'

Pass actual loaded SKILL.md names — not generic labels like code, browser, planning. The jc_list_members response shows all teammates' skills for task routing.

Database Schema (11 tables)

Development

All DB operations go through Docker PostgreSQL. No local SQLite/files.

# 1. Start the stack (DB + server + dashboard)
docker compose up -d --build

# 2. Local dev with venv (connects to Docker postgres on localhost:5432)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 3. Run migrations
DATABASE_URL=postgresql://mcp:mcp@localhost:5432/justclone_mcp alembic upgrade head

# 4. Run server locally (alternative to Docker)
python server.py

# 5. Tests (78 tests, connects to Docker postgres on localhost:5432)
pytest tests/ -v

# 6. Seed project context (optional — populates memories, tasks, context)
python seed_context.py

Key Technical Notes

• JSONB codec: asyncpg pool uses set_type_codec to auto-serialize/deserialize JSONB columns. Always use db.create_pool() — never raw asyncpg.create_pool().
• MCP mount: FastMCP uses streamable_http_path="/" + Starlette Mount("/mcp"). The session manager lifespan is manually propagated to the outer Starlette app.
• No local DB: .env points to localhost:5432 which is the Docker-exposed PostgreSQL port.

Ports

Web Dashboard

Real-time dashboard at http://localhost:20080 with auto-refresh (10s polling).

7 stat cards: Backlog · To Do · In Progress · Done · Blocked · Memories · Members
5-column Kanban board with task cards (ref, title, priority badges, assignee)
4 data panels: Project Context · Recent Messages · 🧠 Memories · 👥 Members

Members panel:

• Global member registry (🤖 agents / 👤 humans)
• Add member modal with type selector and role
• Auto-generates MCP connection config JSON for agents
• Delete member button

Memories panel:

• Scope indicators: 🌐 global / 📁 project
• Category badges (person, term, client, etc.)
• Usage count per memory

All user-facing data is sanitized via esc() helper to prevent XSS.

Security

Roadmap

• Project membership UI — per-project member checkboxes in dashboard
• OpenClaw integration — single pane of glass across all projects
• Trello/Linear sync — bidirectional task sync with external boards
• Auth layer — per-agent permissions and API keys
• Auto-promote/demote — LRU-based hot cache management
• Full-text search upgrade — tsvector + GIN index for memory search (migration 006)
• Audit logging — all mutations now tracked via updated_by + per-agent memory_usage

License

MIT