Skip to main content
Glama
portfolio-mcp

portfolio-mcp

by saagpatel

portfolio-mcp

Glama MCP server

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/<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.

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

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.

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 -- <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:

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.<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-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):

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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.
      90
      MIT
    • F
      license
      C
      quality
      D
      maintenance
      A 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.
      1
      21
      -