When I first built the MCP layer for my portfolio, it was purely read-only retrieval — AI agents could ask "list his projects" and get back structured JSON. Useful, but dumb. It had no idea what you actually wanted.
A visitor asking "show me his AI work" and one asking "navigate to projects" look identical to a string-matching system. They aren't. One wants a search result. The other wants to be taken somewhere. This commit was about teaching the server the difference — using Jev.
What Is Jev?
Jev is a small, fast reasoning model from TypeSafe AI, accessed via the @typesafe-ai/sdk. It's built for structured decisions — not open-ended generation, but precise classification and routing with typed outputs and confidence scores.
Think of it as the brain that sits between a user's raw query and the right action. You give it a question and a set of choices; it returns a choice and a confidence number between 0 and 1. That's it. No paragraphs, no fluff — just a decision.
It runs in under 1200ms with a hard timeout. For an interactive portfolio, that's the ceiling I'm willing to accept before falling back gracefully.
Two Jobs for Jev
I gave Jev two distinct responsibilities in this commit:
1. Route Classification
When a visitor types something in the chat, should I navigate them somewhere, or answer in chat? That's the routing problem.
I built a classifyRoute function in lib/jev.ts. It loads the full routing catalog — every page on the site — converts each into a named choice, and sends the visitor's query to Jev's systemOne API:
const { answers } = await client.systemOne({
model: 'jev-1.13.0',
state: { visitorQuery: query, portfolio: portfolioSummary },
questions: {
destination: choice(
'Determine whether the visitor is navigating or asking...',
toChoiceCriteria(catalog) // e.g. { "projects": "...", "blog": "..." }
)
}
})If confidence is above 0.75, the portfolio navigates. Below that threshold — it falls back to chat. No hallucinated destinations, no silent failures.
2. Search Intent Classification
The second job is for the new search_portfolio MCP tool. When an AI agent asks "what frameworks does he know?", Jev classifies this as skills intent — which tells the search layer exactly which part of the corpus to prioritize.
// 8 possible intents identity | career | skills | projects | certifications | blogs | workshops | general
Again, confidence gating: if Jev isn't at least 75% sure, intent falls back to general. The system degrades gracefully, never confidently wrong.
Hybrid Search: Lexical + Semantic
The new lib/mcp/search.ts is where intent meets retrieval. There are two modes:
- Lexical (always on): Term matching across a curated public corpus — about chunks, projects, resume sections, blog metadata, workshops. Fast, deterministic, zero API cost.
- Semantic (AI-gated): Cosine similarity over 1536-dimension Gemini embeddings, stored in
aniket-data/embeddings.json. Only fires whenMCP_AI_SEARCH_ENABLED=trueand quota allows.
The two rankings are fused using Reciprocal Rank Fusion — a simple but effective technique where the final score is the sum of 1 / (60 + rank) across both lists. Top-5 results get returned.
// Response shape
{
results: SearchResult[],
intent: SearchIntent,
retrievalMode: 'lexical' | 'hybrid',
degraded: boolean
}The degraded flag tells the caller whether AI assist was available or not. The search always returns something — there is no empty failure state.
The Security Layer: lib/mcp/http.ts
With AI calls now happening server-side in response to public MCP requests, I couldn't just rate-limit at the edge. I needed layered protection:
- Origin validation: Only HTTPS origins pass. In dev, localhost is allowed. Any malformed or non-HTTPS origin gets a hard 403.
- Body size cap: POST bodies over 64 KiB are rejected before being read. Batch JSON-RPC envelopes are blocked entirely.
- Request IDs: Every request gets a UUID stamped in the response header for traceability without logging raw queries or IPs.
- HMAC-keyed rate limits: IPs are never stored raw — they're hashed via HMAC-SHA256 with a dedicated secret before entering the rate limiter.
The whole thing is wrapped in a secureMcpHandler that applies all of this before the actual MCP SDK handler even sees the request.
Quota: Two Tiers, One Kill Switch
AI calls cost money. The quota system in lib/mcp/quota.ts enforces two independent budgets using Firestore as the shared counter:
| Quota type | Limit | Window |
|---|---|---|
| request | 60 / IP | per minute |
| ai (per IP) | 20 / IP | per minute |
| ai (global) | 500 total | per day |
If Firestore is unreachable (timeout: 1500ms), it fails closed for AI and open for reads — local data is still served, paid calls aren't. The kill switch is a single env flag: MCP_AI_SEARCH_ENABLED=false disables everything AI-related instantly, without a redeploy.
One reservation = at most one Jev call + one embedding. Provider timeouts can still incur charges — that's the trade-off. But the budget won't silently spiral.
Two New MCP Tools
The commit ships two new tools on top of the existing 12:
| Tool | What it does |
|---|---|
| search_portfolio | Hybrid lexical + semantic search across the full public corpus. Returns intent, retrieval mode, and degraded flag. |
| resolve_portfolio_destination | Uses Jev to suggest a navigation destination for a query. Returns a URL and confidence — never opens anything directly. |
The existing ask_about_aniket tool was also quietly upgraded to share the new search implementation — same hybrid engine, same quota, same fallback behavior.
40 Labeled Retrieval Fixtures
This is the part I'm most proud of. Before shipping, I wrote 40 labeled retrieval fixtures in tests/mcp-search.test.ts — real-world queries mapped to expected result IDs.
The test suite validates that at least 90% of queries return the correct result in the top 5. Anything below that and the build fails. It's a hard quality gate, not a vibe check.
mcp-search.test.ts— 40 labeled retrieval fixturesmcp-http.test.ts— CORS, body limits, origin validationmcp-quota.test.ts— Firestore transaction logic, timeout behaviormcp-embedding.test.ts— Cosine similarity correctnessmcp-route.test.ts— Jev routing decisions and confidence gating
52 files changed. 997 insertions. 1341 deletions. Some of those deletions were the old, sprawling MCP route handler that grew to ~500 lines. It's been replaced by focused, testable modules.
What Actually Changed for Users
Nothing visually. Everything structurally. The chat still looks the same. But now:
- "Take me to his projects" → Jev classifies
navigate→ confidence 0.91 → browser navigates. - "What AI frameworks does he use?" → Jev classifies
skillsintent → hybrid search → structured results in chat. - "Tell me about RagBot" → Jev routes to the RagBot project page if confidence is high; otherwise answers in chat with retrieved evidence.
The portfolio now understands intent. It routes with confidence. It searches with context. And when it's uncertain — it falls back without pretending.
Try the New MCP Tools
The full server is public. If you're building an MCP client or want to query my portfolio programmatically:
// In your mcp_config.json
"aniketppatil-portfolio": {
"serverUrl": "https://www.aniketppatil.com/api/mcp"
}
// Tools available: search_portfolio, resolve_portfolio_destination,
// list_projects, get_project_details, list_blogs, ask_about_aniket + moreLexical search is always available. Hybrid (AI-assisted) search fires when enabled and quota allows — and the response always tells you which mode ran.
What I Learned
Adding AI to public infrastructure is mostly a security and reliability problem, not a model problem. The model part — Jev's structured choice API — was the easiest part of this commit. The hard parts were: body size limits, HMAC-keyed rate limiting, fail-closed quota, graceful degradation, and building a test suite rigorous enough to trust a retrieval system.
If you're building AI-powered public APIs, start with the kill switch. Build the tests before the feature. And treat every AI call as a cost center, not a utility.