harshdipsaha-mcp

A public, read-only Model Context Protocol server for harshdipsaha.tech. Add its URL to any MCP client (Claude Code, Codex, Cursor, …) to query Harshdip Saha's projects and profile directly, instead of scraping the site.

Design doc: docs/plans/2026-09-05-mcp-server-design.md in the portfolio repo. Originated from issue #62.

Not to be confused with WebMCP. The portfolio site separately registers a WebMCP tool (document.modelContext, ADR 0014/0020) — a browser API consumed by an agent embedded in a browser tab. This repo is the real Model Context Protocol, consumed by external clients over a network connection. They share a name and nothing else.

Tools

• searchProjects(query, limit?) — keyword search over the project list, same matching semantics as the portfolio's own WebMCP tool: every whitespace-separated term must appear in the title, summary, slug, or year.

• getProfile() — bio, skills, contact info, résumé link, and site URL.

Deliberately just these two, matching ADR 0014's minimal-surface reasoning: every additional tool is a schema that has to stay correct.

Related MCP server: Portfolio MCP Server

Architecture

harshdipsaha.tech/agent-data.json  ->  fetch (10 min edge cache)  ->  this Worker  ->  MCP client

The Worker holds no data of its own — it fetches agent-data.json (generated by the portfolio repo's scripts/build-agent-data.mjs) on every tool call, cached at Cloudflare's edge via the cf.cacheTtl fetch option, so a burst of MCP traffic never hits GitHub Pages more than once per 10-minute window. There is no database, no KV, no Durable Object — the server is stateless, per the MCP spec's 2026-07-28 revision.

• src/lib/search-projects.mjs, src/lib/format.mjs — pure logic, unit-tested with node --test.

• src/lib/agent-data-client.mjs — the one place that does I/O (the fetch).

• src/server.mjs — builds the McpServer and registers both tools.

• src/index.mjs — the Worker entry point, wrapping createServer with Cloudflare's createMcpHandler (agents/mcp/server) for the Streamable HTTP transport.

Run locally

npm install
npm run typecheck   # tsc, split into tsconfig.json (src, Workers types) + tsconfig.test.json (test, Node types)
npm test            # node --test (default discovery) — the pure-function suite
npm run dev          # wrangler dev — needs Node >= 22 (see below)

Node version: wrangler hard-requires Node ≥ 22. This project's own code runs fine on Node 20+ (npm test/npm run typecheck don't need 22), but npm run dev/npm run deploy will refuse to start otherwise. If you're on an older Node, switch first (nvm use 22 or equivalent).

Verified locally (Node 22.23.2, wrangler dev, no deploy): initialize, tools/list, and a real tools/call for both tools against the live agent-data.json all returned correct responses.

Deploy

npx wrangler login   # one-time, opens a browser OAuth flow — do this yourself, not from an agent session
npm run deploy

Publishes to <worker-name>.<your-subdomain>.workers.dev with no custom domain and no authentication configured, matching the design doc's scope (public, read-only, no auth).

Keeping this in sync

src/lib/types.mjs's JSDoc typedefs mirror the portfolio repo's scripts/lib/agent-data.mjs output field-for-field. There's no shared package between the two repos — if that shape changes on the portfolio side, update the typedefs and src/server.mjs's Zod schemas here by hand.

Out of scope (see the design doc)

• Any write/contact tool.

• Auth of any kind.

• The portfolio site's own discoverability addition (a footer link / /mcp section) — a separate, later change to HARSHDIPSAHA.github.io.