portfolio-mcp

A remote MCP server for publishing to ashutoshverma.dev from any Claude client — including a phone.

Six tools that move bytes. The model does the writing; the server reads content, serves skills, saves drafts, and opens a pull request. It never merges. The merge button is the gate, and it is somewhere the model cannot reach.

Status: all six tools are built, and publish has opened a real pull request. list_content, get_skill, save_draft, get_content and discard_draft work from Claude Code, claude.ai and the phone. publish — the last one, and the only one that writes to the public repo — was proven against the real repo on 2026-08-03: a draft became a pull request, publishing it twice left exactly one, and main was never touched.

An idea on a train now reaches a Vercel preview URL with no laptop involved, and the merge button is still the only thing that makes it real.

Where things live

This repo is the server only. Two other repos are involved and neither is worked on from here:

No repo is ever cloned. Every read and write goes through the GitHub API, because a checkout on disk means stale state and surprise conflicts.

Related MCP server: hashnode-mcp-server

Read these first

The rejected-alternatives table in mcp-design.md is the most useful page in the repo. It is cheaper to read than to re-argue.

Stack

Bun · TypeScript strict · Elysia · Zod · Biome · bun:test · the MCP TypeScript SDK. Reasoning in ADR-001. Its original short version — that publish has to parse MDX, and MDX only parses in JavaScript — no longer holds: ADR-005 drops the MDX parse and leaves the Vercel preview build as the check. The runtime choice stands on the rest of ADR-001's reasoning.

No database, no accounts, no queue. Auth is an unguessable secret in the URL path — there is exactly one user, which is the one case OAuth adds nothing to.

Build order

Plumbing before anything interesting.

Slice 1 is deliberately almost nothing. The riskiest unknown in the plan is whether a custom connector behaves properly in the mobile app, and that cannot be tested locally. Find out with 80 lines, not after six tools exist.

Working in this repo

Feature work follows SPEC-WORKFLOW.md: an accepted ADR, then a sliced spec, then the red-green loop, one slice per PR.

bun install
bun test
bun run docs:sync    # regenerates GENERATED blocks; CI fails on drift

SETUP.md is install notes for the agent scaffold this repo started from. Safe to delete once you stop needing them.