personal-mcp

Albert Yan's homepage — a website, a REST API, and an MCP server that are the same thing.

Most personal sites that claim to be "API-accessible" are a site plus a bolted-on /api folder that drifts out of sync within a month. This one is built on a single rule:

One content graph. One contract. Three renderers. Zero duplication.

content/ holds the facts. src/core/ resolves them. src/app/ renders them as HTML, as JSON, and as MCP. A fact about me is defined once and reachable three ways — never implemented three times.

Talk to it

As a human

https://albertyan.dev

As an agent (MCP)

claude mcp add --transport http albert https://albertyan.dev/mcp

Exposes MCP tools (get_profile, list_projects, get_resume, get_now, search, leave_message), resources (albert://profile, albert://projects/{slug}, …) so a client can attach context without spending a tool call, and prompts.

As a program (REST)

curl https://albertyan.dev/api/v1                    # hypermedia root, links everything
curl https://albertyan.dev/api/v1/resume             # also ?format=jsonresume
curl -H 'Accept: application/json' https://albertyan.dev/projects/<slug>

Every page also answers to Accept: application/json and text/markdown, and has a .md twin URL. Same resource, three representations — rather than a parallel /api universe.

Machine-readable entry points: /openapi.json, /llms.txt, /.well-known/mcp.json.

Related MCP server: mundigital

How it works

content/        source of truth — MDX + JSON, validated at build, versioned by git
  ↓
src/core/       domain. framework-free. the only code that reads content.
  schema/         Zod, written once → TS types + build validation + OpenAPI + MCP schemas
  resolvers/      getProfile(), listProjects(), getResume(), …
  ↓
src/app/        adapters. thin. parse → resolve → serialize.
  (site)/         React Server Components  → HTML
  api/v1/         route handlers           → JSON
  api/mcp/        mcp-handler              → MCP

The arrows only point one way, and that is enforced by ESLint rather than by discipline — src/core may not import React, Next, or any adapter. See eslint.config.mjs.

There is no database. Content is typed files in git, which already provides durable storage, versioning, diffs, review, and revert for the ~200 facts that make up a person. Zod occupies the slot an ORM usually would, and does it at build time: malformed content fails CI instead of throwing in production.

Design decisions and their rationale live in docs/PLAN.md.

Develop

npm install
npm run dev            # http://localhost:3000
npm run check          # typecheck + lint + build — the same gate CI runs

cp .env.example .env.local

Requires Node ≥ 20.9 (CI and production run 24).

Stack

Next.js 16 (App Router) · React 19 · TypeScript (strict, plus noUncheckedIndexedAccess) · Tailwind v4 · Zod · mcp-handler over the official MCP TypeScript SDK · Vercel Fluid Compute.

MCP transport is Streamable HTTP, per the current spec — not the deprecated HTTP+SSE transport. A stdio proxy is published separately for clients that need one; it holds no content of its own and therefore cannot go stale.

License

MIT for the code. The content under content/ is about a real person; please don't misrepresent it.