Kickoff

Task

Implement the Claude Context MCP Server — a Cloudflare Worker exposing skills, agent profiles, and documentation over MCP.

Goal File

Read specification.md in this directory first — it is the authoritative specification for this project. It defines the API contracts, authentication design, build process, caching strategy, technology stack (DR-18), and all design decisions (DR-01 through DR-18).

Target Repository

Arda-cards/skills-mcp — currently contains only a .gitignore. All code is written from scratch.

What to Produce

27 files in the Arda-cards/skills-mcp repository, organized in 6 phases. The full file inventory with per-file instructions is in implementation-changes.md.

Source Files (Phase 2)

File	Content
`src/types.ts`	Env interface, GitHub API response types, index entry types, error codes
`src/auth.ts`	URL-safe Base64 token decode, PAT prefix validation (`ghp_`, `github_pat_`, `gho_`)
`src/validation.ts`	Path traversal rejection (`..`, absolute paths, backslashes)
`src/github.ts`	GitHub Contents API client — fetch, error mapping, content decode
`src/cache.ts`	Cloudflare Cache API wrapper — get/set with 10-min TTL, `skipCache` bypass
`src/index.ts`	McpAgent class with 7 tool registrations, bundled index imports

Build Scripts (Phase 3)

File	Content
`scripts/build-skills-agents-index.js`	Generate skills + agents indexes from YAML frontmatter (js-yaml)
`scripts/build-docs-index.js`	Generate docs index from Astro content frontmatter (.md + .mdx)

Tests (Phase 4)

File	Content
`tests/auth.test.ts`	Token decode, Base64 edge cases, PAT format validation
`tests/validation.test.ts`	Path traversal rejection
`tests/github.test.ts`	Mocked fetch — URL construction, content decode, error mapping, index.md fallback
`tests/cache.test.ts`	Mocked Cache API — hit/miss, skipCache, key construction
`tests/tools.test.ts`	Tool handler logic — bundled indexes, get_* integration with mocks

Infrastructure (Phases 1, 5, 6)

File	Content
`package.json`	Dependencies, scripts, Cloudflare Worker config
`tsconfig.json` / `tsconfig.eslint.json`	TypeScript strict mode, bundler resolution
`wrangler.toml`	Worker config, environment variables, compatibility_date
`.prettierrc` / `eslint.config.js` / `vitest.config.ts`	Code quality tooling
`.gitignore`	Updated with `src/generated/`, `.wrangler/`
`CHANGELOG.md` / `.github/clq/changemap.json`	Changelog with clq validation
`scripts/ensure-generated.js`	Placeholder indexes for local dev
`.github/workflows/publish.yml`	CI/CD — 3 triggers, index generation, Cloudflare deploy
`.github/workflows/pull_request_upkeep.yml`	PR project board automation
`README.md`	Installation guide, PAT setup, Base64 encoding, MCP client config

How to Work

1. Read All Project Documents First

Read every file in this directory before writing any code. They form a complete specification:

Document	What It Contains
`specification.md`	Full design — API contracts, auth flow, configuration, caching, build process, error handling, decisions DR-01 through DR-18
`design.md`	Architecture diagrams (PlantUML) — runtime flow, deployment, test strategy, pipeline
`requirements.md`	27 functional requirements with unique IDs (REQ-AUTH-, REQ-SKILL-, etc.)
`verification.md`	51 test cases mapped to requirements
`implementation-changes.md`	Per-file implementation instructions with code templates and open questions
`plan/task-plan.md`	30 tasks across 6 phases with gates, parallelization, and acceptance criteria
`plan/team-split-assessment.md`	Complexity analysis — single agent recommended

2. Read the Example Repository

The hypothesis-mcp repository (Arda-cards/hypothesis-mcp, local at /Users/jmp/code/arda/hypothesis-mcp/) is the reference implementation for project structure, code style, CI/CD, and conventions. Read these files:

package.json — dependency patterns, scripts, publish config
src/index.ts — MCP tool registration pattern (server.registerTool())
src/client.ts — API client pattern (generic request<T>(), auth headers, error handling)
src/types.ts — type organization (raw vs normalized)
tests/client.test.ts — test patterns (global fetch mock, fixture helpers)
.github/workflows/publish.yml — CI pipeline (clq, build-and-test, publish)
tsconfig.json — TypeScript strict settings
eslint.config.js — linting rules

Important differences from hypothesis-mcp:

This project is a Cloudflare Worker (not a stdio MCP server)
Uses McpAgent from the agents npm package (not StdioServerTransport)
Uses bundler module resolution (not NodeNext)
Has build scripts that generate bundled indexes
Deploys via wrangler (not npm publish)

3. Follow the Phase Gates

The task plan defines 5 gates. Do not proceed past a gate until it passes:

Gate	After Tasks	Verification
#8: Scaffolding	1-7	`npm ci` succeeds, `npx tsc --noEmit` succeeds with placeholder indexes
#15: Source compiles	9-14	`npx tsc --noEmit` passes, `wrangler dev` starts without errors
#18: Index generation	16-17	Run scripts against local clones of source repos; verify JSON output
#24: Tests pass	19-23	`npm test` passes, `npm run lint` passes, `npm run typecheck` passes
#28: CI green	25-27	Push branch, open PR, all CI checks pass

4. Resolve Open Questions During Implementation

Three questions are flagged as open in the implementation plan. Resolve them as you encounter them:

#	Question	When	How
1	McpAgent API for accessing auth headers	Task 14 (`src/index.ts`)	Read the `agents` npm package source/docs. The auth token must flow from the initial HTTP request to tool handlers. Keep `auth.ts` as a pure function regardless.
2	Durable Objects config in `wrangler.toml`	Task 4	Check if `McpAgent.mount()` or `McpAgent.serve()` auto-configures DO bindings, or if explicit `[durable_objects]` and `[[migrations]]` sections are needed.
3	Test approach for Worker-specific code	Task 19+	Decision: test pure logic only (auth, validation, github client, cache). Verify McpAgent integration via manual smoke test after deploy.

5. Validate Before Pushing

Before any push to the remote:

npm run typecheck
npm run lint
npm test

All three must pass. Do not push with failing checks.

6. Branch and Commit Conventions

Branch name: jmpicnic/skills-mcp/initial-implementation
Commit messages: Conventional style, grouped by phase (e.g., “feat: add project scaffolding”, “feat: implement MCP tools and GitHub client”)
Single PR: One PR from the implementation branch to main

Recommended Skills and Agent Profiles

Skills to Load

These skills must be loaded (via the Skill tool) before writing code. They define conventions that all deliverables must follow.

Skill	Purpose	When
`general-conventions`	Workspace-wide conventions — stdout redirect to `scratch/`, agent branch naming, consultative mode.	Before starting any work.
`kotlin-coding`	Not needed — this is a TypeScript project. Listed here to explicitly exclude it.	N/A
`release-lifecycle`	CHANGELOG management, PR conventions, version extraction.	When writing `CHANGELOG.md` and CI workflow.
`document-writing`	Markdown formatting, frontmatter, link conventions.	When writing `README.md`.

Skills to Consult for Domain Knowledge

Skill	Purpose	Relevant Tasks
`knowledge-base`	Check for relevant entries on MCP servers, Cloudflare Workers, or CI patterns.	All tasks (background context)
`unit-tests-frontend`	Jest/Vitest conventions — may inform test structure even though this isn’t React.	Tasks 19-23 (test files)

Agent Profiles for Subagent Delegation

If this task is executed by a team lead or coordinator, these agent profiles are recommended. However, the team split assessment recommends single agent execution — the project is small enough that team orchestration overhead is not justified.

Agent Profile	Recommended For	Tasks
`devops-engineer`	Cloudflare Workers deployment, `wrangler.toml`, GitHub Actions CI/CD, branch protection.	1-8, 25-26, 29-30
`back-end-engineer`	TypeScript source code, MCP tool implementation, GitHub API client, tests.	9-14, 16-24, 27
`technical-writer`	`README.md` authoring — installation guide, PAT walkthrough, usage instructions.	27
`quality-reviewer`	Code review before merging — check for security issues (path traversal), coding standards, test coverage gaps.	Post-task 28 (review before merge)
`security-engineer`	Review path traversal validation, token handling, and error responses for information leakage.	Post-task 24 (security review)

Suggested Execution Strategy

Single Agent (Recommended)

Use the back-end-engineer profile. This agent has TypeScript/Node.js expertise and can handle both the source code and infrastructure files. The project is 27 files with clear templates — a single agent can execute all 30 tasks sequentially in one session.

Load skills: general-conventions, release-lifecycle, document-writing
Read: specification.md, design.md, requirements.md, implementation-changes.md, plan/task-plan.md
Read: hypothesis-mcp/package.json, hypothesis-mcp/src/index.ts, hypothesis-mcp/.github/workflows/publish.yml
Execute: Tasks 1-30 following phase gates

Team Execution (If Preferred)

If speed is prioritized over simplicity, a 2-agent team:

Phase 1 (parallel):
- devops-engineer writes scaffolding (Tasks 1-7)
- Agent waits at Gate #8
Phase 2-3 (sequential, single agent):
- back-end-engineer writes source code (Tasks 9-14) and build scripts (Tasks 16-17)
- Passes Gates #15 and #18
Phase 4 (single agent):
- back-end-engineer writes all tests (Tasks 19-23)
- Passes Gate #24
Phase 5-6 (parallel then sequential):
- devops-engineer writes CI workflows (Tasks 25-26)
- back-end-engineer writes README (Task 27)
- Gate #28: CI green
- devops-engineer handles deploy (Task 29) and branch protection (Task 30)

No worktrees needed — single repository, sequential writes within each phase.