MemoPop Connector API, Phase 1: Foundation
The registry, errors, auth, storage, five tools, the docs generators, the ledger, and CI. Every later phase builds on this one.
- Path
- plans/MemoPop-Connector-API-Phase-1-Foundation.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5 (1M context)
- Tags
- Plan · MemoPop · Claude-Connector · Model-Context-Protocol · TDD
MemoPop Connector API, Phase 1: Foundation
Read the spec first: context-v/specs/MemoPop-Connector-API.md. It is the
contract; this plan is the order of work. Then read the loop:
context-v/loops/Run-the-Connector-Plans-With-a-VP-Eng-and-Subagents.md.
What this phase delivers
A running FastAPI app that serves the connector over MCP at /mcp and REST at
/v1/, with five working tools (list_deals, create_new_deal,
next_step, submit_artifact, get_artifact), all eight tools declared in
the registry (the other three registered with full docs but returning
invalid / not_implemented until their phases land, which keeps
CONN-REG-01 honest from day one), generated docs, auth, the ledger, and a CI
workflow that runs it all.
Phases 4, 5, and 6 will run in parallel on top of this. Lay the code out so
each of them touches mostly its own files: one module per tool under
src/connector/tools/, one instruction file per step under
src/connector/steps/, and tool and step registration that adds a line per
item rather than editing shared logic.
Step 0: the ledger and the ladder (do first)
Copy corpora-builder’s ledger, knots-style (copy, never import across repos):
../../../corpora-builder/src/ledger.py→src/ledger.py../../../corpora-builder/scripts/spec_status.py→scripts/spec_status.py- The spec-marker and results hooks from
../../../corpora-builder/tests/conftest.py→tests/conftest.py
Adapt:
- The Tests section ends only at a level-2 heading. This spec groups its
IDs under
###subheadings; corpora-builder’s parser stops at any heading. - Drop the frontend (
app/) merging. - Specs without a
## Teststable are ignored (the orchestrator has many). - Add
.spec-results.jsonto.gitignore. - Add
--plan <file>(or--ids), so a plan’s owned IDs can be checked alone.
Add scripts/check.sh, the ladder: ruff check src/connector tests/connector,
black --check src/connector tests/connector, pytest, then the ledger.
Scope lint to the new code; don’t reformat the rest of the repo.
Add .github/workflows/connector-tests.yml: on push and pull request to
development and main, check out with submodules: false, install with
uv, install jj and pandoc, run scripts/check.sh. Then run the whole
existing suite in a fresh clone without io/; if existing tests fail there,
don’t edit them. Make CI run the connector tests and the ledger as blocking and
report the rest, and say so in the changelog.
Step 1: failing tests (the TDD floor)
Write tests/connector/ with one test per owned ID, each marked
@pytest.mark.spec("CONN-…"). Fixtures in tests/connector/fixtures/: the
test-firm workspace under tmp_path, fixture-co with a three-section
outline, a local-directory bucket, and canned artifacts. Nothing reads io/.
Run scripts/spec_status.py --plan on this plan. Every owned ID must be RED,
none MISSING, before any implementation.
Step 2: implement, in this order
errors.py: the envelope and the full code catalogue from the spec, each with its kind and docs text.api_versionon every response.workspace.py: firm and deal paths underMEMO_IO_ROOT,deal.jsonwith a per-deal lock, artifact read and write, and aBucketinterface with a local-directory implementation and an S3 implementation (endpoint, key, and bucket from env; boto3 is fine). jj and snapshots are phase 6: leave aHistoryhook that phase 6 fills (a no-op here).registry/: tool and step definitions as dataclasses, matching the spec’s field tables. Register all eight tools with complete docs, and the steps from §First mapping. Write the instruction files forresearch.sectionanddraft.sectionnow, adapted fromsrc/agents/perplexity_section_researcher.pyandsrc/agents/writer.py(strip every model and API call; end with how to submit). Other Claude steps get a stub instruction that phase 5 replaces, but must still satisfyCONN-REG-05.- The five tools, as transport-free functions over a
Workspace. Deal state and ordering per §Deal state. Templates come fromtemplates/outlines/*.yaml; the firm default isdirect-early-stage-12Psunless the firm config says otherwise. auth.py: static per-firm keys from env (MEMOPOP_STATIC_KEYS, for Claude Code and the health check only), and JWT verification against a JWKS URL (MEMOPOP_JWKS_URL, defaulthttps://id.didi.sh/.well-known/jwks.json) with audiencehttps://memopop.didi.shand the firm from the entity claim. Tests use a locally generated EdDSA keypair and a served JWKS; nothing calls id.didi.sh. Serve/.well-known/oauth-protected-resource, building URLs from a configured public base URL, never from the request scheme (CONN-AUTH-02).mcp_app.pyandrest_app.py: both generated from the registry. Use the official MCP Python SDK (mcp) over Streamable HTTP, mounted at/mcpon the existing app insrc/server/app.py. SetreadOnlyHintanddestructiveHinton every tool. MCP and REST must return the same body (CONN-STEP-08).docs_build.py:/v1/openapi.json,/llms.txt,/llms-full.txt,/docs,/docs/errors,/docs/changelog, all from the registry. Plain server-rendered HTML for/docs; no frontend build.
Re-read context-v/blueprints/Transport-Contract-and-API-Conventions.md before naming
anything; follow it where it doesn’t conflict with the spec.
Rules
- Never edit a test to make it pass. If a test can’t pass against honest code, stop and report it.
- No model calls anywhere in the connector, and no new
anthropicclient (tests/test_pipeline_reference.pyenforces the latter). - The existing 22 routes and their tests keep working.
- Add dependencies with
uv add; neverpip. - Don’t touch
io/,main, ormaster.
Done when
scripts/check.shpasses and the ledger shows every owned ID GREEN.- The existing suite still passes locally (554 passed, 2 skipped at the start).
- CI is green on the branch.
- A changelog entry in
changelog/(perchangelog-conventions; see the repo’s recent entries for shape) says what landed and what was not tested. - The branch is pushed. Report back: the ledger output, the suite counts, the CI run URL, and anything in the spec you think is wrong.