saagarpatel.dev Portfolio

portfolio-mcp

saagarpatel.dev 面向 Agent 的层：一个模型上下文协议服务，让任意 AI Agent 都能直接查询 Saagar 的文章、项目、公开安全的仓库档案和基准测试结果，而无需抓取 HTML。

只读、无状态、公开。无需身份验证，不进行跟踪，不使用数据库，不产生运行时出站流量。

架构定位

网站保持为纯静态站点。此服务是它的姊妹服务，而非附加在其上的后端：

• 第 0 层（位于 portfolio-index 仓库中）：构建过程会生成静态机器语料库，包括 corpus-index.json、每篇文档对应的 corpus/<id>.json 和 .well-known/mcp.json；此外还会在有内容时生成公开安全的仓库档案文件，并与 HTML 一同提供。这些内容已经公开。
• 第 1 层（此仓库，src/index.ts）：无状态 Cloudflare Worker，将第 0 层语料库打包进程序包，并通过 MCP（可流式传输的 HTTP、WebStandardStreamableHTTPServerTransport）提供服务。运行时零次抓取。
• 第 2 层（此仓库，src/stdio.ts）：同一服务通过标准输入输出提供，可使用 npx saagar-portfolio-mcp 在本地运行。工具、资源和提示词接口完全相同。

共享核心（src/server.ts）与传输方式无关；两个层都对其进行封装。

工具接口

全部为只读（readOnlyHint: true）。任何工具都不接受 URL 或文件系统路径（不存在 SSRF／数据外泄攻击面）。

工具	用途
search	对整个语料库执行 BM25 搜索；可选 section 筛选器和 limit
get_document	根据 id 获取一篇文档的完整 Markdown
list_corpus	目录；可选 type 筛选器
get_profile	“这是关于谁”的简介卡片（about / now / uses）
list_projects	精选的公开安全项目和匿名汇总数据
list_repo_profiles	公开安全的仓库档案索引，包含时效信息和证明数量
get_repo_profile	根据 repoId 参数获取一个仓库的答疑档案
get_operant_results	公开、经过脱敏的 OPERANT 校准结果（各模型的 OCS）

文档也以资源形式提供（portfolio://essays/{slug}、portfolio://book/{slug}、portfolio://notes/{slug}、portfolio://profile），另有两个提示词：introduce_saagar 和 summarize_writing_on（基于实时 search 结果）。

检索

使用打包索引执行 BM25（v1 不使用嵌入——已提交的语料库包含 166 篇文档，语义由调用方的大模型提供）。标题会获得更高权重。嵌入属于经过测量的第 3 阶段升级，仅在检索质量证明不足时添加。

目录结构

src/
  types.ts            corpus + projects + operant shapes
  bm25.ts             dependency-free BM25 + snippet (pure)
  tools.ts            createTools(corpus) -> the 8 tools (pure, injectable)
  corpus.ts           loads the baked corpus + accessors
  corpus.generated.ts AUTO-GENERATED by build:corpus
  server.ts           buildServer(): shared MCP core (tools + resources + prompts)
  index.ts            Cloudflare Worker transport (streamable HTTP)
  stdio.ts            Layer 2 stdio transport (the npx CLI)
scripts/
	build-corpus.mjs    bakes Layer 0 and local OPERANT inputs into corpus.generated.ts
  probe-mcp.mjs        probes an MCP HTTP endpoint (saagar-mcp-kit driver + domain calls)
  audit-mcp.sh        connected MCPAudit scan of this server (dogfood)
test/                 vitest: bm25, tools, full-protocol server tests

开发

在仓库根目录使用 .node-version 和 package.json 中指定的 Node 和 npm 版本。已签入的公开安全语料库足以满足常规检查；无需检出姊妹仓库、导入本地作品集、签名密钥或 Cloudflare 凭据。

npm ci
make check

make check 会运行 lint、格式验证、类型检查、测试、stdio 构建和协议测试、冒烟测试、一致性检查以及程序包内容检查。相同的聚合检查门槛见 CI。npm run dev 会启动本地 Worker。

npm run build:corpus 会从姊妹仓库或指定的网络 URL 重新生成源内容；URL 模式构建会省略 OPERANT，因为其构建输入未公开发布。生成语料库并非普通样例验证所必需。默认情况下，npm run probe:mcp 会连接线上 Worker；已连接审计会启动本地 Worker，并调用单独安装的 mcp-audit CLI。请将这些操作与本地检查门槛分开；部署和签名仍由操作人员按下文所述进行控制。

使用 MCP Inspector 检查任一传输方式：

npx @modelcontextprotocol/inspector http://localhost:8787/mcp   # Layer 1 (HTTP)
npx @modelcontextprotocol/inspector node dist/stdio.js          # Layer 2 (stdio, after build:cli)

部署（第 1 层）

npm run build:corpus && npm run deploy   # wrangler deploy
npm run probe:mcp                        # post-deploy live MCP readback

需要运营者授权（需要 Cloudflare 身份验证）。v1 仍会部署到默认 portfolio-mcp.<account>.workers.dev URL，且 npm run probe:mcp 默认使用该稳定的 Worker URL。公开发现信息现在公布已验证的自定义端点 https://mcp.saagarpatel.dev/mcp；每次部署后，在更改 .well-known/mcp.json 之前，先验证 Worker 以及 网站清单／回读路径。

wrangler.jsonc 将 workers_dev: true 固定为配置，以便在未来尝试自定义域名期间，公开 Worker URL 始终可用；除非网站清单已改为经过验证的替代端点，否则不要移除该配置。

发布（第 2 层）

npm run build:corpus && npm run build:cli   # -> dist/stdio.js
npm login && npm publish                     # public package: saagar-portfolio-mcp

发布后，任何人都可以运行 npx saagar-portfolio-mcp 在本地使用（无需安装）。

为清单签名（可选的信任信号）

使用 Ed25519 为 .well-known/mcp.json 签名，以便 Agent 或注册表验证其确实来自 Saagar（通过 saagar-mcp-kit 的签名 CLI 和 Node 内置的加密功能）：

npx mcp-kit-sign gen-key --manifest=../portfolio-index/.well-known/mcp.json  # one-time; private key -> .signing/ (gitignored, NEVER commit)
npm run sign                             # writes <manifest>.sig + publishes mcp-ed25519.pub
npm run sign:verify                      # checks manifest bytes against .sig + public key

使用 --manifest=/--key=/--pub=/--sig= 覆盖路径。 将 .sig 和 mcp-ed25519.pub（绝不包括私钥）与清单一起提交到 portfolio-index，然后 重新部署网站。清单每次变更后都要重新运行 sign（签名针对实际提供的确切字节）。

审计状况

设计目标是通过 MCPAudit / mcp-trust（Saagar 自有工具）的审计：仅使用入站 MCP 传输，不包含 shell_execution / file_access / destructive / exfiltration，也不允许由调用方控制出口请求（语料库已内置）。所有工具均标注为只读，并使用简洁、不可注入的描述。运行 bash scripts/audit-mcp.sh 可执行联网扫描。

在实际使用此服务的过程中，发现了 MCPAudit 中一个子字符串匹配误报问题（它在 portfolio:// 中匹配了 port）；修复已提交到 MCPAudit 仓库，使此服务的发现项从 62 项降至 14 项。真正的工具面扫描结果干净（high_risk_servers: 0）。

状态

技术栈

Node.js 24.21.0、npm 12.2.0、TypeScript、Cloudflare Workers 和 MCP SDK。

已知风险

URL 模式的语料库构建会省略 OPERANT，其输入仅在本地语料库构建中可用。Worker 部署和软件包发布不属于本地验证范围。

后续步骤

运营者授权部署后，确保已发布的 MCP 端点与签名后的发现清单保持同步。注册表发布仍是单独且需明确授权的发布操作。