Task Plan

Author: Team Lead Date: 2026-03-27 Status: Planning

User Request

Implement the Claude Context MCP Server as specified in specification.md. The server is a Cloudflare Worker exposing MCP tools that serve skills, agent profiles, and documentation from GitHub repositories. The target repository is Arda-cards/skills-mcp (currently empty).

Reference Documents

Document	Path	Purpose
Specification	specification.md	Full design, API contracts, decisions
Design	design.md	Architecture diagrams, test strategy, pipeline design
Requirements	requirements.md	27 functional requirements with unique IDs
Verification	verification.md	50 test cases mapped to requirements
Implementation Changes	implementation-changes.md	Per-file implementation instructions with code templates
Team Split Assessment	team-split-assessment.md	Complexity analysis — single team recommended

Decomposition

Task List

#	Task	Persona	Depends On	Status	Notes
1	Create package.json with dependencies and scripts	devops-engineer	—	Pending	Follow hypothesis-mcp patterns; add Cloudflare-specific deps
2	Create tsconfig.json and tsconfig.eslint.json	devops-engineer	—	Pending	Use bundler module resolution (not NodeNext)
3	Create .prettierrc, eslint.config.js, vitest.config.ts	devops-engineer	—	Pending	Identical to hypothesis-mcp
4	Create wrangler.toml	devops-engineer	—	Pending	Per specification §wrangler.toml
5	Update .gitignore	devops-engineer	—	Pending	Add src/generated/, .wrangler/, .dev.vars
6	Create CHANGELOG.md and .github/clq/changemap.json	devops-engineer	—	Pending	Identical CLQ config to hypothesis-mcp
7	Create scripts/ensure-generated.js (placeholder indexes)	devops-engineer	—	Pending	Creates empty JSON files in src/generated/
8	GATE: Scaffolding complete	—	1-7	Pending	npm ci succeeds, npx tsc --noEmit succeeds with placeholders
9	Create src/types.ts (Env, response types, index entry types)	back-end-engineer	8	Pending	Per implementation-changes §2.1
10	Create src/auth.ts (token decode + PAT format validation)	back-end-engineer	9	Pending	URL-safe Base64 decode, prefix check (ghp_, github_pat_, gho_)
11	Create src/validation.ts (path traversal checks)	back-end-engineer	9	Pending	Reject .., leading /, \
12	Create src/github.ts (GitHub Contents API client)	back-end-engineer	9	Pending	fetchGitHubContent, fetchGitHubContentOrNull, error mapping
13	Create src/cache.ts (Cloudflare Cache API wrapper)	back-end-engineer	9	Pending	getCached, setCached, buildCacheKey; 10-min TTL
14	Create src/index.ts (McpAgent + 7 tool registrations)	back-end-engineer	10-13	Pending	Main entry point; imports bundled indexes
15	GATE: Source compiles	—	14	Pending	npx tsc --noEmit passes; wrangler dev starts without errors
16	Create scripts/build-skills-agents-index.js	back-end-engineer	8	Pending	js-yaml parser, companion file manifest, graceful fallback
17	Create scripts/build-docs-index.js	back-end-engineer	8	Pending	js-yaml parser, .md + .mdx, hierarchical tree
18	GATE: Index generation works	—	16, 17	Pending	Run scripts against local clones of source repos; verify JSON output
19	Create tests/auth.test.ts	back-end-engineer	10	Pending	AUTH-T01 through AUTH-T05a
20	Create tests/validation.test.ts	back-end-engineer	11	Pending	SEC-T01 through SEC-T05
21	Create tests/github.test.ts	back-end-engineer	12	Pending	Mocked fetch; SKILL-T03/T04, AUTH-T06/T07/T08, DOC-T03/T04/T05
22	Create tests/cache.test.ts	back-end-engineer	13	Pending	Mocked Cache API; SKILL-T05/T06, cache key construction
23	Create tests/tools.test.ts	back-end-engineer	14	Pending	SKILL-T01/T02, AGENT-T01/T02, DOC-T01/T02, SKILL-T07/T08
24	GATE: All tests pass	—	19-23	Pending	npm test passes; npm run lint passes; npm run typecheck passes
25	Create .github/workflows/publish.yml	devops-engineer	24	Pending	3 triggers, 3 jobs (validate-changelog, build-and-test, generate-and-deploy)
26	Create .github/workflows/pull_request_upkeep.yml	devops-engineer	8	Pending	Identical to hypothesis-mcp
27	Create README.md (installation and usage guide)	back-end-engineer	15	Pending	Per implementation-changes §6.1; PAT creation, Base64 encoding, client setup
28	GATE: CI pipeline green	—	25, 26, 27	Pending	Push to branch, open PR, verify all checks pass
29	Merge to main and verify deployment	devops-engineer	28	Pending	Merge PR; verify Worker is live; run manual smoke test checklist
30	Configure branch protection rules	devops-engineer	29	Pending	Match hypothesis-mcp: require PR reviews, require status checks

Worktree Strategy

Single directory — no worktrees needed. This is a greenfield project in its own repository (Arda-cards/skills-mcp) with a single implementing agent writing files sequentially.

Parallelization

The plan is largely sequential due to the nature of the work (each phase builds on the previous). Within phases, some tasks are independent:

• Parallel group 1 (Phase 1): Tasks 1-7 are independent scaffolding files. Can be written in any order.
• Parallel group 2 (Phase 2): Tasks 10, 11, 12, 13 are independent modules (all depend on types.ts from Task 9). Task 14 depends on all four.
• Parallel group 3 (Phase 3): Tasks 16, 17 are independent build scripts.
• Parallel group 4 (Phase 4): Tasks 19-23 can be written in parallel once their corresponding source modules exist.
• Sequential chain: Tasks 8 → 15 → 18 → 24 → 28 → 29 → 30 (gates must pass in order).

With a single agent, the effective execution is sequential. The parallelization groups indicate which tasks within a phase have no internal ordering constraints.

Idle Agent Strategy

Not applicable — single agent execution.

Personas Required

Persona	Tasks Assigned	Worktree	Spawn Order
devops-engineer	1-8, 25, 26, 29, 30	N/A (main repo)	Primary for Phase 1 and Phase 5-6
back-end-engineer	9-14, 16-17, 19-24, 27	N/A (main repo)	Primary for Phases 2-4

With single-agent execution, one agent assumes both roles sequentially.

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	McpAgent API for auth header access	(a) Override lifecycle method, (b) this.request, (c) Forward as query param	Investigate during Task 14; keep auth.ts as pure function regardless	Open
2	Durable Objects config in wrangler.toml	(a) Explicit bindings, (b) Auto-configured by McpAgent.mount()	Check agents package docs during Task 4	Open
3	Test approach for Worker-specific code	(a) Vitest + miniflare, (b) Pure logic only	(b) for v1 — test pure functions, verify Worker via manual smoke test	Decided: (b)

Acceptance Criteria

• All 7 MCP tools implemented and returning correct responses (list_skills, get_skill, get_skill_file, list_agents, get_agent, list_docs, get_doc)
• list_* tools serve bundled indexes with zero runtime GitHub API calls
• get_* tools fetch from GitHub with 10-minute cache and skipCache bypass
• Path traversal validation rejects .., absolute paths, and backslashes
• PAT format validation rejects decoded tokens without recognized prefix
• Build scripts generate correct indexes from source repo frontmatter (js-yaml)
• Graceful fallback: missing frontmatter produces name=filename, description=null
• get_doc resolves index.md first, falls back to *.md
• get_skill_file returns Base64-encoded content as-is from GitHub
• CI pipeline runs on push to main, Saturday cron, and workflow_dispatch
• All unit tests pass (npm test)
• Linting and type-checking pass (npm run lint, npm run typecheck)
• CHANGELOG validates with clq
• README includes PAT creation, Base64 encoding, and MCP client setup instructions
• Worker deploys successfully to Cloudflare Workers
• Branch protection rules configured on main
• Manual smoke test passes (all 7 tools, error cases, cache behavior)

Risks and Blockers

Risk / Blocker	Impact	Mitigation
McpAgent API differs from assumptions	Task 14 (index.ts) may need significant rework	Implement and test all pure modules (auth, validation, github, cache) first. Defer McpAgent integration to last. The agents package API surface is small — worst case is adjusting the lifecycle method for auth header access.
Cloudflare agents package requires Durable Objects config not covered in spec	wrangler.toml may need [durable_objects] and [[migrations]] sections	Test with wrangler dev early (after Task 4). Adjust wrangler.toml before proceeding to Phase 2.
Source repo structure changes before first deploy	Generated indexes may not match expectations	Build scripts have graceful fallback. Test against actual repo clones during Task 18 gate.
GitHub Actions secrets not yet configured	CI deploy step will fail	Non-blocking for development. Configure secrets before the merge-to-main step (Task 29).

Project Completion Artifacts

Byproducts (byproducts/)

File	Description
changelog.md	Summary of changes made during implementation
learnings.md	Insights about Cloudflare Workers, McpAgent API, or MCP protocol discovered during implementation
suggestions.md	Improvement ideas, tech debt, or follow-up work identified

Task Tracking Protocol

The agent’s TodoWrite list is the single source of truth for task status. At each gate:

1. Verify all preceding tasks are marked completed
2. Run the gate verification (npm test, tsc —noEmit, etc.)
3. Only proceed to the next phase if the gate passes

Progress Log

Date	Event	Notes
2026-03-27	Plan created