Public Portfolio MCP

A small, production-minded read-only JSON-RPC service for exposing a deliberately bounded engineering portfolio to recruiters and external agents.

The interesting part is not the profile data. It is the boundary: callers can invoke three purpose-built tools, but they cannot choose a database table, filesystem path, URL, command, or private application module.

What this demonstrates

• Strict TypeScript and zero production dependencies
• MCP-style initialize, tools/list, and tools/call over JSON-RPC 2.0
• Fixed read-only tool allowlist with exact argument keys
• Payload limits, rate limiting, CORS allowlisting, and security headers
• Bounded public text and prompt-injection-shaped input rejection
• Stable errors without stack traces or request payload logging
• Tests, Docker, GitHub Actions, architecture notes, ADR, and threat model

Architecture

Untrusted client
      |
      v
HTTP safeguards
      |
      v
JSON-RPC method allowlist
      |
      v
Strict tool arguments
      |
      v
Immutable public records

See architecture, threat model, and ADR 0001.

Run locally

cp .env.example .env
npm ci
npm test
npm run dev

Health check:

curl http://localhost:3000/health

List tools:

curl http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Search projects:

curl http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_projects","arguments":{"query":"security","limit":3}}}'

Security decisions

The server does not expose a generic query tool. Search runs in memory over known public fields. Tool schemas reject additional properties, and the server does not include a database or outbound HTTP adapter.

Pattern rejection is defense in depth. The main control is the absence of dangerous capabilities.

Trade-offs

The in-memory rate limiter is appropriate for this standalone example, not for a multi-instance global quota. A production deployment should use an external atomic store and trust forwarded client identity only from a controlled edge proxy.

License

MIT