Requirements

Authentication

REQ-AUTH-001: URL-safe Base64 Token Decoding

The Worker must extract the Bearer token from the Authorization header, decode it from URL-safe Base64 (RFC 4648 §5), and use the decoded value as a GitHub Personal Access Token for all GitHub Contents API calls.

REQ-AUTH-002: Missing Token Rejection

If the Authorization header is absent or does not contain a Bearer token, the Worker must return HTTP 401 before dispatching any MCP tool call.

REQ-AUTH-003: Invalid Base64 Rejection

If the Bearer token value cannot be decoded as valid URL-safe Base64, the Worker must return HTTP 401.

REQ-AUTH-003a: PAT Format Validation

After successful Base64 decoding, the Worker must verify that the decoded value matches a recognized GitHub PAT prefix (ghp_, github_pat_, or gho_). If it does not, the Worker must return HTTP 401. This catches misconfigured tokens early, before making a GitHub API call.

REQ-AUTH-004: GitHub Error Propagation

GitHub response codes 401, 403, and 404 must propagate to the caller as MCP error responses with the corresponding error codes (UNAUTHORIZED, FORBIDDEN, NOT_FOUND).

---

Configuration

REQ-CFG-001: Compile-time Configuration

All repository, path, and branch configuration must be set via Cloudflare Worker environment variables at deploy time. There are no per-client overrides or initializationOptions.

REQ-CFG-002: Separate Repo Configuration

Skills/agents and documentation must be configurable to target different repositories, branches, and paths independently.

---

Skills Tools

REQ-SKILL-001: list_skills Returns Bundled Index

list_skills must return a JSON array of skill entries from a bundled index. Each entry includes: name, description, argumentHint, userInvocable, and files (companion file manifest). No GitHub API calls are made at runtime.

REQ-SKILL-002: get_skill Fetches SKILL.md

get_skill must fetch {skillsPath}/{name}/SKILL.md from the configured repository and branch via the GitHub Contents API. The response must include name, content (decoded plain text), path, and sha.

REQ-SKILL-003: get_skill Caching

get_skill responses must be cached for 10 minutes. When skipCache is true, the cache must be bypassed and refreshed with the new response.

REQ-SKILL-004: get_skill_file Fetches Arbitrary Files

get_skill_file must fetch {skillsPath}/{skill}/{file} from the configured repository. Content must be returned as-is from GitHub (Base64-encoded) with encoding: "base64" and size in the response.

REQ-SKILL-005: get_skill_file Caching

Same caching behavior as get_skill (10-minute TTL, skipCache bypass).

---

Agent Tools

REQ-AGENT-001: list_agents Returns Bundled Index

list_agents must return a JSON array of agent entries from a bundled index. Each entry includes: name, description, model, and allowedTools. No GitHub API calls are made at runtime.

REQ-AGENT-002: get_agent Fetches Agent Profile

get_agent must fetch {agentsPath}/{name}.md from the configured repository and branch. The response must include name, content (decoded plain text), path, and sha.

REQ-AGENT-003: get_agent Caching

Same caching behavior as get_skill (10-minute TTL, skipCache bypass).

---

Documentation Tools

REQ-DOC-001: list_docs Returns Bundled Index

list_docs must return a hierarchical JSON structure from a bundled index. Leaf values are page descriptions; intermediate keys are section names. No GitHub API calls are made at runtime.

REQ-DOC-002: get_doc Path Resolution with Fallback

get_doc must resolve the path array using the index.md convention:

1. First try {docsContentPath}/{path.join('/')}/index.md
2. If GitHub returns 404, fall back to {docsContentPath}/{path.join('/')}.md
3. If both return 404, return a NOT_FOUND error.

REQ-DOC-003: get_doc Returns Plain Text

get_doc must decode the Base64 content from GitHub and return it as plain text markdown. The response must include path, content, filePath, and sha.

REQ-DOC-004: get_doc Caching

Same caching behavior as get_skill (10-minute TTL, skipCache bypass).

---

Security

REQ-SEC-001: Path Traversal Validation

All get_* tools that accept path parameters (name, skill, file, path[] segments) must reject values containing .., values starting with /, and values containing \. Rejected inputs must return an INVALID_PATH error.

REQ-SEC-002: No Stored Secrets

The Worker must not store any secrets (tokens, keys) in environment variables, KV, or Durable Object state. The GitHub PAT is transient — present only in the request header for the duration of the tool call.

---

Error Handling

REQ-ERR-001: Structured Error Responses

All errors must follow the error response shape: { error: { code, message, details } }. Details must include repo, path, branch, and githubStatus where applicable.

REQ-ERR-002: Error Code Mapping

GitHub Status	MCP Error Code
401	UNAUTHORIZED
403	FORBIDDEN
404	NOT_FOUND
Other non-2xx	UPSTREAM_ERROR
N/A (validation)	INVALID_PATH

---

Build Process

REQ-BUILD-001: Index Generation from Source Repos

The CI pipeline must clone both source repositories and generate three index files (skills-index.json, agents-index.json, docs-index.json) from frontmatter using js-yaml.

REQ-BUILD-002: Graceful Frontmatter Fallback

If a skill or agent file has no YAML frontmatter, the index entry must use the filename as name and null as description. The build must not fail.

REQ-BUILD-003: Companion File Manifest

The skills index must include a files array listing all files in the skill directory excluding SKILL.md, using relative paths.

REQ-BUILD-004: Docs Index Includes .md and .mdx

The docs index generation must process both .md and .mdx files.

REQ-BUILD-005: Three CI Triggers

The build-and-deploy pipeline must run on: (1) push to main, (2) weekly cron (Saturday 00:00 Pacific / 07:00 UTC), (3) workflow_dispatch.

REQ-BUILD-006: Bundled Static Imports

Generated index files must be importable as static JSON modules in the Worker source and embedded in the Worker bundle at deploy time.

---

Infrastructure

REQ-INFRA-001: Cloudflare Workers Deployment

The server must deploy as a Cloudflare Worker using wrangler deploy. The wrangler.toml must configure compatibility_date = "2025-06-01" and nodejs_compat.

REQ-INFRA-002: MCP Protocol via McpAgent

The Worker must use Cloudflare’s McpAgent from the agents npm package for MCP HTTP+SSE protocol handling.

REQ-INFRA-003: Branch Protection Rules

After the first version reaches main, the repository must have branch protection rules equivalent to the Arda-cards/hypothesis-mcp example repository.