This is a submission for the GitHub Finish-Up-A-Thon Challenge
What I Built
Last semester, under the pressure of B.Tech finals and a looming presentation deadline, I shipped a full-stack AI agent system called the Unified MCP Framework. The idea was straightforward: build a single orchestration layer where an AI could interpret natural language commands and route them to the right tool - a filesystem, a browser, a GitHub API - without the developer having to wire each one manually.
The core architecture had three pieces:
- A React + Vite frontend for the chat interface and tool trace visualization
- A FastAPI backend acting as the AI Orchestrator, powered by Google Gemini
- Three specialized tool servers: Filesystem (sandboxed), Browser (Playwright), and GitHub (PyGithub)
It worked. The demo went well. I submitted the PDF, the PPTX, the poster - and then I closed the repo and moved on.
The problem was that "it worked" and "it was usable by anyone else" were two very different things.
Demo
π¦ npm package: unified-mcp on npm
π» GitHub repo: Om-Shree-0709/Major-Project
The system takes a natural language query like:
"Summarize the latest commits in my repo and write a summary file."
...and routes it across the GitHub tool (fetch commits), Filesystem tool (write file), and Gemini (generate summary) - with each tool call visible in the frontend trace panel.
The Comeback Story
When I came back to this project after graduation exams, here's what I found:
Before:
- No installation path that didn't require reading the source code
- README that assumed you already understood what MCP was
- No
.env.example, so first-time setup always failed - Playwright setup instructions buried halfway through a wall of text
- The npm package (
unified-mcp) existed but had no usage examples - just a package.json and good intentions - Zero error messages that actually told you what went wrong; just raw Python tracebacks
After:
- Rewrote the README top-to-bottom: quick-start first, architecture second
- Added a proper
.env.examplewith inline comments - Separated Windows and Unix setup paths - Playwright's async event loop fix is Windows-only; nobody should need to figure that out mid-debug
- Added a
QUICK_TEST_QUERIES.mdandCOMPLEX_TEST_QUERIES.mdso any developer could validate the system end-to-end in under 5 minutes - Fixed the sandboxed filesystem error handling - instead of a traceback, you now get a clear message:
"Access denied: path is outside sandbox directory" - Polished the npm package with real usage documentation, proper exports, and a working install flow
- Added a troubleshooting section covering the three most common failure modes: backend offline, Playwright binary missing, env vars not loaded
The week the npm package was properly documented and re-announced: 750+ downloads.
That number matters to me not because it's large - it isn't - but because week one with no usable docs had yielded single digits. The code hadn't changed. The docs had.
My Experience with GitHub Copilot
I'll be specific about where it actually helped, because "Copilot helped me" is a useless sentence.
Rewriting the README: I had rough notes about what the system did. Copilot autocompleted the setup steps once I established the structure - it understood that after pip install -r requirements.txt comes playwright install chromium, and it kept that sequencing consistent when I reorganized sections. Saved probably 30 minutes of manual tab-matching.
The .env.example file: I typed the first variable with a comment. Copilot generated the remaining four in the same format - correct variable names, sensible placeholder values. That's the kind of tedious-but-error-prone work where it genuinely earns its keep.
The error handling refactor: The original filesystem_server.py had bare except Exception as e: raise e blocks everywhere. I asked Copilot to help me add user-facing error messages. It suggested wrapping each block with specific messages tied to the exception type - FileNotFoundError, PermissionError, IsADirectoryError - rather than a single generic catch. That was the right call and I wouldn't have done it that cleanly by hand at 11pm.
The COMPLEX_TEST_QUERIES.md: I started writing test cases by hand. Copilot kept generating the next logical one based on the pattern I established. "List all Python files in the sandbox" β "Read the contents of a specific file" β "Write a new file with generated content." The progression made sense and I kept most of it.
Where it didn't help: anything requiring knowledge of my specific project structure. It would hallucinate import paths, suggest tools I hadn't built, and occasionally propose FastAPI route patterns that conflicted with what I already had. The rule I settled on: use it for boilerplate and structure, verify everything that touches the actual logic.
The original project was built in a sprint, for a grade. This version was rebuilt for the people who might actually use it. That's a different problem, and it turned out to be a harder one. GitHub Copilot made the second pass faster - not by doing the thinking, but by handling the parts that didn't require any.
If you're building MCP tooling and want a working reference implementation with a real setup path, the repo is linked above. The npm package is live. Feedback welcome.
Follow for more coverage on MCP, agentic AI, and developer infrastructure.
