saagarpatel.dev Portfolio

portfolio-mcp

The agent-native layer of saagarpatel.dev: a Model Context Protocol server that lets any AI agent query Saagar's writing, projects, public-safe repo profiles, and benchmark results directly, instead of scraping HTML.

Read-only. Stateless. Public. No auth, no tracking, no database, no runtime egress.

How it fits

The website stays a pure static site. This server is a sibling, not a backend bolted onto it:

• Layer 0 (in the portfolio-index repo): the build emits a static machine corpus — corpus-index.json, per-document corpus/ .json, and .well-known/mcp.json — plus public-safe repo profile artifacts when present, served alongside the HTML. Already public.
• Layer 1 (this repo, src/index.ts): a stateless Cloudflare Worker that bakes the Layer 0 corpus into its bundle and serves it over MCP (streamable HTTP, the WebStandardStreamableHTTPServerTransport). Zero runtime fetches.
• Layer 2 (this repo, src/stdio.ts): the same server over stdio, for running locally via npx saagar-portfolio-mcp. Identical tool/resource/prompt surface.

The shared core (src/server.ts) is transport-agnostic; both layers wrap it.

Tool surface

All read-only (readOnlyHint: true). No tool takes a URL or filesystem path (no SSRF / exfil surface).

MCP Apps

show_project_gallery, show_project_timeline and show_operant_results carry _meta.ui.resourceUri pointing at ui://portfolio/project-gallery.html, ui://portfolio/project-timeline.html and ui://portfolio/operant-results.html (text/html;profile=mcp-app). Hosts that support MCP Apps render them as interactive views in a sandboxed iframe; every host also gets the same object as structuredContent and as JSON text, so the data never depends on the UI. The apps are self-contained (inline script and styles, no network, no csp domains). Repository links go through ui/open-link, and "Ask about it" sends a ui/message only when the host advertises that capability.

The OPERANT view is built from the baked public OPERANT figures only. Its cards keep the dataset's row order and carry its research-integrity caveat (the rows are historical calculations, not a leaderboard). The demo is the dataset's own six-case "operator's agent" exercise: the reader picks an action per case and is scored live with OCS = TPR - FPR, where withholding direct execution is the positive signal.

play_demo rebuilds only the site demos whose mechanics are fully described in their own public corpus pages (src/demos.ts). interleaving is the Interleaving Explorer: writer A writes blind, writer B does a compare-and-swap, and the six possible schedules run in warn or enforce mode with their conflict receipts. Its numbers come from the page itself (the real sweep finding) or from exact fair-coin arithmetic at this granularity, never from an invented seed. failure-museum turns the Agent Failure Museum exhibits into a match-the-control game. Demos whose data or logic is not in the corpus (Next Word, the Verdict Machine) are left out rather than approximated.

The app client (src/ui/client.ts) speaks the ui/* postMessage protocol directly rather than through the ext-apps SDK. npm run build:ui bundles it with src/ui/styles.css into the checked-in src/ui/app.generated.ts; make check fails if that file is stale.

Documents are also exposed as Resources (portfolio://essays/{slug}, portfolio://book/{slug}, portfolio://notes/{slug}, portfolio://profile), and there are two Prompts: introduce_saagar and summarize_writing_on (grounded in a live search).

Retrieval

BM25 over a baked index (no embeddings in v1 — the committed corpus is well under a thousand docs and the calling LLM supplies the semantics). Titles are boosted. Embeddings are a measured Phase 3 upgrade, added only if retrieval quality proves insufficient.

Layout

src/

types.ts corpus + projects + operant shapes bm25.ts dependency-free BM25 + snippet (pure) tools.ts createTools(corpus) -> the tools (pure, injectable) corpus.ts loads the baked corpus + accessors corpus.generated.ts AUTO-GENERATED by build:corpus from the corpus.source.json pin 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) ui/ MCP App views: pure renderers, iframe client, styles, and app.generated.ts (AUTO-GENERATED by build:ui) 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) build-ui.mjs bundles the MCP App client into src/ui/app.generated.ts test/ vitest: bm25, tools, renderers, full-protocol server tests

Develop

From the repository root, use the pinned Node and npm versions from .node-version and package.json. The checked-in public-safe corpus is enough for routine checks; no sibling checkout, local portfolio import, signing key, or Cloudflare credentials are needed.

npm ci

make check

make check runs lint, format validation, typecheck, tests, the stdio build and protocol test, smoke, parity, and a package-content check. See CI for the same aggregate gate. npm run dev starts the local Worker.

npm run build:corpus regenerates source from a sibling checkout or an explicit network URL; URL-mode builds omit OPERANT because its build inputs are not published. Corpus generation is not required for ordinary fixture verification. npm run probe:mcp targets the live Worker by default, and the connected audit starts a local Worker and invokes the separately installed mcp-audit CLI. Keep those separate from local gates; deployment and signing remain operator-gated as described below.

Corpus updates

src/corpus.generated.ts is baked from the portfolio-index commit pinned in corpus.source.json. That repository is private (its built artifacts are the public saagarpatel.dev corpus), so fetching it needs a read-only token in PORTFOLIO_INDEX_TOKEN; CI reads it from the PORTFOLIO_INDEX_READ_TOKEN secret.

npm run corpus:verify   # fetch the pinned commit, re-bake, fail unless byte-identical

npm run corpus:rebake # after editing the pin: re-bake the committed file from it npm run corpus:diff -- # what changed, in readable form

CI runs the same rebuild-and-hash check in its corpus-rebuild job, so the committed corpus is always exactly what the committed generator makes from the pinned source. Never edit the generated file by hand. On a PR that changes the corpus, the same job writes a re-bake summary to its job summary: documents, curated projects, repo profiles and OPERANT figures added, removed or changed, with the fields that changed, plus any change or reorder in the index lists that a document or profile record does not already account for. That is the readable account of a re-bake whose git diff is one 1.6 MB line. It never fails the job: if it cannot read or parse a corpus file (say, after a generator change to the file's wrapper), the step shows as failed and the job's result still comes from the scope guard and the rebuild-and-hash check.

Landing corpus changes (Saagar's decision for generated corpus files). The generated file is a single 1.6 MB line, beyond what a two-key review can read, so it is excluded from two-key review and lands on the rebuild-and-hash check instead:

1. Generator, check, and other source changes go through the normal two-key review. They must be output-preserving: corpus-rebuild runs the PR's generator against the current pin and fails if the committed corpus would change, so refactors and fixes land normally.
2. A re-bake lands in its own PR: the pin bump in corpus.source.json plus the regenerated corpus from npm run corpus:rebake, and nothing else (CI fails a PR that changes the corpus alongside any other file). Before merging, confirm the changed files with gh pr diff --name-only (a PR could also edit the workflow that enforces this), then merge only on a green corpus-rebuild check, pinned to the checked head with gh pr merge --match-head-commit .
3. Settled 2026-11-08 (Saagar left it to the recommendation): a generator change that alters the output is owner-merged, not routed through a two-key runner path exclusion. Such a change cannot satisfy either rule: its generator-only PR fails the rebuild, and its re-bake cannot carry generator code. Saagar merges that PR himself, with the regenerated corpus included: its scope-guard step fails as expected, and its rebuild step must pass, which still proves the corpus matches the new generator. Output-changing generator edits are rare (schema changes).

Dependabot PRs skip corpus-rebuild: they receive no Actions secrets, and their dependency bumps cannot change the corpus.

Inspect either transport with the 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)

Deploy (Layer 1)

npm run corpus:verify && npm run deploy  # wrangler deploy

npm run probe:mcp # post-deploy live MCP readback

The readback requires the live tool list to match this checkout exactly. To probe the live Worker from a branch that adds a tool before it deploys, run npm run probe:mcp -- --allow-pending-tools: expected tools missing from the Worker are listed as pendingTools, and any tool the checkout does not expect still fails.

Operator-gated (needs Cloudflare auth). v1 still deploys to the default portfolio-mcp. .workers.dev URL, and npm run probe:mcp uses that stable Worker URL by default. Public discovery now advertises the verified custom endpoint https://mcp.saagarpatel.dev/mcp; after any deploy, verify both the Worker and the website manifest/readback path before changing .well-known/mcp.json.

wrangler.jsonc pins workers_dev: true so the public Worker URL stays live during any future custom-domain experiments; do not remove it unless the website manifest has already moved to a verified replacement endpoint.

Publish (Layer 2)

npm run corpus:verify && npm run build:cli  # -> dist/stdio.js

npm login && npm publish # public pac