P9-S35: MCP server

.ai/handoff/CURRENT_STATE.md

@@ -20,7 +20,7 @@
 
 ## Incomplete / At-Risk Areas
 
-- no published MCP server surface exists yet
+- no external adapter/importer interop has shipped yet beyond local MCP
 - importer and adapter story is not yet public-ready
 - OSS license finalization is still open
 
@@ -30,7 +30,7 @@ Phase 9: Alice Public Core and Agent Interop
 
 ## Latest State Summary
 
-`P9-S33` and `P9-S34` are now shipped baselines:
+`P9-S33`, `P9-S34`, and `P9-S35` are now shipped baselines:
 
 - package boundary is documented around `alice-core`
 - canonical local startup path is documented and script-backed
@@ -39,12 +39,27 @@ Phase 9: Alice Public Core and Agent Interop
 - packaged CLI entrypoint exists at `python -m alicebot_api` (optional console script `alicebot`)
 - continuity command coverage exists for capture, recall, resume, open-loops, review queue/show/apply, and status
 - correction flow through CLI now deterministically changes later recall/resume outputs
-
-The next active seam is `P9-S35`:
-
-- mirror the shipped CLI continuity contract via MCP tool transport
-- keep parity strict with existing deterministic CLI semantics
-- avoid reopening continuity behavior in transport work
+- local MCP server entrypoint exists at `python -m alicebot_api.mcp_server` (optional console script `alicebot-mcp`)
+- ADR-003 MCP tools are wired to shipped continuity seams:
+  - `alice_capture`
+  - `alice_recall`
+  - `alice_resume`
+  - `alice_open_loops`
+  - `alice_recent_decisions`
+  - `alice_recent_changes`
+  - `alice_memory_review`
+  - `alice_memory_correct`
+  - `alice_context_pack`
+- MCP interoperability proof is now covered by integration tests for:
+  - successful `alice_recall` and `alice_resume` calls
+  - correction via `alice_memory_correct` changing subsequent retrieval deterministically
+  - structured parity against shipped CLI/core behavior
+
+The next active seam is `P9-S36`:
+
+- implement OpenClaw adapter boundary on top of shipped CLI/MCP continuity contract
+- keep parity strict with existing deterministic continuity semantics
+- avoid widening MCP transport semantics while adapter boundary is established
 
 ## Critical Constraints
 
@@ -55,11 +70,11 @@ The next active seam is `P9-S35`:
 
 ## Immediate Next Move
 
-Execute `P9-S35` on top of the `P9-S33`/`P9-S34` boundary:
+Execute `P9-S36` on top of the `P9-S33`/`P9-S34`/`P9-S35` boundary:
 
-- map MCP tools directly to the shipped CLI behavior contract
-- preserve deterministic output semantics for parity tests
-- keep startup/sample-data path unchanged while MCP is introduced
+- build the first OpenClaw adapter using the shipped MCP wedge
+- preserve deterministic continuity output semantics and correction parity
+- keep startup/sample-data path unchanged while adapter support is added
 
 ## Legacy Compatibility Markers
 

BUILD_REPORT.md

@@ -1,48 +1,57 @@
 # BUILD_REPORT.md
 
 ## sprint objective
-Ship `P9-S34` by adding a deterministic local CLI for core continuity flows (`capture`, `recall`, `resume`, `open-loops`, `review queue/show/apply`, `status`) on top of the shipped `alice-core` runtime.
+Ship `P9-S35` by adding a deterministic local MCP server that exposes the ADR-003 continuity tool surface (`alice_capture`, `alice_recall`, `alice_resume`, `alice_open_loops`, `alice_recent_decisions`, `alice_recent_changes`, `alice_memory_review`, `alice_memory_correct`, `alice_context_pack`) over the shipped `alice-core` runtime without changing `P9-S33` startup flow or `P9-S34` semantics.
 
 ## completed work
-- Added packaged CLI entrypoint and module entry support:
-  - `apps/api/src/alicebot_api/cli.py`
-  - `apps/api/src/alicebot_api/cli_formatting.py`
-  - `apps/api/src/alicebot_api/__main__.py`
-  - `pyproject.toml` (`[project.scripts] alicebot = "alicebot_api.cli:main"`)
-- Kept CLI behavior on existing continuity seams (no core semantic fork):
-  - capture: `capture_continuity_input`
-  - recall: `query_continuity_recall`
-  - resume: `compile_continuity_resumption_brief`
-  - open-loops: `compile_continuity_open_loop_dashboard`
-  - review queue/show/apply: `list_continuity_review_queue`, `get_continuity_review_detail`, `apply_continuity_correction`
-  - status: runtime health + continuity/review/open-loop/retrieval summary
-- Added deterministic terminal formatting with provenance/trust signals:
-  - stable section order
-  - stable scope rendering
-  - stable list rendering and confidence/posture fields
-  - explicit empty states
-- Added CLI-focused tests:
-  - `tests/unit/test_cli.py`
-  - `tests/integration/test_cli_integration.py`
+- Added runnable MCP transport entrypoint:
+  - `apps/api/src/alicebot_api/mcp_server.py`
+  - stdio JSON-RPC loop with deterministic framing
+  - supported methods: `initialize`, `ping`, `tools/list`, `tools/call`
+- Added deterministic MCP tool layer:
+  - `apps/api/src/alicebot_api/mcp_tools.py`
+  - static deterministic tool schemas (ADR-003 tool names in fixed order)
+  - direct mapping to shipped continuity seams (capture/recall/resume/open-loops/review/correction)
+  - deterministic structured serialization and narrow error envelopes
+- Added package script entrypoint:
+  - `pyproject.toml`: `alicebot-mcp = "alicebot_api.mcp_server:main"`
+- Added MCP unit and integration verification:
+  - `tests/unit/test_mcp.py`
+  - `tests/integration/test_mcp_server.py`
+  - `tests/integration/test_mcp_cli_parity.py`
+- Added interoperability evidence for a real MCP client path (stdio JSON-RPC client subprocess):
+  - successful `alice_recall`
+  - successful `alice_resume`
+  - successful `alice_memory_correct` (`supersede`) with deterministic change in later recall/resume result
+- Captured required acceptance evidence details:
+  - exact MCP startup path used: `./.venv/bin/python -m alicebot_api.mcp_server`
+  - exact local client/config used for proof:
+    - client type: stdio JSON-RPC MCP client subprocess
+    - transport command: `python -m alicebot_api.mcp_server`
+    - env: `DATABASE_URL=postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot`
+    - env: `ALICEBOT_AUTH_USER_ID=00000000-0000-0000-0000-000000000001`
+  - intentionally deferred concern: no hosted/remote auth layer (local process + local user scope only)
 - Updated sprint-scoped docs:
-  - `README.md` (CLI invocation and examples)
-  - `ROADMAP.md` (`P9-S34` shipped baseline, `P9-S35` next seam)
-  - `.ai/handoff/CURRENT_STATE.md` (CLI shipped summary and next seam)
-- Preserved control-doc truth marker compatibility in `.ai/handoff/CURRENT_STATE.md` (`Active Sprint focus is Phase 4 Sprint 14`) to keep baseline gate checks green.
+  - `README.md` with exact MCP startup path and compatible local client config example
+  - `ROADMAP.md` marking `P9-S35` shipped baseline
+  - `.ai/handoff/CURRENT_STATE.md` with MCP shipped baseline and `P9-S36` next seam
 
 ## incomplete work
-- None inside `P9-S34` scope.
-- Intentionally deferred (out of scope): MCP transport/tool schemas (`P9-S35`), adapters/importer expansion, CLI ergonomics polish (autocomplete/TUI enhancements).
+- None inside `P9-S35` scope.
+- Intentionally deferred (out of scope):
+  - OpenClaw adapter implementation (`P9-S36`)
+  - importer expansion
+  - hosted/remote auth systems
+  - MCP ergonomics beyond the initial narrow wedge (pagination/advanced discovery ergonomics)
 
 ## files changed
 - `.ai/active/SPRINT_PACKET.md`
-- `apps/api/src/alicebot_api/cli.py`
-- `apps/api/src/alicebot_api/cli_formatting.py`
-- `apps/api/src/alicebot_api/__main__.py`
-- `apps/api/src/alicebot_api/__init__.py`
+- `apps/api/src/alicebot_api/mcp_server.py`
+- `apps/api/src/alicebot_api/mcp_tools.py`
 - `pyproject.toml`
-- `tests/unit/test_cli.py`
-- `tests/integration/test_cli_integration.py`
+- `tests/unit/test_mcp.py`
+- `tests/integration/test_mcp_server.py`
+- `tests/integration/test_mcp_cli_parity.py`
 - `README.md`
 - `ROADMAP.md`
 - `.ai/handoff/CURRENT_STATE.md`
@@ -59,43 +68,39 @@ Ship `P9-S34` by adding a deterministic local CLI for core continuity flows (`ca
 - `./scripts/migrate.sh`
   - PASS (required elevated local DB access)
 - `./scripts/load_sample_data.sh`
-  - PASS (`status=noop`, fixture already present)
-- `APP_RELOAD=false ./scripts/api_dev.sh` + `curl -sS http://127.0.0.1:8000/healthz`
-  - PASS (`status=ok`)
+  - PASS (`status=noop`, fixture already loaded)
+- `APP_RELOAD=false ./scripts/api_dev.sh`
+  - PASS (server started on `http://127.0.0.1:8000`)
+- `curl -sS http://127.0.0.1:8000/healthz`
+  - PASS (`status":"ok"`)
 - `./.venv/bin/python -m alicebot_api --help`
   - PASS
-- `./.venv/bin/python -m alicebot_api status`
-  - PASS (database reachable, continuity metrics rendered)
-- `./.venv/bin/python -m alicebot_api recall --query local-first`
-  - PASS (deterministic ordered output with provenance snippets)
-- `./.venv/bin/python -m alicebot_api resume`
-  - PASS (last decision/open loops/recent changes/next action sections)
-- `./.venv/bin/python -m alicebot_api open-loops --limit 20`
+- `./.venv/bin/python -m alicebot_api.mcp_server --help`
   - PASS
-- `./.venv/bin/python -m alicebot_api capture "Decision: CLI verification keeps deterministic continuity output." --explicit-signal decision`
-  - PASS
-- `./.venv/bin/python -m alicebot_api review queue --status correction_ready --limit 20`
-  - PASS
-- `./.venv/bin/python -m alicebot_api review show b5bfdbcc-cbb2-440f-9e4e-7ebabdb41f3f`
-  - PASS
-- `./.venv/bin/python -m alicebot_api review apply b5bfdbcc-cbb2-440f-9e4e-7ebabdb41f3f --action supersede ...`
-  - PASS
-- `./.venv/bin/python -m alicebot_api recall --query local-first --limit 20` (post-correction)
-  - PASS (updated active decision ranked ahead of superseded prior decision)
-- `./.venv/bin/python -m alicebot_api resume --max-recent-changes 5 --max-open-loops 5` (post-correction)
-  - PASS (last decision updated deterministically after correction)
-- `./.venv/bin/python -m pytest tests/unit/test_cli.py -q`
+- `./.venv/bin/python -m pytest tests/unit/test_mcp.py -q`
   - PASS (`5 passed`)
-- `./.venv/bin/python -m pytest tests/integration/test_cli_integration.py -q`
+- `./.venv/bin/python -m pytest tests/integration/test_mcp_server.py -q`
+  - PASS (`1 passed`)
+- `./.venv/bin/python -m pytest tests/integration/test_mcp_cli_parity.py -q`
   - PASS (`1 passed`)
+- `./.venv/bin/python -m pytest tests/unit/test_mcp.py tests/integration/test_mcp_server.py tests/integration/test_mcp_cli_parity.py -q`
+  - PASS (`7 passed`)
 - `./.venv/bin/python -m pytest tests/unit tests/integration`
-  - PASS (`954 passed in 85.02s`) (required elevated local DB access)
+  - PASS (`961 passed in 97.32s`) (required elevated local DB access)
 - `pnpm --dir apps/web test`
-  - PASS (`192 passed`)
+  - PASS (`57 files, 192 tests`)
+- MCP smoke client against new entrypoint (`python -m alicebot_api.mcp_server`)
+  - PASS
+  - initialize protocol: `2024-11-05`
+  - `alice_recall`: `isError=false`, returned count `3`
+  - `alice_resume`: `isError=false`, last decision present
 
 ## blockers/issues
-- Sandbox-restricted localhost Postgres access required elevated execution for DB-backed commands/tests.
-- Initial backend full-suite run failed at collection due duplicate test-module basename (`test_cli.py` in both unit and integration); resolved by renaming integration test file to `tests/integration/test_cli_integration.py`.
+- Sandbox restrictions required elevated execution for localhost Postgres connections and binding to localhost `:8000`.
+- Initial MCP integration test failure due missing `if __name__ == "__main__":` in `mcp_server.py`; fixed by adding module entry invocation.
+- Remaining non-sprint workspace artifacts are limited to untracked local archive directories:
+  - `.ai/archive/`
+  - `docs/archive/planning/`
 
 ## recommended next step
-Start `P9-S35` by mirroring the shipped CLI continuity contract via a narrow MCP tool surface, with parity tests that compare MCP outputs to current CLI deterministic output for the same dataset/scope.
+Start `P9-S36` by implementing the OpenClaw adapter against the now-stable MCP tool contract, keeping strict parity checks so adapter integration does not reopen continuity transport semantics.

README.md

@@ -2,7 +2,7 @@
 
 Alice is a local-first memory and continuity engine for AI agents.
 
-`P9-S33` shipped the public-core baseline. `P9-S34` ships a deterministic local CLI for continuity flows on top of that baseline.
+`P9-S33` shipped the public-core baseline. `P9-S34` shipped the deterministic local CLI for continuity flows on top of that baseline. `P9-S35` now ships a narrow MCP transport for the same continuity contract.
 
 ## Canonical Local Startup Path (`P9-S33`)
 
@@ -54,6 +54,60 @@ Run these against the `P9-S33` sample dataset after startup:
 
 The CLI output is deterministic text (stable section order and provenance snippets) to support `P9-S35` MCP parity.
 
+## MCP Invocation Path (`P9-S35`)
+
+Run the MCP server from the same local runtime used by CLI:
+
+```bash
+./.venv/bin/python -m alicebot_api.mcp_server --help
+./.venv/bin/python -m alicebot_api.mcp_server
+```
+
+Optional console-script entrypoint (after editable install):
+
+```bash
+alicebot-mcp --help
+alicebot-mcp
+```
+
+MCP uses the same local auth/config scope as CLI:
+
+- `DATABASE_URL` selects the local database
+- `ALICEBOT_AUTH_USER_ID` selects the user scope (or `--user-id`)
+- if unset, scope defaults to `00000000-0000-0000-0000-000000000001`
+
+Initial ADR-003 MCP tools:
+
+- `alice_capture`
+- `alice_recall`
+- `alice_resume`
+- `alice_open_loops`
+- `alice_recent_decisions`
+- `alice_recent_changes`
+- `alice_memory_review`
+- `alice_memory_correct`
+- `alice_context_pack`
+
+### Compatible Client Example (Claude Desktop MCP)
+
+`claude_desktop_config.json` example:
+
+```json
+{
+  "mcpServers": {
+    "alice-core": {
+      "command": "/ABSOLUTE/PATH/TO/AliceBot/.venv/bin/python",
+      "args": ["-m", "alicebot_api.mcp_server"],
+      "cwd": "/ABSOLUTE/PATH/TO/AliceBot",
+      "env": {
+        "DATABASE_URL": "postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot",
+        "ALICEBOT_AUTH_USER_ID": "00000000-0000-0000-0000-000000000001"
+      }
+    }
+  }
+}
+```
+
 ## Essential Verification Commands
 
 - API health: `curl -sS http://127.0.0.1:8000/healthz`

REVIEW_REPORT.md

@@ -4,35 +4,51 @@
 PASS
 
 ## criteria met
-- `P9-S34` packaged CLI entrypoint is implemented and callable from documented local install path (`python -m alicebot_api`).
-- Required command coverage is present: `capture`, `recall`, `resume`, `open-loops`, `review queue`, `review show`, `review apply`, `status`.
-- CLI output is deterministic and terminal-friendly, with stable section ordering, explicit empty states, and provenance/trust fields where relevant.
-- Correction flow is wired end-to-end and deterministically updates later recall/resume outcomes.
-- Sprint docs are aligned with delivered CLI surface (`README.md`, `ROADMAP.md`, `.ai/handoff/CURRENT_STATE.md`, reports).
-- Merge-readiness gap is resolved: required new CLI/test files are now added to git (no longer untracked).
-- The only remaining non-sprint worktree paths are local archive directories explicitly excluded from merge scope (`.ai/archive/`, `docs/archive/planning/`).
+- Runnable MCP server entrypoint is implemented and callable from the documented local path: `python -m alicebot_api.mcp_server`, with console-script packaging via `alicebot-mcp`.
+- ADR-003 initial MCP tool surface is implemented with deterministic schemas and fixed ordering:
+  - `alice_capture`
+  - `alice_recall`
+  - `alice_resume`
+  - `alice_open_loops`
+  - `alice_recent_decisions`
+  - `alice_recent_changes`
+  - `alice_memory_review`
+  - `alice_memory_correct`
+  - `alice_context_pack`
+- One MCP-capable client path can call `alice_recall` successfully against the local runtime, verified in `tests/integration/test_mcp_server.py`.
+- One MCP-capable client path can call `alice_resume` successfully against the local runtime, verified in `tests/integration/test_mcp_server.py`.
+- Correction through `alice_memory_correct` changes later retrieval/resumption behavior deterministically, verified in `tests/integration/test_mcp_server.py`.
+- MCP outputs remain narrow, deterministic, and provenance-backed through direct transport wrappers over shipped continuity seams in `apps/api/src/alicebot_api/mcp_tools.py`.
+- Parity evidence exists between MCP and shipped CLI/core behavior in `tests/integration/test_mcp_cli_parity.py`.
+- Sprint docs are aligned with the delivered MCP surface in `README.md`, `ROADMAP.md`, `.ai/handoff/CURRENT_STATE.md`, `BUILD_REPORT.md`, and this report.
 
 ## criteria missed
 - None.
 
 ## quality issues
-- No blocking quality issues identified for `P9-S34` scope.
-- Existing out-of-scope tracked churn previously noted in planning docs has been removed from the tracked diff.
+- No blocking quality issues found in sprint scope.
+- The sprint diff includes the MCP source and test files required by the packet, so the delivered feature matches the actual branch payload.
 
 ## regression risks
-- Low. Relevant CLI unit/integration tests and full backend/web suites pass in this environment.
-- Residual risk is standard future contract drift risk if downstream (`P9-S35`) parity tests are not kept strict against CLI behavior.
+- Low.
+- Directly verified during review:
+  - `./.venv/bin/python -m alicebot_api.mcp_server --help`
+  - `./.venv/bin/python -m pytest tests/unit/test_mcp.py tests/integration/test_mcp_server.py tests/integration/test_mcp_cli_parity.py -q`
+  - `./.venv/bin/python -m pytest tests/unit tests/integration`
+  - `pnpm --dir apps/web test`
+- Residual risk is future contract drift between MCP and CLI/core behavior if later seams widen payloads without preserving parity tests.
 
 ## docs issues
 - No blocking docs issues in sprint scope.
-- CLI invocation and command examples are present and consistent with shipped runtime behavior.
+- `README.md` includes the exact local MCP startup path, auth/config assumptions, and one compatible client configuration example.
+- The only remaining non-sprint worktree paths are local archive directories explicitly excluded from merge scope (`.ai/archive/`, `docs/archive/planning/`).
 
 ## should anything be added to RULES.md?
-- Optional hardening: add a rule to avoid duplicate pytest module basenames across different test directories to prevent collection/import collisions.
+- Optional hardening: require new runnable module entrypoints to include explicit `if __name__ == "__main__":` invocation whenever `python -m ...` is part of the documented startup path.
 
 ## should anything update ARCHITECTURE.md?
-- No required update. Implementation aligns with existing Phase 9 public-layer architecture and does not alter core semantics.
+- No required update. The implementation stays within the existing Phase 9 architecture and ADR-003 by treating MCP as a transport wrapper over shipped continuity seams.
 
 ## recommended next action
-1. Finalize PR with current scoped changes and verification evidence.
-2. Begin `P9-S35` by mirroring this CLI contract in MCP with explicit parity tests.
+1. Finalize the sprint PR from the current staged diff.
+2. Keep `tests/integration/test_mcp_cli_parity.py` as a required guard while building `P9-S36` so adapter work does not reopen MCP transport semantics.

ROADMAP.md

@@ -38,13 +38,13 @@ Success condition:
 - terminal commands for capture, recall, resume, open loops, review, correction, and status
 - deterministic terminal formatting with provenance snippets
 
-### P9-S35: MCP Server (next active seam)
+### P9-S35: MCP Server (shipped baseline)
 
 - small stable MCP tool surface
 - local interop examples for compatible clients
 - deterministic tool contracts
 
-### P9-S36: OpenClaw Adapter
+### P9-S36: OpenClaw Adapter (next active seam)
 
 - import path for OpenClaw durable memory/workspace data
 - Alice MCP augmentation mode for OpenClaw-style workflows
@@ -80,6 +80,7 @@ Success condition:
 
 - Phase 8 delivered operational chief-of-staff handoffs, routing, outcome learning, and closure quality.
 - `P9-S33` delivered the public-safe `alice-core` boundary, canonical local startup path, and deterministic sample-data proof.
+- `P9-S34` delivered the shipped local CLI continuity contract that `P9-S35` should mirror through MCP.
 
 ## Legacy Compatibility Markers