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

Scope	Description	Visibility
Global (is_global=True)	Company-wide: people, terms, processes	Every agent, every project
Project	Project-specific: decisions, tech stack	Only agents on that project

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

Tool	Description
jc_start	Begin session — validates member, self-reports capabilities, returns protocol + state + team skills
jc_update	Get current project snapshot

Tasks

Tool	Description
jc_create_task	Add a task to the board (optional assignee)
jc_update_task	Move task between statuses
jc_complete_task	Mark task done with summary
jc_list_tasks	List all tasks (optional assignee filter)
jc_get_task	Get full task details + plan + result
jc_edit_task	Edit task title/description
jc_delete_task	Delete a task by reference

Context

Tool	Description
jc_get_context	Read all context keys
jc_set_context	Write a context key/value
jc_delete_context	Delete a context key

Plans & Results

Tool	Description
jc_save_plan	Store implementation plan for a task
jc_get_plan	Retrieve plan for a task
jc_save_result	Store task result
jc_get_result	Retrieve task result

Sessions & Messaging

Tool	Description
jc_end_session	End session with summary
jc_post_message	Send message (validates sender/recipient are project members)
jc_get_messages	Fetch messages for an agent

Memory (Two-Tier)

Tool	Description
jc_remember	Store a memory (project or global scope)
jc_recall	Recall memory by key (tiered: project → global)
jc_memory_search	Full-text search memories (tsvector)
jc_forget	Delete a memory
jc_memory_promote	Promote/demote memory tier (hot ↔ deep)

Admin

Tool	Description
jc_list_projects	List all projects
jc_list_sessions	List recent sessions for a project
jc_delete_project	Delete project + all data (CASCADE)

Members & Assignment

Tool	Description
jc_list_members	List project members with full capability descriptions
jc_assign_task	Assign a task to a project member
jc_my_tasks	List tasks assigned to a specific agent

Codebase Sync

Tool	Description
jc_sync_codebase	Batch-sync derived codebase metrics with project context

REST API (19 endpoints)

Method	Endpoint	Description
GET	/health	Health check
GET	/api/projects	List projects
POST	/api/projects	Create project
DELETE	/api/projects/{id}	Delete project
GET	/api/projects/{id}/tasks	List tasks
DELETE	/api/projects/{id}/tasks/{ref}	Delete task
GET	/api/projects/{id}/context	List context
DELETE	/api/projects/{id}/context/{key}	Delete context key
GET	/api/projects/{id}/messages	List messages
GET	/api/projects/{id}/sessions	List sessions
GET	/api/projects/{id}/memories	List project + global memories
GET	/api/memories/global	List global memories only
GET	/api/members	List all members
POST	/api/members	Create member (returns MCP config for agents)
DELETE	/api/members/{id}	Delete member
PATCH	/api/members/{id}	Update member capabilities/role
GET	/api/projects/{id}/members	List project members
POST	/api/projects/{id}/members	Add member to project
DELETE	/api/projects/{id}/members/{mid}	Remove member from project

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)

Table	Purpose
projects	Project registry
tasks	Task board (backlog → done), with optional assignee + updated_by
plans	Implementation plans per task + updated_by
results	Task outputs and deliverables + updated_by
context	Key/value config and state + updated_by
sessions	Agent session tracking
messages	Inter-agent messaging (validated sender/recipient)
memories	Two-tier memory (hot/deep, project/global) + updated_by
members	Global member registry (agents + humans, type + role)
project_members	Many-to-many: which members work on which project
memory_usage	Per-agent memory access tracking (usage_count, last_used)

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

Port	Service
8765	MCP Server + REST API
20080	Web Dashboard
5432	PostgreSQL (internal)

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

Protection	Where	Method
XSS prevention	Dashboard (all render functions)	esc() — textContent-based HTML escaping
FTS safety	db.search_memories()	plainto_tsquery() — prevents tsquery injection
SQL injection	All DB functions	Parameterized queries via asyncpg
CASCADE safety	jc_delete_project	Atomic DELETE ... RETURNING
CORS	REST API	Configurable via Starlette middleware

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
• [x] Full-text search upgrade — tsvector + GIN index for memory search (migration 006)
• [x] Audit logging — all mutations now tracked via updated_by + per-agent memory_usage

License

MIT