ctx

ctx.vanshul.com

一个公开的 Model Context Protocol (MCP) 服务，以 Cloudflare Worker 的形式运行，可将 GitHub 仓库或文档站点转换为适合 Agent 使用的上下文。将 AI Agent 指向它，即可将整个仓库（或抓取整个文档站点）打包成一个经过令牌数估算的文本块；也可以搜索并仅获取相关段落，每段都附带文件/URL 和行号。

它是面向 Agent 的 mcp/ 配套工具：mcp 读取单个网页，而 ctx 读取整个仓库和文档站点。仓库处理流程会在进程内获取、解压 gzip 并解析 tarball；文档提取则会复用 Mozilla Readability + Turndown。

端点

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

工具

工具	输入	返回内容
pack_repo	{ repo, ref?, include?, exclude?, max_tokens? }	将仓库作为一个上下文文本块返回，带有 ==== path ==== 标题和令牌数估算
search_context	{ repo, query, ref?, include?, exclude?, max_matches?, context_chars? }	仅返回与 query 匹配的段落，每段包含文件、行号和评分
list_files	{ repo, ref?, include?, exclude? }	JSON：ctx 将纳入的文本文件及其字节大小
get_file	{ repo, path, ref? }	单个文件的完整文本
pack_docs	{ url, depth?, max_pages?, max_tokens? }	将抓取的文档站点作为一个上下文文本块返回（每个页面 → Markdown）
search_docs	{ url, query, depth?, max_pages?, max_matches?, context_chars? }	仅返回与 query 匹配的文档段落，每段包含页面 URL、行号和评分

repo 可以是 owner/repo、owner/repo/ref 或 github.com URL。文档工具中的 url 是用于开始抓取的绝对 http(s) 文档页面地址。

从 MCP 客户端连接

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

仅支持 Stdio 的客户端可通过 npx mcp-remote https://ctx.vanshul.com/mcp 桥接。

添加到客户端

• Cursor — 依次选择 Settings → MCP → Add new server，或将以下内容添加到 ~/.cursor/mcp.json：

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

• Claude Desktop — 将相同的配置块添加到 claude_desktop_config.json（Settings → Developer → Edit Config）。如果你的版本仅支持 stdio，请使用：

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

• Continue / VS Code — 在 MCP 服务配置中添加 ctx，URL 为 https://ctx.vanshul.com/mcp。

使用 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"}}}'

目录结构

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

开发与部署

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

工作原理

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

GitHub URL 始终由固定的 owner/repo 标识构造，因此仓库工具不存在 SSRF 攻击面。文档工具会获取调用方提供的 URL，因此每个 URL 和重定向跳转都会针对 SSRF 防护规则重新验证。下载均有边界限制（超时、大小上限、页面/文件数量上限），结果会在每个 isolate 中缓存几分钟。

安全与限制

• 无 SSRF： 输入是仓库标识，而非任意 URL；只会获取 github.com。
• 有限制： 下载超时为 20s，解压后大小上限约为 60 MB，单个文件上限为 512 KB，文件数不超过 3000，并设有基于 IP 的速率限制。
• 无状态且私密： 不存储代码，流程中不使用大模型；默认支持公开仓库（私有仓库需提供令牌）。

身份验证（可选）

设置 GITHUB_TOKEN Worker 密钥，即可提高 GitHub 的速率限制（每小时 60 次 → 5,000 次）并读取私有仓库：

wrangler secret put GITHUB_TOKEN

该令牌仅作为 Worker 密钥使用，不会作为工具参数传入，因此不会泄露给 Agent。

文档

• docs/architecture.md — 模块、处理流程、tar 解析、限制
• docs/tools.md — 完整的工具与 JSON-RPC API 参考
• docs/deployment.md — Cloudflare Worker + 自定义域名部署

许可证

MIT © Vanshul Goyal