# Milestone v1.6 — MCP Fabric Summary

**Generated:** 2026-04-13
**Purpose:** Team onboarding and project review
**Grouping:** Changes organized by relevance to MCP structure

---

## 1. Project Overview

Owl Skill is a zero-dependency inter-agent messaging system for Claude Code. Agents register "perches" (file-based inboxes under `~/.claude/owlery/`), communicate via a native Rust binary (`owl.exe`), and use Claude Code skills (`/spt:*`) as their interface.

**v1.6 MCP Fabric** adds an MCP (Model Context Protocol) server transport layer to the existing spacetime messaging system. Agents in Claude Code sessions now interact with spacetime through structured MCP tools and resources instead of raw CLI commands, while the underlying Rust core remains unchanged.

**Status:** All 4 phases complete (15-18). 3 quick-fix tasks shipped post-verification.

---

## 2. Changes by MCP Relevance

### Tier 1: Core MCP Server Infrastructure

These changes create the MCP server itself — the JSON-RPC transport layer that Claude Code connects to.

| Change | Phase | Files |
|--------|-------|-------|
| Hand-rolled JSON-RPC 2.0 stdio server with initialize/ping dispatch | 15 | `src/mcp/server.rs`, `src/mcp/types.rs`, `src/mcp/dispatch.rs` |
| Parent-PID watchdog thread for clean exit when Claude Code dies | 15 | `src/mcp/watchdog.rs` |
| `owl mcp-serve` CLI subcommand to start the server | 15 | `src/cli.rs`, `src/owl/mod.rs` |
| Plugin `.mcp.json` manifest for auto-discovery by Claude Code | 18 | `plugin/spt/.mcp.json` |

**Key decision:** Hand-rolled JSON-RPC over stdio — no tokio, no new dependencies. Keeps the binary small and synchronous.

---

### Tier 2: MCP Tools (Agent Actions)

These changes expose spacetime operations as structured MCP tools that agents call.

| Change | Phase | Files |
|--------|-------|-------|
| Tool registry with 13 tool definitions, inputSchema, and annotations | 16 | `src/mcp/tools.rs` |
| `tools/list` and `tools/call` dispatch with all 13 handlers | 16 | `src/mcp/dispatch.rs` |
| `Arc<Mutex<Option<String>>>` identity binding via `spacetime_listen` / `spacetime_live_start` | 16 | `src/mcp/dispatch.rs`, `src/mcp/server.rs` |
| Lazy-bind: action tools auto-discover agent identity before executing | 16 | `src/mcp/dispatch.rs` |
| Tool error handling: `isError: true` with structured `{success, error, hint}` | 16 | `src/mcp/dispatch.rs` |
| MCP tool response slimming — return confirmations, not echo payloads | quick | `src/mcp/dispatch.rs` |

**13 MCP Tools:**
- **Owl (7):** `listen`, `send`, `list`, `stop`, `whoami`, `doctor`
- **Live (7):** `live_start`, `live_stop`, `commune`, `signoff`, `timed_pulse`, `context_save`, `amend_signoff`

**Annotations:** `readOnlyHint` on list/whoami/doctor; `destructiveHint` on stop/signoff/live_stop.

---

### Tier 3: MCP Resources (Agent Reads)

These changes expose spacetime state as read-only MCP resources using `spt://` URIs.

| Change | Phase | Files |
|--------|-------|-------|
| 5 resource definitions with `spt://` URI scheme | 17 | `src/mcp/resources.rs` |
| `resources/list` and `resources/read` dispatch | 17 | `src/mcp/dispatch.rs` |
| Inbox auto-mark-delivered on read (resource read = delivered) | 17 | `src/mcp/resources.rs` |
| ChangeTracker with check-on-dispatch notification emission | 17 | `src/mcp/resources.rs`, `src/mcp/server.rs` |
| Path traversal mitigation on `/{id}` suffix (T-17-04) | 17 | `src/mcp/resources.rs` |

**5 MCP Resources:**
| URI | Description | Binding Required |
|-----|-------------|-----------------|
| `spt://inbox` | Undelivered messages (ANSI-formatted) | Yes |
| `spt://perches` | All registered perches with online/offline status | No |
| `spt://psyches` | Psyche processes with status | No |
| `spt://context` | Bound agent's persisted Psyche context | Yes |
| `spt://memformat` | Bound agent's persisted memformat | Yes |

---

### Tier 4: Hook & Delivery Integration

These changes wire MCP awareness into the existing hook-based message delivery system.

| Change | Phase | Files |
|--------|-------|-------|
| PreToolUse hook migrated to spool-only (`peek_all` + `mark_delivered`) | 18 | `src/owl/hook_check.rs` |
| UserPromptSubmit wake-sentinel detection (`.` and `spt-wake`) | 18 | `src/owl/hook_prompt.rs` |
| SessionStart re-orientation on `/clear` and `/compact` | 18 | `src/owl/plugin_session_start.rs`, `src/owl/resume.rs` |
| Atomic spool coordination between hooks and MCP server | 18 | `src/common/spool.rs` |
| Hooks use `CLAUDE_PLUGIN_ROOT` instead of `OWL` env var | quick | `plugin/spt/hooks/hooks.json` |

**Key decision:** No MCP/non-MCP branching — all sessions are MCP after this transition.

---

### Tier 5: Spool & Result Variant Foundation

These changes prepare the internal data layer that MCP tools and resources consume. Not MCP-specific, but required for the MCP layer to function.

| Change | Phase | Files |
|--------|-------|-------|
| SQLite spool `delivered` column with idempotent schema migration | 15 | `src/common/spool.rs` |
| `peek_all()` non-destructive read and `mark_delivered()` atomic marking | 15 | `src/common/spool.rs` |
| `drain_all()` migrated from DELETE to `UPDATE SET delivered=1` | 15 | `src/common/spool.rs` |
| TCP-received messages written to spool before wake signal (SPOOL-04) | 15 | `src/owl/poll.rs` |
| 9 spool unit tests (gap closure) | 15 | `src/common/spool.rs` |
| 6 owl `_result()` functions: send, ring, whoami, list, stop, doctor | 15 | `src/owl/*.rs` |
| 7 live `_result()` functions: commune, live_start, live_stop, signoff, context_save, amend_signoff, timed_pulse | 16 | `src/live/*.rs` |
| 16 outcome types in `outcomes.rs` | 15-16 | `src/common/outcomes.rs` |
| 13 result_variants integration tests | 15 | `tests/result_variants.rs` |

---

### Tier 6: CLI Rename & Skill Documentation

These changes are MCP-motivated but affect the CLI and documentation surface.

| Change | Phase | Files |
|--------|-------|-------|
| Command rename: `deliver` -> `send`, `send` -> `ring`, `reply` folded into `send --reply-to` | 16 | `src/owl/send.rs`, `src/owl/ring.rs` (20 files total) |
| Backward-compat CLI aliases (`deliver`, `ask`, `reply` still work) | 16 | `src/cli.rs` |
| Root `SKILL.md`, `LIVE-SKILL.md`, `commune.md` retired | 18 | (deleted) |
| All plugin skill files rewritten MCP-first | 18 | `plugin/spt/skills/*/SKILL.md` |
| Only `poll` and `ring` documented as CLI commands (rest MCP-only) | 18 | Skill files |
| Plugin version bumped to 1.6.0 | 18 | `plugin/spt/.claude-plugin/plugin.json` |
| MCP server renamed `spacetime` -> `ime`, tool prefix stripped | quick | Multiple files |

---

## 3. Phases Delivered

| Phase | Name | Status | One-Liner |
|-------|------|--------|-----------|
| 15 | MCP Spike & Spool Foundations | Complete | JSON-RPC server spike + spool delivered marking + 13 result variants |
| 16 | MCP Tools | Complete | 13 MCP tools with identity binding, lazy-bind, and structured error handling |
| 17 | MCP Resources | Complete | 5 `spt://` resources with auto-mark inbox, change notifications |
| 18 | Hooks & Plugin Integration | Complete | Spool-only hooks, wake sentinels, plugin manifest, skill doc rewrite |

**Quick Tasks (post-verification):**
| Task | Description |
|------|-------------|
| 260413-6p7 | Fix plugin hooks to use `CLAUDE_PLUGIN_ROOT` |
| 260413-7bt | Rename MCP server, strip tool prefix, rewrite skills MCP-only |
| 260413-8k0 | Slim MCP tool responses to simple confirmations |

---

## 4. Key Decisions Log

| Decision | Phase | Rationale |
|----------|-------|-----------|
| Hand-rolled JSON-RPC, no tokio | 15 | Zero-dependency constraint; sync stdio is simpler for single-connection MCP |
| Spool is single source of truth | 15 | TCP messages written to spool before signal; hooks and MCP both read from spool |
| `_result()` functions parallel `run()` | 15 | Incremental migration — MCP calls `_result()`, CLI keeps `run()` |
| Lazy-bind identity discovery | 16 | Action tools auto-resolve agent_id; no explicit bind needed if perch exists |
| Curated 13-tool set (not 1:1 CLI) | 16 | Dropped lifecycle commands; MCP tools are the primary interface |
| `deliver` -> `send`, `send` -> `ring` | 16 | Aligns natural verb with most common operation |
| `spt://` URI scheme | 17 | Short, matches `/spt:` skill prefix |
| Inbox auto-mark on read | 17 | Reading = delivery; eliminates a round-trip tool call |
| Check-on-dispatch notifications | 17 | No background thread; checks before each request |
| No MCP/non-MCP branching | 18 | Clean transition; all sessions are MCP after v1.6 |
| Root skill files retired | 18 | Individual `spt:*` skills are what agents invoke; monolithic docs removed |
| `.mcp.json` for auto-discovery | 18 | Plugin-native manifest; no manual settings.json edits |
| Psyche excluded from MCP | Design | CLI only via `$OWL`/`$LIVE` — Psyche is a detached process |

---

## 5. Tech Debt & Deferred Items

**From verification reports:**
- Spool unit tests were missing after Phase 15 (SUMMARY falsely claimed 12 tests); closed in Phase 15 Plan 05
- REQUIREMENTS.md not updated for v1.6 requirement IDs (MCP-01..05, SPOOL-01..05, RVAR-01..11, TOOL-01..15, RES-01..08, HOOK-01..06, PLUG-01..07) — administrative gap only
- TOCTOU race in `plugin_session_start.rs` settings write (parallel session start edge case)
- Dead function `find_working_perch_by_agent_id` in `hook_output.rs`
- `unwrap()` on JSON serialization in `resume.rs` (consistent with codebase, low risk)

**From deferred ideas:**
- Stop hook commune wrapper for automatic Psyche updates
- Psyche wrapper auto-recovery on empty PULSE_TRIGGER stdout
- Revive and start commands leave Self listener dead (bug)
- Add tool limitations to Psyche sessions
- Log psyche wrapper output to file

---

## 6. Getting Started

- **Build:** `cargo build --release` produces `target/release/owl.exe`
- **Deploy:** Copy binary + plugin directory per `docs/DEPLOY.md`
- **Tests:** `cargo test` (124 tests: 42 CLI parse, 31 lib, 13 result variants, integration tests)
- **MCP server:** `owl mcp-serve` (auto-started by Claude Code via `.mcp.json`)
- **Key directories:**
  - `src/mcp/` — MCP server, tools, resources, dispatch (new in v1.6)
  - `src/common/outcomes.rs` — All structured outcome types (new in v1.6)
  - `src/common/spool.rs` — SQLite spool with delivered marking (extended in v1.6)
  - `plugin/spt/` — Plugin manifest, hooks, skill files

---

## Stats

- **Timeline:** 2026-04-10 -> 2026-04-13 (4 days)
- **Phases:** 4/4 complete + 3 quick tasks
- **Commits:** 106
- **Source files changed:** 69 (+3,954 / -1,184 lines)
- **New modules:** `src/mcp/` (6 files: dispatch, mod, resources, server, tools, types, watchdog)
- **New files:** `src/common/outcomes.rs`, `src/owl/ring.rs`, `tests/result_variants.rs`, `plugin/spt/.mcp.json`
- **Deleted files:** `src/owl/deliver.rs`, `src/owl/reply.rs`, `SKILL.md`, `LIVE-SKILL.md`, `commune.md`
- **Contributors:** Reavo End