io.github.vanshulgoyal101/ctx

ctx.vanshul.com

A public Model Context Protocol (MCP) server, running as a Cloudflare Worker, that turns a GitHub repository or a documentation site into agent-ready context. Point an AI agent at it and it can pack a whole repo (or crawl a docs site) into one token-counted blob — or search it and get back only the relevant passages, each with its file/URL and line.

It's the agent-first companion to mcp/: where mcp reads a single web page, ctx reads whole repos and doc sites. The repo pipeline fetches, gunzips and parses the tarball in-process; docs extraction reuses Mozilla Readability + Turndown.

Endpoint

POST https://ctx.vanshul.com/mcp     # JSON-RPC 2.0 (MCP)
GET  https://ctx.vanshul.com/health  # { ok: true, tools: [...] }

Tools

repo is owner/repo, owner/repo/ref, or a github.com URL. url (for the docs tools) is an absolute http(s) docs page to start crawling from.

Connect from an MCP client

{ "mcpServers": { "ctx": { "url": "https://ctx.vanshul.com/mcp" } } }

Stdio-only clients bridge with npx mcp-remote https://ctx.vanshul.com/mcp.

Add it to your client

• Cursor — Settings → MCP → Add new server, or drop this into ~/.cursor/mcp.json:

  { "mcpServers": { "ctx": { "url": "https://ctx.vanshul.com/mcp" } } }

• Claude Desktop — add the same block to claude_desktop_config.json (Settings → Developer → Edit Config). If your version is stdio-only, use:

  { "mcpServers": { "ctx": { "command": "npx", "args": ["mcp-remote", "https://ctx.vanshul.com/mcp"] } } }

• Continue / VS Code — add ctx with URL https://ctx.vanshul.com/mcp to your MCP servers config.

Try it with curl

# Pack a repo, capped to 8000 tokens
curl -s https://ctx.vanshul.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"pack_repo","arguments":{"repo":"sindresorhus/slugify","max_tokens":8000}}}'

# Search a repo for just the relevant passages
curl -s https://ctx.vanshul.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_context","arguments":{"repo":"sindresorhus/slugify","query":"replace separator"}}}'

Layout

ctx/
├── src/
│   ├── worker.ts     # entry: routes /mcp, /health, rate limit, CORS
│   ├── mcp.ts        # JSON-RPC dispatch + the six tool definitions
│   ├── github.ts     # fetch tarball, gunzip, parse tar, filter files (no deps)
│   ├── pack.ts       # assemble the context blob + token estimate
│   ├── search.ts     # ranked passage search over files (file + line)
│   ├── docs.ts       # crawl a docs site into pages (BFS, same-section)
│   ├── extract.ts    # HTML -> Markdown / links (Readability + Turndown)
│   ├── fetcher.ts    # bounded fetch with re-validated redirects (SSRF)
│   └── security.ts   # SSRF guard (block private/internal addresses)
├── public/
│   ├── index.html    # landing page (served for non-API paths)
│   ├── og.png / og.svg
│   ├── robots.txt
│   └── sitemap.xml
├── tests/            # vitest: github (tar parsing), pack, search, mcp, worker
├── docs/             # architecture, tools/API reference, deployment
├── wrangler.toml
├── package.json
└── tsconfig.json

Develop & deploy

cd ctx
npm install
npm run typecheck
npm test           # vitest — full suite
npm run dev        # local worker at http://localhost:8787  (POST /mcp)
npm run deploy     # wrangler deploy

How it works

owner/repo → github.com tarball → DecompressionStream('gzip')
           → in-process tar parse → drop binaries/lockfiles/build dirs
           → pack (concat + token estimate) OR search (ranked passages)

The GitHub URL is always constructed from a fixed owner/repo slug, so the repo tools have no SSRF surface. The docs tools fetch caller-supplied URLs, so every URL and redirect hop is re-validated against the SSRF guard. Downloads are bounded (timeout, size caps, page/file-count caps) and results are cached per-isolate for a few minutes.

Security & limits

• No SSRF: input is a repo slug, not an arbitrary URL; only github.com is fetched.
• Bounded: 20s download timeout, ~60 MB uncompressed cap, 512 KB/file, ≤3000 files, per-IP rate limit.
• Stateless & private: no code stored, no LLM in the loop; public repos by default (private with a token).

Authentication (optional)

Set a GITHUB_TOKEN Worker secret to lift GitHub's rate limit (60 → 5,000/hour) and read private repos:

wrangler secret put GITHUB_TOKEN

The token is a Worker secret only — never a tool argument — so it can't leak to an agent.

Documentation

• docs/architecture.md — modules, pipeline, tar parsing, limits
• docs/tools.md — full tool & JSON-RPC API reference
• docs/deployment.md — Cloudflare Worker + custom-domain deploy

License

MIT © Vanshul Goyal