🚀 Ultimate MCP Platform
A complete AI development toolkit that lets you write, test, and execute code safely—even if you've never coded before.
Think of this as your AI coding assistant's brain: it can check code for errors, run tests, execute programs safely, store knowledge in a graph database, and generate new code from templates. Perfect for AI agents, developers, and anyone building with Claude or other AI tools.
📋 Table of Contents
- What Is This?
- Quick Start (3 Steps)
- What Can It Do?
- All Available Tools
- Built-in AI Prompts
- Real-World Examples
- Accessing Your Services
- Troubleshooting
- Advanced Usage
🎯 What Is This?
Ultimate MCP is a complete development platform that gives AI assistants (like Claude) powerful tools to:
- ✅ Check code for errors (linting)
- ✅ Run code safely in isolated containers
- ✅ Execute tests automatically
- ✅ Generate new code from templates
- ✅ Store and query knowledge in a graph database
- ✅ Track relationships between code, services, and data
Who is this for?
- 🤖 AI developers building agents with Claude, ChatGPT, or custom LLMs
- 👨💻 Software developers who want automated code quality tools
- 🎓 Students learning to code with AI assistance
- 🏢 Teams building internal developer tools
What makes it special?
- 🔒 Secure by default - Code runs in sandboxes, can't harm your system
- 🧠 Memory included - Neo4j graph database remembers everything
- 🔌 MCP compatible - Works with Claude Desktop and any MCP client
- 📦 One-click deploy - Everything runs in Docker containers
⚡ Quick Start (3 Steps)
Prerequisites
You need these installed on your computer:
- Docker Desktop (Download here)
- Git (Download here)
That's it! No Python, Node.js, or other tools needed.
Step 1: Download the Project
Open your terminal (Command Prompt on Windows, Terminal on Mac/Linux) and run:
git clone https://github.com/Senpai-Sama7/Ultimate_MCP.git
cd Ultimate_MCP
Step 2: Start Everything
./deploy.sh
This single command will:
- ✅ Build all Docker containers
- ✅ Start Neo4j database
- ✅ Launch the backend API
- ✅ Start the web interface
- ✅ Generate secure passwords automatically
Wait 1-2 minutes for everything to start up.
Step 3: Verify It's Working
Open your browser and visit:
- Web Interface: http://localhost:3000
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/health
If you see a green "OK" status, you're ready to go! 🎉
🛠️ What Can It Do?
1. Code Quality Checking (Linting)
Automatically finds bugs, style issues, and potential problems in your code.
Example Use Case: Before deploying code, check if it follows best practices.
2. Safe Code Execution
Runs Python code in an isolated sandbox that can't access your files or network.
Example Use Case: Test a code snippet from the internet without risking your computer.
3. Automated Testing
Runs your test suite and reports which tests pass or fail.
Example Use Case: Verify your changes didn't break existing functionality.
4. Code Generation
Creates new code from templates by filling in variables.
Example Use Case: Generate boilerplate code for new API endpoints.
5. Knowledge Graph Storage
Stores information about your code, services, and their relationships in a graph database.
Example Use Case: Track which microservices call each other and their dependencies.
6. Graph Queries
Search and analyze your stored knowledge using Cypher query language.
Example Use Case: Find all services written in Python that call the authentication service.
🔧 All Available Tools
Tool 1: lint_code - Check Code Quality
What it does: Analyzes code for errors, style issues, and complexity.
When to use it: Before committing code, during code reviews, or when learning.
Example Request:
curl http://localhost:8000/lint_code \
-H "Content-Type: application/json" \
-d '{
"code": "def calculate_total(items):\n total = 0\n for item in items:\n total += item.price\n return total",
"language": "python"
}'
Example Response:
{
"id": "abc123",
"code_hash": "e788cd4a...",
"functions": ["calculate_total"],
"classes": [],
"imports": [],
"complexity": 2.0,
"linter_exit_code": 0,
"linter_output": ""
}
What the response means:
functions: List of function names foundcomplexity: How complex the code is (lower is better)linter_exit_code: 0 means no errors foundlinter_output: Any warnings or errors
Tool 2: execute_code - Run Code Safely
What it does: Executes Python code in a secure sandbox with resource limits.
When to use it: Testing code snippets, running calculations, or prototyping.
Example Request:
curl http://localhost:8000/execute_code \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"code": "import math\nresult = math.sqrt(144)\nprint(f\"Square root: {result}\")",
"language": "python"
}'
Example Response:
{
"id": "xyz789",
"return_code": 0,
"stdout": "Square root: 12.0\n",
"stderr": "",
"duration_seconds": 0.023
}
What the response means:
return_code: 0 = success, non-zero = errorstdout: What the program printedstderr: Any error messagesduration_seconds: How long it took to run
⚠️ Security Note: Requires authentication token (found in .env.deploy file).
Tool 3: run_tests - Execute Test Suites
What it does: Runs pytest tests and reports results.
When to use it: Continuous integration, before deployments, or during development.
Example Request:
curl http://localhost:8000/run_tests \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"code": "def add(a, b):\n return a + b\n\ndef test_add():\n assert add(2, 3) == 5\n assert add(-1, 1) == 0",
"language": "python"
}'
Example Response:
{
"id": "test456",
"return_code": 0,
"stdout": "===== test session starts =====\ncollected 1 item\n\ntest_add PASSED [100%]\n\n===== 1 passed in 0.02s =====",
"stderr": "",
"duration_seconds": 0.156
}
What the response means:
return_code: 0 = all tests passedstdout: Test results and summary- Look for "PASSED" or "FAILED" in the output
Tool 4: generate_code - Create Code from Templates
What it does: Fills in template variables to generate new code.
When to use it: Creating boilerplate, generating similar functions, or scaffolding.
Example Request:
curl http://localhost:8000/generate_code \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"template": "def {{ function_name }}({{ params }}):\n \"\"\"{{ docstring }}\"\"\"\n return {{ return_value }}",
"context": {
"function_name": "get_user_age",
"params": "user_id: int",
"docstring": "Retrieve user age from database",
"return_value": "database.query(user_id).age"
}
}'
Example Response:
{
"generated_code": "def get_user_age(user_id: int):\n \"\"\"Retrieve user age from database\"\"\"\n return database.query(user_id).age"
}
Tool 5: graph_upsert - Store Knowledge
What it does: Saves nodes and relationships to the Neo4j graph database.
When to use it: Tracking services, storing code metadata, or building knowledge graphs.
Example Request:
curl http://localhost:8000/graph_upsert \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "auth_service",
"labels": ["Service", "Microservice"],
"properties": {
"name": "Authentication Service",
"language": "python",
"version": "2.1.0",
"port": 8080
}
},
{
"id": "user_db",
"labels": ["Database"],
"properties": {
"name": "User Database",
"type": "PostgreSQL",
"host": "db.example.com"
}
}
],
"relationships": [
{
"from": "auth_service",
"to": "user_db",
"type": "CONNECTS_TO",
"properties": {
"connection_pool_size": 20,
"timeout_seconds": 30
}
}
]
}'
Example Response:
{
"nodes_created": 2,
"relationships_created": 1,
"properties_set": 9
}
Real-World Use Case: Track your microservices architecture:
- Which services exist
- What languages they use
- How they connect to each other
- Performance metrics for each connection
Tool 6: graph_query - Search Knowledge
What it does: Queries the graph database using Cypher language.
When to use it: Finding patterns, analyzing relationships, or generating reports.
Example Request:
curl http://localhost:8000/graph_query \
-H "Content-Type: application/json" \
-d '{
"cypher": "MATCH (s:Service)-[r:CONNECTS_TO]->(d:Database) RETURN s.name AS service, d.name AS database, r.timeout_seconds AS timeout",
"parameters": {}
}'
Example Response:
{
"results": [
{
"service": "Authentication Service",
"database": "User Database",
"timeout": 30
}
],
"count": 1
}
Common Query Examples:
- Find all Python services:
MATCH (s:Service {language: "python"})
RETURN s.name, s.version
- Find services with high complexity:
MATCH (s:Service)
WHERE s.complexity > 10
RETURN s.name, s.complexity
ORDER BY s.complexity DESC
- Find connection chains:
MATCH path = (s1:Service)-[:CONNECTS_TO*1..3]->(s2:Service)
RETURN s1.name, s2.name, length(path) AS hops
🎭 Built-in AI Prompts
The platform includes 7 pre-configured AI assistant prompts for different tasks:
1. proceed - Senior Pair-Programmer
Use when: You need help writing or debugging code What it does: Acts as an experienced developer helping you code Example: "Help me implement a user authentication system"
2. evaluate - Comprehensive Audit
Use when: You need a thorough code review What it does: Analyzes code quality, security, and best practices Example: "Review this API endpoint for security issues"
3. real-a - Production Delivery
Use when: Preparing code for production deployment What it does: Ensures code is production-ready with proper error handling Example: "Make this code production-ready"
4. test-a - CI Quality Runner
Use when: Setting up automated testing What it does: Creates comprehensive test suites Example: "Generate tests for this function"
5. improve - Holistic Refactor
Use when: Code works but needs improvement What it does: Refactors code for better performance and maintainability Example: "Optimize this database query function"
6. clean - Repo Janitor
Use when: Codebase needs cleanup What it does: Removes dead code, fixes formatting, updates dependencies Example: "Clean up unused imports and format this file"
7. synthesize - Systems Integration
Use when: Connecting multiple services or systems What it does: Helps integrate different components Example: "Connect this API to the payment gateway"
How to use prompts:
# List all prompts
curl http://localhost:8000/prompts
# Get specific prompt
curl http://localhost:8000/prompts/proceed
📚 Built-in MCP Resources
Codex CLI, Claude Desktop, and other MCP clients can now stream the core project manuals directly
from the server. Each resource is available under the resource://ultimate-mcp/... namespace:
| URI | What You Get |
|---|---|
resource://ultimate-mcp/readme | Project overview, feature list, and navigation links |
resource://ultimate-mcp/quick-start | Three-step launch checklist for the full stack |
resource://ultimate-mcp/agent-handbook | Operating guidelines targeted at agentic coding assistants |
resource://ultimate-mcp/ai-tools-setup | Codex CLI, Gemini CLI, and Amazon Q MCP configuration recipes |
resource://ultimate-mcp/executive-summary | High-level status brief and roadmap priorities for leadership |
resource://ultimate-mcp/architecture | Visual architecture walkthrough covering backend, frontend, and graph pieces |
CLI tip:
codex mcp resources list ultimate-mcp
codex mcp resources read ultimate-mcp resource://ultimate-mcp/readme
💡 Real-World Examples
Example 1: Building a REST API
Scenario: You're building a user management API and want to ensure quality.
Step 1 - Generate the code:
curl http://localhost:8000/generate_code \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"template": "from fastapi import FastAPI\n\napp = FastAPI()\n\n@app.{{ method }}(\"/{{ endpoint }}\")\ndef {{ function_name }}():\n return {{ response }}",
"context": {
"method": "get",
"endpoint": "users",
"function_name": "list_users",
"response": "{\"users\": []}"
}
}'
Step 2 - Check code quality:
curl http://localhost:8000/lint_code \
-d '{"code": "YOUR_GENERATED_CODE", "language": "python"}'
Step 3 - Test it:
curl http://localhost:8000/execute_code \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"code": "YOUR_GENERATED_CODE\nprint(list_users())", "language": "python"}'
Step 4 - Store in knowledge graph:
curl http://localhost:8000/graph_upsert \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"nodes": [{
"id": "user_api",
"labels": ["API", "Service"],
"properties": {"name": "User API", "endpoint": "/users"}
}]
}'
Example 2: Analyzing Your Microservices
Scenario: You have 10 microservices and want to understand their dependencies.
Step 1 - Store all services:
# Store each service (repeat for all services)
curl http://localhost:8000/graph_upsert \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"nodes": [
{"id": "frontend", "labels": ["Service"], "properties": {"name": "Frontend", "language": "typescript"}},
{"id": "auth", "labels": ["Service"], "properties": {"name": "Auth Service", "language": "python"}},
{"id": "api", "labels": ["Service"], "properties": {"name": "API Gateway", "language": "go"}}
],
"relationships": [
{"from": "frontend", "to": "api", "type": "CALLS"},
{"from": "api", "to": "auth", "type": "CALLS"}
]
}'
Step 2 - Find all dependencies:
curl http://localhost:8000/graph_query \
-d '{
"cypher": "MATCH (s1:Service)-[:CALLS]->(s2:Service) RETURN s1.name AS caller, s2.name AS called",
"parameters": {}
}'
Step 3 - Find critical services (most dependencies):
curl http://localhost:8000/graph_query \
-d '{
"cypher": "MATCH (s:Service)<-[:CALLS]-(caller) RETURN s.name, count(caller) AS dependents ORDER BY dependents DESC",
"parameters": {}
}'
Example 3: Learning Python with AI
Scenario: You're learning Python and want to practice with immediate feedback.
Step 1 - Write code:
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
print(fibonacci(10))
Step 2 - Check for issues:
curl http://localhost:8000/lint_code \
-d '{"code": "YOUR_CODE_HERE", "language": "python"}'
Step 3 - Run it safely:
curl http://localhost:8000/execute_code \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"code": "YOUR_CODE_HERE", "language": "python"}'
Step 4 - Add tests:
curl http://localhost:8000/run_tests \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"code": "YOUR_CODE_HERE\n\ndef test_fibonacci():\n assert fibonacci(0) == 0\n assert fibonacci(1) == 1\n assert fibonacci(10) == 55",
"language": "python"
}'
🌐 Accessing Your Services
Once deployed, you can access:
| Service | URL | Purpose |
|---|---|---|
| Web Interface | http://localhost:3000 | Visual dashboard for all tools |
| API Documentation | http://localhost:8000/docs | Interactive API testing (Swagger UI) |
| Health Check | http://localhost:8000/health | System status |
| Metrics | http://localhost:8000/metrics | Performance metrics |
| Neo4j Browser | http://localhost:7474 | Graph database interface |
| Neo4j Bolt | bolt://localhost:7687 | Direct database connection |
Finding Your Authentication Token
Your secure token is in the .env.deploy file:
# View your token
cat .env.deploy | grep AUTH_TOKEN
Copy the value after AUTH_TOKEN= and use it in your requests:
curl http://localhost:8000/execute_code \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-d '{"code": "print(\"Hello\")", "language": "python"}'
Neo4j Database Access
Username: neo4j
Password: Found in .env.deploy under NEO4J_PASSWORD
# View Neo4j password
cat .env.deploy | grep NEO4J_PASSWORD
🔧 Troubleshooting
Problem: "Port already in use"
Solution: Another service is using the same port.
# Find what's using port 8000
lsof -i :8000
# Stop the conflicting service or change ports in .env.deploy
# Edit these lines:
# FRONTEND_HTTP_PORT=3001 (instead of 3000)
# NEO4J_HTTP_PORT=7475 (instead of 7474)
Problem: "Cannot connect to Docker daemon"
Solution: Docker Desktop isn't running.
- Open Docker Desktop application
- Wait for it to fully start (whale icon in system tray)
- Try
./deploy.shagain
Problem: "Authentication failed"
Solution: Using wrong or expired token.
# Get fresh token
cat .env.deploy | grep AUTH_TOKEN
# Use it in your request
curl -H "Authorization: Bearer PASTE_TOKEN_HERE" ...
Problem: "Neo4j not healthy"
Solution: Database needs more time to start.
# Check Neo4j status
docker ps | grep neo4j
# Wait 30 seconds and check health
curl http://localhost:8000/health
Problem: "Code execution timeout"
Solution: Code is taking too long or has infinite loop.
- Default timeout is 30 seconds
- Check your code for infinite loops
- Optimize slow operations
🚀 Advanced Usage
Using with Claude Desktop
- Install Claude Desktop from Anthropic
- Configure MCP by editing
~/.config/Claude/claude_desktop_config.json:
{
"mcpServers": {
"ultimate-mcp": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch", "http://localhost:8000/mcp"],
"env": {
"AUTH_TOKEN": "YOUR_TOKEN_FROM_ENV_DEPLOY"
}
}
}
}
- Restart Claude Desktop
- Test it: Ask Claude "Can you lint this Python code for me?"
Deploying to Production
Option 1: Railway (Recommended)
# Install Railway CLI
npm install -g @railway/cli
# Login and deploy
railway login
railway init
railway up
Option 2: Docker Compose on VPS
# On your server
git clone https://github.com/Senpai-Sama7/Ultimate_MCP.git
cd Ultimate_MCP
./deploy.sh
# Configure firewall
sudo ufw allow 8000/tcp
sudo ufw allow 3000/tcp
Option 3: Kubernetes
# Convert docker-compose to k8s
kompose convert -f deployment/docker-compose.yml
# Apply to cluster
kubectl apply -f .
Custom Configuration
Edit .env.deploy to customize:
# Change ports
FRONTEND_HTTP_PORT=3000
NEO4J_HTTP_PORT=7474
NEO4J_BOLT_PORT=7687
# Security
AUTH_TOKEN=your-secure-token-here
NEO4J_PASSWORD=your-secure-password-here
# Rate limiting
RATE_LIMIT_RPS=10 # Requests per second
# CORS (for web apps)
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
Monitoring and Logs
View logs:
# All services
docker compose -f deployment/docker-compose.yml logs -f
# Specific service
docker logs deployment-backend-1 -f
docker logs ultimate_mcp_neo4j -f
Check metrics:
# Prometheus format
curl http://localhost:8000/metrics
# JSON format
curl http://localhost:8000/metrics | jq
Backup Neo4j Data
# Create backup
docker exec ultimate_mcp_neo4j neo4j-admin database dump neo4j --to-path=/backups
# Copy to host
docker cp ultimate_mcp_neo4j:/backups/neo4j.dump ./backup-$(date +%Y%m%d).dump
# Restore backup
docker exec ultimate_mcp_neo4j neo4j-admin database load neo4j --from-path=/backups
📚 Additional Resources
- Full API Documentation: http://localhost:8000/docs (when running)
- Neo4j Cypher Guide: https://neo4j.com/docs/cypher-manual/current/
- MCP Protocol Spec: https://modelcontextprotocol.io/
- FastAPI Docs: https://fastapi.tiangolo.com/
- Docker Guide: https://docs.docker.com/get-started/
🤝 Contributing
We welcome contributions! Here's how:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Run tests:
python scripts/smoke_test.py - Commit:
git commit -m "Add amazing feature" - Push:
git push origin feature/amazing-feature - Open a Pull Request
See AGENTS.md for detailed contributor guidelines.
📄 License
MIT License - see LICENSE file for details.
🆘 Getting Help
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Check
docs/folder for detailed guides
🎉 Quick Reference Card
Most Common Commands:
# Start everything
./deploy.sh
# Stop everything
docker compose -f deployment/docker-compose.yml down
# View logs
docker compose -f deployment/docker-compose.yml logs -f
# Check health
curl http://localhost:8000/health
# Get your token
cat .env.deploy | grep AUTH_TOKEN
# Lint code
curl http://localhost:8000/lint_code -d '{"code":"YOUR_CODE","language":"python"}'
# Execute code (needs token)
curl http://localhost:8000/execute_code -H "Authorization: Bearer TOKEN" -d '{"code":"print(42)","language":"python"}'
Default Ports:
- Frontend: 3000
- Backend: 8000
- Neo4j Browser: 7474
- Neo4j Bolt: 7687
Important Files:
.env.deploy- Your passwords and tokensdeployment/docker-compose.yml- Service configurationbackend/requirements.txt- Python dependencies
Made with ❤️ for the AI development community