WebMCP Portfolio Kit

• 

• 

• 

• 

• 

Inspiration

I'm a freelance WordPress/WooCommerce and Shopify developer, and I already had a portfolio site built for an earlier dev.to Gemini hackathon. What stuck with me from that event wasn't the winning entries — it was one unranked submission: an MCP-enabled portfolio where an agent could actually query someone's CV instead of just reading it. It never won anything, but it was the only project I actually remembered months later.

The WebMCP Challenge was the excuse to finally build that properly — and to fix what I think was the real gap in that original idea: answering "what are his skills" is a parlor trick. Answering "does he actually fit this job, and where are the gaps" is what a technical buyer actually needs.

What it does

WebMCP Portfolio Starter Kit exposes 8 WebMCP tools on a normal-looking portfolio site. An agent — acting for a recruiter, a CTO, whoever — can hand it a real brief and get back a transparent requirement → evidence → gap map: evidence found, or no direct evidence, stated plainly. It's never a forced "95% match" score.

From there the agent can compare engagement options (migration / optimization / audit / advisory), save a session-only discovery brief, and prepare a contact request. A human reviews the draft; the core kit never sends a message.

It's also a starter kit, not just a personal site: config, content, and code are cleanly separated, so anyone can fork it, drop in their own skills and projects, and deploy their own copy to Vercel with one click and zero required environment variables.

How we built it

I extended my existing Vite/React portfolio rather than starting from scratch, restructuring it into config/ (the fork surface), content/ (skills, case studies, engagement options), and generic src/lib/ tool code that never hardcodes a name.

All 8 tools use the WebMCP Imperative API with explicit input schemas. Evidence tools are read-only; the remaining tools only update the visible page or create an unsent, reviewable draft.

The core kit needs no backend. The one optional exception is a /setup Profile Bootstrapper that uses Vercel AI Gateway to help a forker draft their profile.json from raw material — off by default behind an explicit env var, output validated against a strict schema, and prompted to treat source text as data, never as instructions.

Testing wasn't just manual clicking: validate-content checks the profile data against a schema, test:forkability runs the matching logic against a completely unrelated fixture persona, and a production run of the official webmcp-evals suite passed all eight tools against the live deployment.

Challenges we ran into

The hard trade-off was breadth versus coherence. I kept all eight tools, but prioritised their shared evidence model, clear side-effect boundaries, and production testing over extra visual polish and stretch features.

Avoiding a false-precision "fit score" was a real design problem, not just a copy choice — early versions of the matching tool risked implying certainty the underlying logic didn't have. I settled on a plain requirement/evidence/gap map with an explicit disclaimer field on every response instead.

And I didn't want "forkable" to just be a claim in a README. Proving it meant building an actual unrelated test persona and a smoke test, not just asserting the code was generic.

Accomplishments that we're proud of

The forkability test genuinely passes against a persona with nothing to do with cloud infrastructure — it surfaces a real skill match, a real project match, and an honestly stated unmatched requirement, for a profile that shares nothing with mine.

Zero required environment variables to deploy the core kit — fork, edit two JSON files, click deploy.

The optional AI-assisted drafting path is off by default and explicitly designed against prompt injection in its own source material, not just in theory.

And map_requirements_to_evidence stating a gap plainly, instead of forcing a match — that's the single behavior the whole project is really about.

Existing-work disclosure

The visual portfolio and its self-authored project history existed before the challenge. During the submission period, I meaningfully extended it with eight WebMCP tools and schemas, the requirement-to-evidence interface, source-labelled outputs, the reusable config/content/code split, the Bootstrapper, and automated validation and evaluation. The public repository’s dated September 2–3 commits document that WebMCP-specific work.

What we learned

That a "never overclaim" constraint has to be enforced in the code itself, not just promised in a README — stating a gap instead of forcing a match, and never wiring up an auto-send path for the contact tool.

That deterministic, auditable matching is a legitimate design choice against a generative one, not just a corner cut when you're short on time — every match traces back to real data instead of a model's guess.

And that two small automated tests, plus one production evals run, are worth more than an evening of manual clicking when there's no time left to re-verify everything by hand before a deadline.

What's next for WebMCP Portfolio Starter Kit

Support importing authorised structured exports or pasted profile material — for example from a PeoplePerHour export — into profile.json, instead of a one-time manual copy.

Semantic, embedding-based matching via Vercel AI Gateway as an option — making the matching smarter while keeping every match's underlying evidence fully auditable, not replacing it with a black box.

And more real forks, to prove this out beyond the one alternate-persona fixture.

Built With

• javascript
• json-schema
• node.js
• react
• vercel
• vercel-ai-gateway
• vite
• webmcp
• zod