ctx

ctx.vanshul.com

Cloudflare Worker として稼働する、公開 Model Context Protocol (MCP) サーバーです。GitHub リポジトリやドキュメントサイトを、エージェントが利用しやすいコンテキストに変換します。AI エージェントからこのサーバーを指定すると、リポジトリ全体（またはドキュメントサイトをクロールした結果）を、トークン数をカウントした 1 つのデータにまとめられます。また、検索して関連する箇所だけを、ファイル名または URL と行番号付きで取得することもできます。

mcp/ のエージェント向けコンパニオンです。mcp が単一のウェブページを読み取るのに対し、ctx はリポジトリ全体やドキュメントサイトを読み取ります。リポジトリの処理パイプラインでは 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) URL を指定します。

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 サーバー設定に、URL https://ctx.vanshul.com/mcp の ctx を追加します。

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 ガードで再検証されます。ダウンロードには上限が設定されています（タイムアウト、サイズ上限、ページ数／ファイル数上限）。結果は数分間、インスタンスごとにキャッシュされます。

セキュリティと制限

• SSRF なし： 入力は任意の URL ではなくリポジトリのスラッグです。取得先は github.com のみです。
• 上限あり： ダウンロードタイムアウトは 20 秒、展開後のサイズ上限は約 60 MB、1 ファイルあたり 512 KB、ファイル数は最大 3000、IP ごとのレート制限があります。
• ステートレスかつプライベート： コードは保存されず、処理に LLM は介在しません。デフォルトでは公開リポジトリが対象です（トークンを使用すればプライベートリポジトリも対象にできます）。

認証（任意）

GITHUB_TOKEN Worker シークレットを設定すると、GitHub のレート制限を緩和し（1 時間あたり 60 回から 5,000 回）、プライベートリポジトリを読み取れるようになります。

wrangler secret put GITHUB_TOKEN

このトークンは Worker シークレットとしてのみ使用され、ツール引数には含まれないため、エージェントに漏れることはありません。

ドキュメント

• docs/architecture.md — モジュール、パイプライン、tar の解析、制限事項
• docs/tools.md — ツールおよび JSON-RPC API の完全なリファレンス
• docs/deployment.md — Cloudflare Worker とカスタムドメインのデプロイ

ライセンス

MIT © Vanshul Goyal