vanshulgoyal101

mcp.vanshul.com

Cloudflare Worker として稼働する公開 Model Context Protocol (MCP) サーバーです。あらゆる AI エージェントが、最新のウェブを読みやすい Markdown として取得できます。姉妹プロジェクトの reader/ と同じ抽出パイプライン（Mozilla Readability + Turndown）を基盤とし、MCP の Streamable HTTP トランスポート経由で提供するため、エージェント機能を備えたクライアントから直接利用できます。

エンドポイント

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

ツール

ツール	入力	戻り値
fetch_markdown	{ url, max_chars? }	ページの主要コンテンツを読みやすい Markdown として返します（必要に応じて max_chars 文字に切り詰めます）
search_page	{ url, query, max_matches?, context_chars? }	query に一致する箇所のみを、見出しの階層情報と関連度順で返します。fetch_markdown に代わる、トークン効率の高い方法です
fetch_metadata	{ url }	JSON：タイトル、著者名、サイト名、抜粋、単語数
extract_links	{ url, limit? }	JSON：すべての外部 http(s) リンクとアンカーテキスト

MCP クライアントから接続する

リモート／HTTP 対応クライアント（Claude Desktop、Cursor、Continue など）：

{
  "mcpServers": {
    "web-reader": { "url": "https://mcp.vanshul.com/mcp" }
  }
}

Stdio のみ対応するクライアントは、mcp-remote でブリッジできます：

npx mcp-remote https://mcp.vanshul.com/mcp

クライアントに追加する

• Cursor — Settings → MCP → Add new server を選択するか、次の内容を ~/.cursor/mcp.json に追加します：

  { "mcpServers": { "web-reader": { "url": "https://mcp.vanshul.com/mcp" } } }
  

• Claude Desktop — claude_desktop_config.json に同じブロックを追加します（Settings → Developer → Edit Config）。お使いのバージョンが Stdio のみ対応している場合は、次を使用します：

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

• Continue / VS Code — MCP サーバー設定に URL https://mcp.vanshul.com/mcp の web-reader を追加します。

curl で試す

curl -s https://mcp.vanshul.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://mcp.vanshul.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"fetch_markdown","arguments":{"url":"https://example.com"}}}'

# Return only the passages matching a query (token-efficient):
curl -s https://mcp.vanshul.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search_page","arguments":{"url":"https://example.com","query":"more information"}}}'

ディレクトリ構成

mcp/
├── src/
│   ├── worker.ts     # entry: routes /mcp, /health, rate limit, CORS
│   ├── mcp.ts        # JSON-RPC dispatch + tool definitions
│   ├── extract.ts    # HTML -> Markdown / links (Readability + Turndown)
│   ├── search.ts     # query-focused passage search over extracted Markdown
│   ├── fetcher.ts    # fetch with timeout, size cap, re-validated redirects
│   └── security.ts   # SSRF guard (block private/internal addresses)
├── public/
│   ├── index.html    # landing page (served for non-API paths)
│   ├── og.png        # social share image (1200×630)
│   ├── og.svg        # social image source
│   ├── robots.txt
│   └── sitemap.xml
├── tests/            # vitest: security, extract, search, mcp dispatch, fetcher, worker
├── wrangler.toml
├── package.json
├── tsconfig.json
└── README.md

開発とデプロイ

cd mcp
npm install
npm run typecheck
npm test          # vitest — security, extraction, search, MCP dispatch, fetcher, worker
npm run dev        # local worker at http://localhost:8787  (POST /mcp)
npm run deploy     # wrangler deploy

初回デプロイ後、Cloudflare ダッシュボード（Workers & Pages → この worker → Settings → Domains）でカスタムドメイン mcp.vanshul.com を関連付けるか、wrangler.toml の [[routes]] ブロックのコメントを解除します。

セキュリティ

• SSRF 対策済み： 公開されている http(s) URL のみを許可します。localhost、プライベート範囲、クラウドメタデータへのアクセスはブロックし、リダイレクトの各段階で再検証します。
• 制限付き： フェッチのタイムアウトは 10 秒、ページサイズの上限は約 3 MB、リダイレクトは最大 5 回で、IP ごとにレート制限を設けています。
• ステートレスかつプライベート： ページコンテンツは保存されません。LLM を介さず、決定論的に抽出します。

MCP プロトコル

initialize、ping、tools/list、tools/call と通知を実装しています（プロトコルバージョン 2025-06-18）。ツールの失敗は { content, isError: true } として返されるため、エージェントはメッセージを読み取って処理を続行できます。不正なリクエストには標準の JSON-RPC エラーコードを使用します。

ドキュメント

• docs/architecture.md — モジュール、リクエストのライフサイクル、抽出パイプライン、制限
• docs/tools.md — ツールと JSON-RPC API の詳細なリファレンスおよび使用例
• docs/security.md — SSRF の脅威モデルと緩和策
• docs/deployment.md — Cloudflare Worker とカスタムドメインのデプロイガイド

ライセンス

MIT © Vanshul Goyal