portfolio-mcp
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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-indexrepo): the build emits a static machine corpus —corpus-index.json, per-documentcorpus/<id>.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, theWebStandardStreamableHTTPServerTransport). Zero runtime fetches.Layer 2 (this repo,
src/stdio.ts): the same server over stdio, for running locally vianpx saagar-portfolio-mcp. Identical tool/resource/prompt surface.
The shared core (src/server.ts) is transport-agnostic; both layers wrap it.
Related MCP server: CodeAlive MCP
Tool surface
All read-only (readOnlyHint: true). No tool takes a URL or filesystem path (no
SSRF / exfil surface).
Tool | Purpose |
| BM25 over the whole corpus; optional |
| Full Markdown of one document by |
| The table of contents; optional |
| The "who is this" card (about / now / uses) |
| Curated public-safe projects + anonymized aggregates |
| Public-safe repo profile index with freshness and proof counts |
| One repo answering profile by the |
| Public, sanitized OPERANT calibration results (per-model OCS) |
| Curated projects as gallery cards (MCP App); optional |
| Curated projects by last-active month, with archive lifecycle mix (MCP App) |
| OPERANT calibration-profile cards plus a playable demo scored with OCS (MCP App); optional |
| The site's playable demos rebuilt from their corpus pages (MCP App): |
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 testsDevelop
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 checkmake 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 -- <before.ts> <after.ts> # what changed, in readable formCI 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:
Generator, check, and other source changes go through the normal two-key review. They must be output-preserving:
corpus-rebuildruns the PR's generator against the current pin and fails if the committed corpus would change, so refactors and fixes land normally.A re-bake lands in its own PR: the pin bump in
corpus.source.jsonplus the regenerated corpus fromnpm run corpus:rebake, and nothing else (CI fails a PR that changes the corpus alongside any other file). Before merging, confirm the changed files withgh pr diff <n> --name-only(a PR could also edit the workflow that enforces this), then merge only on a greencorpus-rebuildcheck, pinned to the checked head withgh pr merge --match-head-commit <sha>.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 readbackThe 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.<account>.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 package: saagar-portfolio-mcpOnce published, anyone can run it locally with npx saagar-portfolio-mcp (no install).
Sign the manifest (optional trust signal)
Ed25519-sign .well-known/mcp.json so an agent or registry can verify it authentically
comes from Saagar (via saagar-mcp-kit's signing CLI, Node built-in crypto):
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 keyOverride paths with --manifest=/--key=/--pub=/--sig=.
Commit the .sig + mcp-ed25519.pub (never the private key) into portfolio-index next to the manifest, then
redeploy the site. Re-run sign whenever the manifest changes (it signs the exact served bytes).
For verification, configure MCP_TRUSTED_PUBLISHER_PUB to an independently provisioned public-key
file, then run npm run sign:verify. This invokes mcp-kit-sign verify-pinned once and accepts only
its JSON result for the independent-publisher-pin policy. The adjacent bundle key is not a trust root;
missing pins, invalid signatures, or an older CLI that does not report this policy fail closed. Key
selection and provisioning remain an operator responsibility.
Audit posture
Designed to pass MCPAudit / mcp-trust (Saagar's own tools): only the inbound MCP
transport, no shell_execution / file_access / destructive / exfiltration, and no
caller-controlled egress (the corpus is baked). All tools are annotated read-only with
plain, non-injectable descriptions. bash scripts/audit-mcp.sh runs a connected scan.
Dogfooding this server surfaced a substring-matching false-positive bug in MCPAudit (it
matched port inside portfolio://); that fix lives in the MCPAudit repo and cut this
server's findings 62 → 14. The genuine tool surface scans clean (high_risk_servers: 0).
Status
Stack
Node.js 24.21.0, npm 12.2.0, TypeScript, Cloudflare Workers, and the MCP SDK.
Known risks
URL-mode corpus builds omit OPERANT, whose inputs are only available to local corpus builds. Worker deployment and package publication are not part of local verification.
Next steps
Keep the published MCP endpoint and signed discovery manifest in sync when an operator authorizes a deployment. Registry publication remains a separate, explicitly authorized release action.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Web search API and MCP server for developers building AI agents.
Turn any public website into an MCP server for agents to search, read and navigate.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA simple Model Context Protocol server that enables searching and retrieving relevant documentation snippets from Langchain, Llama Index, and OpenAI official documentation.-

CodeAlive MCPofficial
AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.90MIT- FlicenseCqualityDmaintenanceA Model Context Protocol server that provides Retrieval-Augmented Generation capabilities using Contextual AI, enabling AI interfaces like Cursor IDE and Claude Desktop to query domain-specific knowledge with context-aware responses and source citations.121-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to access structured content by building static Markdown/JSON files served as a Model Context Protocol server.1-