- An MCP agent framework built as a B.Tech project hit 750+ npm downloads in its first properly documented week.
- The MCP agent framework code never changed — only the README, .env setup, and error messages were rewritten.
- Week one with no usable documentation yielded single-digit downloads; proper docs multiplied that by roughly 100x.
- GitHub Copilot accelerated the documentation rewrite by handling boilerplate — but hallucinated on project-specific logic.
The MCP Agent Framework Nobody Could Actually Use
There’s a version of this story that’s familiar to anyone who’s shipped a side project under deadline pressure. Om Shree built a working MCP agent framework as a B.Tech major project, demoed it successfully, submitted the PDF and the poster — and then closed the repo. The problem wasn’t the code. The problem was that “it works” and “someone else can use it” are two entirely different engineering problems, and only one of them gets graded.
The project, now published as unified-mcp on npm, is a single orchestration layer that takes natural language commands and routes them to the right tool — a sandboxed filesystem, a Playwright-powered browser, or the GitHub API — without requiring developers to wire each integration manually. The AI backbone is Google Gemini, coordinated through a FastAPI backend, with a React and Vite frontend that visualises each tool call as it happens. It’s a practical take on what the industry is increasingly calling agentic AI: systems that don’t just answer questions but actually do things across multiple services in sequence. As an MCP agent framework, it represents exactly the kind of concrete, runnable implementation that the broader ecosystem needs more of.
The Model Context Protocol itself is worth understanding as context here. MCP, originally introduced by Anthropic, is an open standard designed to give AI models a consistent way to interact with external tools and data sources. Think of it as a common interface layer — instead of every AI application reinventing its own tool-calling logic, MCP provides a shared contract. Shree’s MCP agent framework sits on top of that idea and makes it concrete: here’s a GitHub tool, a filesystem tool, a browser tool, and an AI orchestrator smart enough to chain them together when you ask it to “summarise the latest commits and write a summary file.”
That’s a genuinely useful demo. The kind that gets nods in a presentation room. But the repo that shipped after that presentation was, by Shree’s own account, effectively unusable by anyone who hadn’t built it themselves.
What “Broken” Actually Looked Like
The list of problems reads like a checklist of every open-source anti-pattern at once. No installation path that didn’t require reading the source code. A README that assumed the reader already knew what MCP was. No .env.example file, which meant first-time setup failed every single time. Playwright setup instructions buried deep in a wall of undifferentiated text. An npm package that technically existed but contained no usage examples — just a package.json and, as Shree puts it, “good intentions.” And when things went wrong, users got raw Python tracebacks instead of anything resembling a helpful error message.
None of this is unusual. It’s the standard gap between code that works in the author’s environment and code that works anywhere else. Any MCP agent framework faces this same adoption hurdle: the underlying protocol knowledge cannot be assumed, and every missing step in the setup process costs real users. What makes Shree’s case instructive is that he went back and fixed it systematically — and then measured the result.
The Documentation Rewrite That Changed Everything
The fix wasn’t a refactor. The underlying architecture of the MCP agent framework — FastAPI orchestrator, three tool servers, Gemini integration, React frontend — stayed exactly as it was. What changed was everything around the code: the README got rewritten top-to-bottom with quick-start instructions first and architecture explanation second. A proper .env.example appeared with inline comments on every variable. Setup paths were split for Windows and Unix, because Playwright’s async event loop fix is Windows-specific and no developer should have to discover that mid-debug at 11pm. Two new files, QUICK_TEST_QUERIES.md and COMPLEX_TEST_QUERIES.md, gave any new user a way to validate the entire system end-to-end in under five minutes.
The error handling got a proper pass too. The original filesystem_server.py had bare except Exception as e: raise e blocks throughout — technically catching errors, practically useless for diagnosis. The rewrite replaced those with specific, human-readable messages tied to exception type: FileNotFoundError, PermissionError, IsADirectoryError. Instead of a traceback, you now get “Access denied: path is outside sandbox directory.” That’s the difference between an MCP agent framework that respects its users and one that doesn’t.
The result: 750+ npm downloads in the first week after the rewrite went live. The week before, with the same code and no usable docs, the number was in the single digits. That’s not a small improvement in conversion — it’s a roughly hundredfold difference driven entirely by documentation quality. The MCP agent framework itself hadn’t changed. The developer experience around it had.
How GitHub Copilot Fit Into the Process
Shree is precise about where AI assistance actually helped, which is refreshing compared to the usual vague claims about productivity gains. For the README rewrite, Copilot handled sequencing consistency — once the structure was established, it correctly inferred that playwright install chromium follows pip install -r requirements.txt and kept that order intact across reorganised sections. Shree estimates it saved about 30 minutes of manual cross-referencing.
The .env.example file was a cleaner win. Type the first variable with a comment, and Copilot generated the remaining four in identical format with correct variable names and sensible placeholder values. That’s exactly the kind of tedious-but-error-prone task where autocomplete earns its keep — the output is predictable, the pattern is obvious, and the cost of a mistake is a broken setup experience for every new user.
For the error handling refactor, Copilot suggested wrapping each exception block with specific messages tied to exception type rather than a single generic catch. “That was the right call,” Shree notes, “and I wouldn’t have done it that cleanly by hand at 11pm.” The test query documents benefited similarly — Copilot kept generating the next logical test case once the pattern was established, producing a coherent progression from basic file listing through to multi-step content generation.
Where it fell apart: anything requiring knowledge of the actual project structure. Copilot hallucinated import paths, suggested tools that didn’t exist in the codebase, and occasionally proposed FastAPI route patterns that conflicted with what was already there. The rule Shree settled on — use it for boilerplate and structure, verify everything that touches the actual logic — is probably the most honest description of how these tools currently function in a real workflow. They’re exceptional at pattern completion. They’re unreliable as soon as context specificity matters. This holds true whether you’re building a generic utility or a purpose-built MCP agent framework where the tool-routing logic is highly specific to the project.
Why This Number Actually Matters
Seven hundred and fifty downloads isn’t a viral moment. It won’t make the npm weekly charts. But that’s not the point Shree is making, and it’s not the point worth taking from this story either. The signal here is the ratio: near-zero to 750 with no code changes whatsoever. Documentation wasn’t a finishing touch — it was the actual product, from the perspective of anyone encountering the repo for the first time.
This is a lesson the open-source world relearns constantly but struggles to institutionalise. Projects like Anthropic’s Model Context Protocol ship with thorough specs and reference implementations precisely because adoption depends on the first-hour developer experience, not the underlying technical merit. A well-architected tool that nobody can set up competes directly with a mediocre tool that has a five-minute getting-started guide — and the mediocre tool often wins.
For developers building in the MCP and agentic AI space right now, that tension is particularly sharp. The tooling ecosystem is young, fragmented, and moving fast. Every MCP agent framework published today is a potential reference point for developers who are still figuring out how to structure tool orchestration in their own projects. Reference implementations like Shree’s unified-mcp have real value as concrete working examples — but only if someone can actually run them. The 750-download story is a small, specific proof point for something the industry already knows but rarely quantifies: onboarding friction kills adoption faster than almost any technical shortcoming. Fix the docs first. The architecture can wait.
