vanshulgoyal101

mcp.vanshul.com

一个公开的 Model Context Protocol (MCP) 服务，运行于 Cloudflare Worker，可让任何 AI Agent 以简洁的 Markdown 格式读取实时网页。它采用与同系列项目 reader/ 相同的内容提取流程（Mozilla Readability + Turndown），并通过 MCP Streamable HTTP 传输协议提供服务，方便 Agent 客户端直接接入。

端点

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 服务配置中添加 web-reader，并将 URL 设为 https://mcp.vanshul.com/mcp。

使用 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 控制面板中绑定自定义域名 mcp.vanshul.com（Workers & Pages → 此 Worker → Settings → Domains），或者取消 wrangler.toml 中 [[routes]] 代码块的注释。

安全性

• **防 SSRF：**仅允许公开的 http(s) URL；会拦截并重新验证 localhost、私有地址范围、云元数据以及每次重定向。
• **限制明确：**抓取超时为 10 秒，网页大小上限约为 3 MB，最多重定向 5 次，并按 IP 限流。
• **无状态且保护隐私：**不存储网页内容；内容提取过程是确定性的，不涉及大模型。

MCP 协议

实现了 initialize、ping、tools/list、tools/call 和通知（协议版本 2025-06-18）。工具失败时会返回 { content, isError: true }，以便 Agent 读取消息并恢复；格式错误的请求会使用标准 JSON-RPC 错误代码。

文档

• docs/architecture.md — 模块、请求生命周期、内容提取流程、限制
• docs/tools.md — 完整的工具与 JSON-RPC API 参考，附示例
• docs/security.md — SSRF 威胁模型与缓解措施
• docs/deployment.md — Cloudflare Worker 与自定义域名部署指南

许可证

MIT © Vanshul Goyal