Commit eb0c01
2026-03-13 01:48:48 Claude (Dev): [mcp] Port Phase 0 tasks to wiki| /dev/null .. tasks/phase 0.md | |
| @@ 0,0 1,225 @@ | |
| + | ## How to read this document |
| + | |
| + | - **Dependencies** list task IDs that must be complete before this task starts |
| + | - **Parallel group** identifies tasks that can run simultaneously within a phase |
| + | - **Target** identifies which repo and branch the work goes into |
| + | - Tasks are numbered `P{phase}-{sequence}` (e.g., P0-3) |
| + | - Acceptance criteria are binary — pass or fail, no judgment calls |
| + | |
| + | --- |
| + | |
| + | ## Phase 0: Proof of Concept |
| + | |
| + | **Goal:** Validate the two core technical risks: git on EFS via Lambda, and MCP OAuth via WorkOS. |
| + | |
| + | **Two independent tracks** that can run with separate managers: |
| + | - Track A: EFS + Lambda (P0-1 → P0-5) |
| + | - Track B: WorkOS + MCP auth (P0-6 → P0-8) |
| + | |
| + | ### P0-1: Pulumi Scaffold |
| + | |
| + | **Parallel group:** Track A start |
| + | **Dependencies:** None |
| + | **Target:** `wikibot-io` repo, `feat/P0-1-pulumi-scaffold` |
| + | |
| + | **Description:** |
| + | Create the Pulumi project with foundational AWS infrastructure: VPC with 1 public and 1 private subnet (single AZ for dev), security groups, route tables, and gateway endpoints for DynamoDB and S3. |
| + | |
| + | **Deliverables:** |
| + | - `infra/__main__.py` with top-level composition |
| + | - `infra/components/vpc.py` — VPC, subnets, security groups, route tables, gateway endpoints |
| + | - Unit tests verifying resource creation and security group rules |
| + | - `pulumi up` succeeds against the dev stack |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] VPC created with correct CIDR, 1 public + 1 private subnet |
| + | - [ ] Gateway endpoints for DynamoDB and S3 attached to private subnet route table |
| + | - [ ] Security group allows Lambda → EFS (NFS port 2049) and Lambda → internet (egress) |
| + | - [ ] All resources tagged with `project: wikibot-io`, `environment: dev` |
| + | - [ ] Unit tests pass with `pulumi.runtime.set_mocks()` |
| + | - [ ] `pulumi up` succeeds |
| + | |
| + | --- |
| + | |
| + | ### P0-2: EFS + Lambda Basic |
| + | |
| + | **Parallel group:** Track A |
| + | **Dependencies:** P0-1 |
| + | **Target:** `wikibot-io` repo, `feat/P0-2-efs-lambda` |
| + | |
| + | **Description:** |
| + | Add EFS filesystem with mount target in the private subnet. Create a Lambda function (Python 3.12, VPC-attached) that mounts EFS and performs basic file read/write. This validates the core infrastructure pattern. |
| + | |
| + | **Deliverables:** |
| + | - `infra/components/efs.py` — EFS filesystem, mount target, access point |
| + | - `infra/components/lambda_functions.py` — Lambda function with VPC config and EFS mount |
| + | - `app/poc/efs_test.py` — Lambda handler that writes a file, reads it back, returns timing |
| + | - IAM role with EFS and VPC permissions |
| + | - Integration test that invokes the Lambda and verifies file persistence |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Lambda can write a file to EFS at `/mnt/efs/test.txt` |
| + | - [ ] Lambda can read the file back and content matches |
| + | - [ ] File persists across Lambda invocations (cold and warm) |
| + | - [ ] Integration test passes |
| + | - [ ] Lambda execution time logged |
| + | |
| + | --- |
| + | |
| + | ### P0-3: Git on EFS |
| + | |
| + | **Parallel group:** Track A |
| + | **Dependencies:** P0-2 |
| + | **Target:** `wikibot-io` repo, `feat/P0-3-git-efs` |
| + | |
| + | **Description:** |
| + | Lambda function that initializes a bare git repo on EFS, commits a markdown file, reads it back, and lists commits. Validates that git operations work correctly on NFS-mounted storage. |
| + | |
| + | Investigate git library choice: gitpython (shells out to `git` binary — verify availability in Lambda runtime) vs. dulwich (pure Python, no binary dependency). If `git` is not available in the Lambda runtime, use dulwich. Document the decision. |
| + | |
| + | **Deliverables:** |
| + | - `app/poc/git_test.py` — Lambda handler: init bare repo, commit file, read file, list history |
| + | - Decision documented: gitpython vs. dulwich, with rationale |
| + | - Integration test that exercises the full git lifecycle |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Bare git repo created on EFS at a specified path |
| + | - [ ] Markdown file committed with author, message, and timestamp |
| + | - [ ] File content readable from the repo |
| + | - [ ] Commit history retrievable |
| + | - [ ] Repo persists across Lambda invocations |
| + | - [ ] Concurrent read test: 3 simultaneous Lambda invocations reading the same repo |
| + | - [ ] Git library decision documented with rationale |
| + | |
| + | --- |
| + | |
| + | ### P0-4: X-Ray Tracing |
| + | |
| + | **Parallel group:** Track A (can run parallel with P0-3) |
| + | **Dependencies:** P0-2 |
| + | **Target:** `wikibot-io` repo, `feat/P0-4-xray` |
| + | |
| + | **Description:** |
| + | Enable AWS X-Ray tracing on Lambda and API Gateway. Add custom subsegments for git operations (init, commit, read) so that Phase 0 benchmarks can break down latency by operation. |
| + | |
| + | **Deliverables:** |
| + | - X-Ray tracing enabled on Lambda function(s) via Pulumi |
| + | - Custom subsegment instrumentation in git test Lambda |
| + | - API Gateway stage with X-Ray enabled (if API Gateway exists at this point; otherwise, just Lambda tracing) |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] X-Ray traces visible in AWS console after Lambda invocation |
| + | - [ ] Custom subsegments for git operations appear in trace timeline |
| + | - [ ] Cold start vs. warm start distinguishable in traces |
| + | |
| + | --- |
| + | |
| + | ### P0-5: Performance Benchmarks |
| + | |
| + | **Parallel group:** Track A (final) |
| + | **Dependencies:** P0-3, P0-4 |
| + | **Target:** `wikibot-io` repo, `feat/P0-5-benchmarks` |
| + | |
| + | **Description:** |
| + | Benchmark script that invokes the git Lambda repeatedly and collects timing data. Measures cold start latency, warm read latency, warm write latency, and concurrent access behavior. Results compared against Phase 0 exit criteria. |
| + | |
| + | **Deliverables:** |
| + | - `scripts/benchmark_efs.py` — invokes Lambda N times, collects X-Ray data or Lambda response times |
| + | - Results written to `Dev/Phase 0 — EFS Benchmarks` wiki note |
| + | - Concurrent write test: 5 simultaneous Lambda invocations writing to the same repo |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Warm page read < 500ms (measured over 20+ invocations) |
| + | - [ ] Warm page write < 1s (measured over 20+ invocations) |
| + | - [ ] Cold start < 5s total (measured over 5+ cold starts) |
| + | - [ ] Concurrent reads succeed without errors |
| + | - [ ] Concurrent writes succeed (git locking handles serialization) |
| + | - [ ] Results documented in wiki |
| + | |
| + | --- |
| + | |
| + | ### P0-6: WorkOS AuthKit Setup |
| + | |
| + | **Parallel group:** Track B start (independent of Track A) |
| + | **Dependencies:** None |
| + | **Target:** `wikibot-io` repo, `feat/P0-6-workos-setup` |
| + | |
| + | **Description:** |
| + | Set up WorkOS AuthKit with Google OAuth provider. Configure the WorkOS dashboard, obtain API keys, and write a minimal test that authenticates a user and retrieves their profile including raw OAuth provider `sub` claim. |
| + | |
| + | **Deliverables:** |
| + | - WorkOS AuthKit configuration (documented, not in code — dashboard setup) |
| + | - `app/poc/workos_test.py` — script that initiates OAuth flow and prints user profile |
| + | - WorkOS API key stored in Pulumi config (`pulumi config set --secret workos_api_key`) |
| + | - Documentation of provider sub retrieval (especially Apple, if testable) |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Google OAuth login flow completes successfully |
| + | - [ ] User profile retrieved with email, name, and raw Google `sub` claim |
| + | - [ ] API key securely stored in Pulumi config |
| + | - [ ] Apple provider sub retrieval status documented (verified or flagged as unavailable) |
| + | |
| + | --- |
| + | |
| + | ### P0-7: FastMCP + WorkOS on Lambda |
| + | |
| + | **Parallel group:** Track B |
| + | **Dependencies:** P0-2, P0-6 |
| + | **Target:** `wikibot-io` repo, `feat/P0-7-mcp-workos-lambda` |
| + | |
| + | **Description:** |
| + | Deploy a minimal FastMCP server on Lambda with WorkOS OAuth 2.1 authentication. The MCP server exposes a single test tool (e.g., `echo`) that returns its input. Uses Streamable HTTP transport (not SSE). Validates that the FastMCP + WorkOS integration works on Lambda behind API Gateway. |
| + | |
| + | Reference the existing `otterwiki-mcp` auth implementation for patterns (MultiAuth, InMemoryOAuthProvider, StaticTokenVerifier). |
| + | |
| + | **Deliverables:** |
| + | - `app/poc/mcp_server.py` — minimal FastMCP server with WorkOS auth and one test tool |
| + | - Mangum adapter wrapping the MCP server for Lambda |
| + | - API Gateway route for MCP endpoint |
| + | - Unit tests for auth setup (mock WorkOS) |
| + | - Integration test that calls the echo tool with a valid token |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] MCP server deploys to Lambda successfully |
| + | - [ ] API Gateway routes to MCP endpoint |
| + | - [ ] OAuth 2.1 flow completes (WorkOS issues token, MCP server validates) |
| + | - [ ] Test tool callable with valid auth token |
| + | - [ ] Invalid/missing tokens rejected |
| + | - [ ] Bearer token auth works alongside OAuth (if MCP_AUTH_TOKEN configured) |
| + | |
| + | --- |
| + | |
| + | ### P0-8: Claude.ai MCP End-to-End |
| + | |
| + | **Parallel group:** Track B (final) |
| + | **Dependencies:** P0-7 |
| + | **Target:** Manual testing (no code deliverable) |
| + | |
| + | **Description:** |
| + | Connect Claude.ai to the MCP endpoint deployed in P0-7. Verify that Claude.ai can authenticate via WorkOS OAuth and call the test tool. This is a manual test performed by the human or the manager. |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Claude.ai MCP connection configured with the endpoint URL |
| + | - [ ] OAuth flow completes in Claude.ai |
| + | - [ ] Claude.ai can call the echo tool and receive a response |
| + | - [ ] Results documented in wiki |
| + | |
| + | --- |
| + | |
| + | ### P0-9: Billing Alarm |
| + | |
| + | **Parallel group:** Can run anytime after P0-1 |
| + | **Dependencies:** P0-1 |
| + | **Target:** `wikibot-io` repo, `feat/P0-9-billing-alarm` |
| + | |
| + | **Description:** |
| + | Set up AWS Budgets billing alarm with a $50/month threshold. Email notification to the project owner. |
| + | |
| + | **Deliverables:** |
| + | - Pulumi resource for AWS Budget with email alert |
| + | - Alert threshold: $50/month |
| + | |
| + | **Acceptance criteria:** |
| + | - [ ] Budget alarm created |
| + | - [ ] Email notification configured |
| + | - [ ] `pulumi up` succeeds |
| \ | No newline at end of file |