# 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  
> **30 MCP tools · 19 REST endpoints · 11 tables · 63 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 │ 30 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 (5 migrations) |
| Dashboard | nginx on port 20080 |
| Runtime | Docker Compose |
| Tests | pytest-asyncio (63 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 (30)

### 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` | Search memories by partial match |
| `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 |

## 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`:

```json
{
  "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 30 MCP tools
  rest-reference.md     # Full reference: all 19 REST endpoints
```

**Install by copying to your agent's skill directory:**
```bash
# Claude Code
cp -r skills/using-justclone-mcp ~/.claude/skills/

# Other agents — equivalent skill directory path
```

**Capabilities format (the critical rule):**
```json
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.**

```bash
# 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 (63 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 |
| ILIKE injection | `db.search_memories()` | `_escape_like()` — escapes `%`, `_`, `\` |
| 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
- [ ] Full-text search upgrade — switch from ILIKE to tsvector for memory search at scale
- [x] ~~Audit logging~~ — all mutations now tracked via `updated_by` + per-agent memory_usage

## License

MIT