portfolio-mcp
by saagpatel
README.md
# portfolio-mcp
[](https://glama.ai/mcp/servers/saagpatel/portfolio-mcp)
The agent-native layer of [saagarpatel.dev](https://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/<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, 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).
| Tool | Purpose |
|---|---|
| `search` | BM25 over the whole corpus; optional `section` filter, `limit` |
| `get_document` | Full Markdown of one document by `id` |
| `list_corpus` | The table of contents; optional `type` filter |
| `get_profile` | The "who is this" card (about / now / uses) |
| `list_projects` | Curated public-safe projects + anonymized aggregates |
| `list_repo_profiles` | Public-safe repo profile index with freshness and proof counts |
| `get_repo_profile` | One repo answering profile by the `repoId` argument |
| `get_operant_results` | Public, sanitized OPERANT calibration results (per-model OCS) |
| `show_project_gallery` | Curated projects as gallery cards (MCP App); optional `status`, `lifecycle` |
| `show_project_timeline` | Curated projects by last-active month, with archive lifecycle mix (MCP App) |
| `show_operant_results` | OPERANT calibration-profile cards plus a playable demo scored with OCS (MCP App); optional `section` |
| `play_demo` | The site's playable demos rebuilt from their corpus pages (MCP App): `interleaving` or `failure-museum` |
## 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.
```sh
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](.github/workflows/ci.yml) 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`](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.
```sh
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 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 <n> --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 <sha>`.
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:
```sh
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)
```sh
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.<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)
```sh
npm run corpus:verify && npm run build:cli # -> dist/stdio.js
npm login && npm publish # public package: saagar-portfolio-mcp
```
Once 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):
```sh
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
```
Override 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.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues