mcp-server-builder
CLAUDE.md0 starsChanged 2 months agoMITView on GitHub
This document provides context for developers and AI agents building and maintaining the MCP Server Builder platform. MCP Server Builder is an AI-powered platform that transforms API documentation (URLs) into production-ready MCP (Model Context Protocol) servers through automated discovery, analysis, and code generation. Core Value: Eliminates manual MCP server coding by leveraging AI to understand APIs and automatically design optimal tool interfaces. Built by: Muhammad Sami Asghar Mughal (Senior AI Agent Engineer, COO at MARSA Empower) Explicitly NOT used: React…
- Reads credentials
- Installs packages
- Sends data out
- Commits and pushes
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ckm:banner-designSkill
- ckm:brandSkill
- ckm:design-systemSkill
- skill-creator-proSkill
- skill-creatorSkill
- ckm:slidesSkill
- ckm:ui-stylingSkill
- ui-ux-pro-maxSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
37 rules. About 0 are common, 23 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈23
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 87
Call OpenAI with structured prompts
- Distinctive: line 99
Import validation (all dependencies available)
- Distinctive: line 197
Add GraphQL detection logic
- Very specific: line 210
Add GraphQL client setup in generated main.py
- Very specific: line 219
Add to API_REFERENCE.md
- Very specific: line 249
After generation, browse /projects/{project_id} to:
- Very specific: line 251
Test syntax with python -m py_compile
- Very specific: line 252
Check requirements with pip install --dry-run -r requirements.txt
- Very specific: line 266
Fix: Check CORS_ORIGINS in config, set to * for development
- Very specific: line 269
Fix: Check validator.py output, ensure all dependencies in requirements.txt
- Distinctive: line 284
No native querying/filtering
- Distinctive: line 285
Must load all files for history view
- Distinctive: line 287
When to change: If project count > 10,000 or concurrent users > 100
- Distinctive: line 290
Decision: Use AI to design MCP tools from API analysis, not just generate code
- Distinctive: line 314
If AI design is wrong, generated code reflects it
- Distinctive: line 317
Best practice: Keep templates simple, logic in AI prompts
- Distinctive: line 320
Decision: No frontend framework (React/Vue)
- Distinctive: line 333
When to change: If UI has >100 components or complex interactivity
- Distinctive: line 346
Async: Use async/await for all I/O operations
- Distinctive: line 382
Test happy path and error cases
- Distinctive: line 387
Test full pipeline (URL → generated server)
- Distinctive: line 388
Use fixture APIs (httpbin, swaggerhub examples)
- Distinctive: line 390
Check project storage/retrieval
- Distinctive: line 399
Test with real APIs (GitHub, Stripe, Twilio)
- Distinctive: line 400
Verify generated servers run without errors
- Distinctive: line 401
Check MCP compatibility with Claude Desktop
- Very specific: line 402
Test on Windows/Mac/Linux
- Very specific: line 447
Write tests: test_discover_valid_url(), test_discover_invalid_url()
- Distinctive: line 458
Update system message or user message
- Very specific: line 459
Run test with fixed API: pytest tests/test_designer.py::test_design_tools
- Very specific: line 465
Update discovery.py to detect new format
- Distinctive: line 466
Add parsing logic to extract endpoints
- Distinctive: line 467
Add test with sample API of that format
- Very specific: line 468
Update documentation (API_REFERENCE.md, ARCHITECTURE.md)
- Very specific: line 482
Update version in app/__version__.py
- Very specific: line 483
Update CHANGELOG.md with changes
- Distinctive: line 484
Create git tag: git tag v0.2.0
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MCP Server Builder – Developer Instructions
This document provides context for developers and AI agents building and maintaining the MCP Server Builder platform.
Project Brief
MCP Server Builder is an AI-powered platform that transforms API documentation (URLs) into production-ready MCP (Model Context Protocol) servers through automated discovery, analysis, and code generation.
Core Value: Eliminates manual MCP server coding by leveraging AI to understand APIs and automatically design optimal tool interfaces.
Built by: Muhammad Sami Asghar Mughal (Senior AI Agent Engineer, COO at MARSA Empower)
Architecture At A Glance
Frontend (HTML/Tailwind/JS)
↓
FastAPI Backend (Python)
├─ URL Validation & SSRF Protection
├─ API Discovery (OpenAPI/Swagger/HTML parsing)
├─ AI Analysis (GPT-4 for tool design)
├─ Code Generation (Jinja2 templates)
└─ Project Storage (JSON files)
↓
Generated MCP Servers (complete Python projects)Technology Decisions & Rationale
| Component | Choice | Why |
| Frontend | Vanilla JS + Tailwind | Lightweight, no build step, works offline |
| Backend | FastAPI | Modern, fast, built-in validation (Pydantic), excellent async |
| AI Engine | OpenAI GPT-4 | Best at understanding APIs and designing interfaces |
| Templates | Jinja2 | Powerful, standard in Python ecosystem |
| HTTP Client | httpx | Async-ready, cleaner SSRF protection |
| Validation | Pydantic | Type safety, JSON schema generation |
| Development | Uvicorn | Fast local development, same as production |
Explicitly NOT used: React (overkill), Node.js (Python focus), database (JSON files OK for MVP)
Key Files & Responsibilities
Configuration & Setup
app/config.py(66 lines)- SSRF blocklist (private/loopback IP ranges)
- OpenAPI/Swagger detection paths
- Environment variable loading
- Security thresholds (timeout, max size, max discovery pages)
Data Models (Pydantic)
app/models/api.py(80 lines)APIRepresentation: Normalized API structureEndpoint: Individual API endpointDiscoveryResult: Output of API discovery phaseParameter,Response,SecurityScheme: API components
app/models/mcp.py(85 lines)MCPTool: Single tool definitionMCPServerDesign: Complete design with all toolsGeneratedMCPServer: Generated Python code artifactsMCPProject: Project state + all generated files
app/models/project.py(35 lines)ProjectMetadata: For listing/historyProjectSummary: Minimal summary for UIHistoryResponse: API response format
Services (Business Logic)
Expected locations (create if missing):
app/services/discovery.pydiscover_api(url: str)– Fetch and parse documentation- Handle OpenAPI/Swagger detection
- Extract endpoints, parameters, responses
- Output:
DiscoveryResult
app/services/analyzer.pyanalyze_api(discovery_result)– Extract structured API data- Normalize endpoint paths and methods
- Identify parameter requirements and types
- Detect authentication schemes
- Output:
APIRepresentation
app/services/designer.pydesign_tools(api: APIRepresentation)– AI-driven tool design- Call OpenAI with structured prompts
- Generate
MCPServerDesignwith optimal tools - Handle tool naming, descriptions, grouping
app/services/generator.pygenerate_server(design: MCPServerDesign)– Code generation- Render Jinja2 templates (main.py, tools.py, etc.)
- Validate Python syntax
- Output:
GeneratedMCPServer
app/services/validator.pyvalidate_generated_server(server: GeneratedMCPServer)– Syntax/schema checks- Import validation (all dependencies available)
- MCP schema compliance
- Return:
ValidationResultwith errors/warnings
Frontend
index.html(~500 lines)- Single-page app: landing → builder → results
- Sections: hero, how-it-works, features, footer
- Uses highlight.js for code display
static/client.js(expected)- Handle URL input and form submission
- POST to
/api/discover,/api/analyze,/api/design,/api/generate - Show progress indicators and status
- Display generated project files
- Download ZIP functionality
static/styles.css(expected)- Tailwind CSS (CDN or compiled)
- Dark mode support (via prefers-color-scheme)
- Responsive design (mobile-first)
Application Entry Point
app/main.py(expected)- FastAPI app instantiation
- CORS middleware
- Static file serving (HTML, CSS, JS)
- API routes:
/api/* - Error handling and logging
- Health check endpoint
Development Workflow
1. Local Setup
# Create venv
python -m venv venv
source venv/bin/activate
# Install deps
pip install -r requirements.txt
# Set environment
cp .env.example .env
# Edit .env: add OPENAI_API_KEY
# Run server
uvicorn app.main:app --reload --port 8000
# Open browser
open http://localhost:80002. Testing During Development
# Run full test suite
pytest
# Run with coverage
pytest --cov=app
# Run specific test file
pytest tests/test_security.py -v
# Watch mode (requires pytest-watch)
ptw
# Debug a single test
pytest tests/test_discovery.py::test_openapi_parsing -vvs3. Code Quality
# Format code
black app/ tests/
# Import sorting
isort app/ tests/
# Type checking
mypy app/
# Lint
flake8 app/
# All together
make format lint type4. Adding a Feature
Example: Add support for GraphQL APIs
- Define models in
app/models/api.pyGraphQLSchema,GraphQLQuery, etc.- Extend
APIRepresentationor create new type
- Update discovery in
app/services/discovery.py- Add GraphQL detection logic
- Parse GraphQL introspection schema
- Return appropriate model
- Implement analysis in
app/services/analyzer.py- Extract queries/mutations from GraphQL schema
- Map to
Endpoint-like structures
- Update designer in
app/services/designer.py- Handle GraphQL in AI prompts
- Design tools for queries vs mutations
- Extend generation in
app/services/generator.py- Add GraphQL client setup in generated main.py
- Include graphql-core in requirements
- Write tests
- Unit tests for each service
- Integration test end-to-end
- Fixtures with sample GraphQL schemas
- Update documentation
- Add to API_REFERENCE.md
- Update ARCHITECTURE.md
- Note in CHANGELOG.md
Debugging & Development Tips
Enable Debug Logging
# In app/main.py
import logging
logging.basicConfig(level=logging.DEBUG)
# Or set environment
DEBUG=true uvicorn app.main:app --reloadTest SSRF Protection
# Should fail (blocked IP ranges)
curl -X POST http://localhost:8000/api/discover \
-H "Content-Type: application/json" \
-d '{"url": "http://127.0.0.1:9000"}'
# Should succeed
curl -X POST http://localhost:8000/api/discover \
-H "Content-Type: application/json" \
-d '{"url": "https://api.github.com"}'Inspect Generated MCP Server
After generation, browse /projects/{project_id} to:
- View generated Python files
- Test syntax with
python -m py_compile - Check requirements with
pip install --dry-run -r requirements.txt
Common Issues & Fixes
Issue: OPENAI_API_KEY not found
- Fix:
cp .env.example .env && edit .envwith real key
Issue: ImportError: No module named 'pydantic'
- Fix:
pip install -r requirements.txtin activated venv
Issue: Port 8000 already in use
- Fix:
uvicorn app.main:app --port 8001
Issue: CORS errors in browser
- Fix: Check
CORS_ORIGINSin config, set to*for development
Issue: Generated server won't import
- Fix: Check
validator.pyoutput, ensure all dependencies inrequirements.txt
Important Architectural Decisions
1. JSON File Storage (Not Database)
Decision: Store projects as JSON files in app/data/ instead of using database
Rationale:
- Simpler MVP (no DB setup/migration)
- Easy to inspect/debug projects
- Version control friendly
- Projects are self-contained (can be emailed/shared)
Trade-off:
- Doesn't scale to millions of projects
- No native querying/filtering
- Must load all files for history view
When to change: If project count > 10,000 or concurrent users > 100
2. OpenAI GPT-4 for Tool Design
Decision: Use AI to design MCP tools from API analysis, not just generate code
Rationale:
- AI understands API semantics better than templates
- Produces better tool names/descriptions
- Handles unusual API patterns
- Iterative improvement possible (retry with feedback)
Trade-off:
- Slower than pure templates (1-2 sec latency)
- Costs per generation (e.g., $0.05-0.50 per design)
- Potential inconsistency in output
Mitigation: Caching, validation, user editing capability
3. Jinja2 for Code Generation
Decision: Template-based code generation after AI design
Rationale:
- Deterministic output (same design → same code)
- Easy to modify/version templates
- Clear separation: design (AI) vs rendering (templates)
Trade-off:
- If AI design is wrong, generated code reflects it
- Large/complex templates are hard to maintain
Best practice: Keep templates simple, logic in AI prompts
4. Vanilla JavaScript Frontend
Decision: No frontend framework (React/Vue)
Rationale:
- Reduces dependencies
- Single HTML file deployment
- No build step
- Works in any browser without transpilation
Trade-off:
- More verbose DOM manipulation
- Harder to manage complex state
- Limited component reusability
When to change: If UI has >100 components or complex interactivity
Performance Considerations
Bottlenecks (Measured)
- OpenAI API calls – ~2-3 seconds per design call
- Large API discovery – Parsing 100+ endpoints takes ~1-2 seconds
- Jinja2 template rendering – Usually <100ms even for large files
- Project storage – JSON I/O is fast for small projects
Optimization Opportunities
- Batch AI calls: Design multiple tools in one prompt
- Caching: Store discovered APIs to avoid re-fetching
- Async: Use async/await for all I/O operations
- Rate limiting: Queue requests if hitting OpenAI limits
- Compression: Gzip responses > 1KB
Scalability Notes
- Concurrent generations: Limited by OpenAI rate limits (3500 RPM tier-1)
- Project storage: 1GB disk ~= 10,000 medium projects
- Memory: FastAPI + Uvicorn uses ~100MB baseline
- Database: Move to PostgreSQL/MongoDB when projects > 100k
Security Guidelines
What We Protect Against
- SSRF attacks – Block private IP ranges (127.x, 10.x, 192.168.x, etc.)
- Large response DOS – Max 10MB response body
- URL bombing – Max 10 discovery pages
- Redirect loops – Max 5 redirects per request
- API key exposure – Never log API keys, only env vars
- Code injection – Sanitize API responses before templating
- Malicious generated code – Validate syntax before returning
What NOT to do
- ❌ Log API keys or sensitive data
- ❌ Store credentials in code or config files
- ❌ Trust user input without validation
- ❌ Disable HTTPS in production
- ❌ Commit .env files
- ❌ Run generated code without review
- ❌ Expose internal error details to clients
See SECURITY.md for detailed security architecture.
Testing Requirements
Unit Tests
- One test file per service
- Test happy path and error cases
- Mock external APIs (OpenAI, HTTP requests)
- Aim for 80%+ coverage
Integration Tests
- Test full pipeline (URL → generated server)
- Use fixture APIs (httpbin, swaggerhub examples)
- Validate generated code syntax
- Check project storage/retrieval
Security Tests
- SSRF protection (blocked IPs, redirects)
- URL validation (format, length, encoding)
- API key handling (never exposed in logs)
- Generated code doesn't include secrets
Manual Testing
- Test with real APIs (GitHub, Stripe, Twilio)
- Verify generated servers run without errors
- Check MCP compatibility with Claude Desktop
- Test on Windows/Mac/Linux
See TESTING.md for complete testing guide.
Deployment Notes
Development
uvicorn app.main:app --reload --port 8000Staging/Production
gunicorn app.main:app \
--workers 4 \
--worker-class uvicorn.workers.UvicornWorker \
--bind 0.0.0.0:8000 \
--env PYTHONUNBUFFERED=1Environment Variables (Production)
export OPENAI_API_KEY=sk-...
export DEBUG=false
export CORS_ORIGINS=https://example.com
export REQUEST_TIMEOUT=30
export LOG_LEVEL=INFOMonitoring
- Health check:
GET /health - Metrics: Log generation times, success/fail rates
- Errors: Alert on 500+ errors
- Usage: Track API calls per hour, top source URLs
See DEPLOYMENT.md for full production guide.
Common Tasks & How To Do Them
Add a New API Endpoint
- Define request model:
class DiscoverRequest(BaseModel): - Define response model:
class DiscoverResponse(BaseModel): - Create route:
@app.post("/api/discover") - Call service:
result = await discover_api(request.url) - Return response:
return DiscoverResponse(...) - Write tests:
test_discover_valid_url(),test_discover_invalid_url()
Update Jinja2 Template
- Find template file in
templates/ - Make edit (e.g., add new parameter)
- Test with:
python -m jinja2.env - Run generator:
pytest tests/test_generation.py - Inspect generated output for correctness
Change the AI Prompt
- Find prompt in
app/services/designer.py - Update system message or user message
- Run test with fixed API:
pytest tests/test_designer.py::test_design_tools - Review generated tool designs for quality
- Iterate if needed
Add Support for New API Format
- Extend
APIRepresentationor create new model - Update
discovery.pyto detect new format - Add parsing logic to extract endpoints
- Add test with sample API of that format
- Update documentation (API_REFERENCE.md, ARCHITECTURE.md)
Debug a Generated Server
- Find project in
app/data/{project_id}.json - Extract main.py, check syntax:
python -m py_compile - Try importing:
python -c "import sys; sys.path.insert(0, 'project'); import main" - Check requirements:
pip install --dry-run -r requirements.txt - Run:
python project/main.py
Version & Releases
Current version: Read from app/__version__.py
Release process:
- Update version in
app/__version__.py - Update
CHANGELOG.mdwith changes - Create git tag:
git tag v0.2.0 - Push:
git push origin main --tags - GitHub Actions creates release + uploads artifacts
Useful Commands
# Format code
make format
# Run tests
make test
# Type check
make type
# Full lint + type + format
make all
# Build for production
make build
# Start dev server
make dev
# Clean artifacts
make clean(See Makefile if it exists, or run commands manually)
Key Metrics to Track
- Generation time: Target <5 seconds per project
- Success rate: Target >95% (captures all endpoints)
- API key cost: Monitor GPT-4 usage
- Project storage: Clean up old projects monthly
- Error rate: Alert if >1% of requests fail
- User satisfaction: Track generated server usability
Future Work / Technical Debt
- Add GraphQL support (currently REST/OpenAPI only)
- Implement caching for discovered APIs
- Add database (PostgreSQL) for scalability
- Build CLI tool for headless generation
- Add webhook support for generated servers
- Implement server one-click hosting
- Add rate limiting on endpoints
- Improve AI prompts for edge cases
- Support multi-API composition
- Add automated testing for generated servers
Resources
- FastAPI Docs: https://fastapi.tiangolo.com/
- Pydantic Docs: https://docs.pydantic.dev/
- OpenAI API: https://platform.openai.com/docs/
- MCP Spec: https://modelcontextprotocol.io/
- Tailwind CSS: https://tailwindcss.com/
- Jinja2: https://jinja.palletsprojects.com/
Last Updated: 2024-01-01
Maintained By: Muhammad Sami Asghar Mughal
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

