Skip to main content
Glama

Ultimate MCP Coding Platform

README.mdβ€’23.6 kB
# πŸš€ 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. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.111.0-009688.svg)](https://fastapi.tiangolo.com) [![Neo4j](https://img.shields.io/badge/Neo4j-5.23-008CC1.svg)](https://neo4j.com) --- ## πŸ“‹ Table of Contents - [What Is This?](#-what-is-this) - [Quick Start (3 Steps)](#-quick-start-3-steps) - [What Can It Do?](#-what-can-it-do) - [All Available Tools](#-all-available-tools) - [Built-in AI Prompts](#-built-in-ai-prompts) - [Real-World Examples](#-real-world-examples) - [Accessing Your Services](#-accessing-your-services) - [Troubleshooting](#-troubleshooting) - [Advanced Usage](#-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](https://www.docker.com/products/docker-desktop)) - **Git** ([Download here](https://git-scm.com/downloads)) 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: ```bash git clone https://github.com/Senpai-Sama7/Ultimate_MCP.git cd Ultimate_MCP ``` ### Step 2: Start Everything ```bash ./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**: ```bash 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**: ```json { "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 found - `complexity`: How complex the code is (lower is better) - `linter_exit_code`: 0 means no errors found - `linter_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**: ```bash 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**: ```json { "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 = error - `stdout`: What the program printed - `stderr`: Any error messages - `duration_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**: ```bash 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**: ```json { "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 passed - `stdout`: 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**: ```bash 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**: ```json { "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**: ```bash 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**: ```json { "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**: ```bash 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**: ```json { "results": [ { "service": "Authentication Service", "database": "User Database", "timeout": 30 } ], "count": 1 } ``` **Common Query Examples**: 1. **Find all Python services**: ```cypher MATCH (s:Service {language: "python"}) RETURN s.name, s.version ``` 2. **Find services with high complexity**: ```cypher MATCH (s:Service) WHERE s.complexity > 10 RETURN s.name, s.complexity ORDER BY s.complexity DESC ``` 3. **Find connection chains**: ```cypher 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**: ```bash # 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**: ```bash 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**: ```bash 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**: ```bash curl http://localhost:8000/lint_code \ -d '{"code": "YOUR_GENERATED_CODE", "language": "python"}' ``` **Step 3 - Test it**: ```bash 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**: ```bash 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**: ```bash # 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**: ```bash 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): ```bash 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**: ```python def fibonacci(n): if n <= 1: return n return fibonacci(n-1) + fibonacci(n-2) print(fibonacci(10)) ``` **Step 2 - Check for issues**: ```bash curl http://localhost:8000/lint_code \ -d '{"code": "YOUR_CODE_HERE", "language": "python"}' ``` **Step 3 - Run it safely**: ```bash curl http://localhost:8000/execute_code \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"code": "YOUR_CODE_HERE", "language": "python"}' ``` **Step 4 - Add tests**: ```bash 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: ```bash # View your token cat .env.deploy | grep AUTH_TOKEN ``` Copy the value after `AUTH_TOKEN=` and use it in your requests: ```bash 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` ```bash # View Neo4j password cat .env.deploy | grep NEO4J_PASSWORD ``` --- ## πŸ”§ Troubleshooting ### Problem: "Port already in use" **Solution**: Another service is using the same port. ```bash # 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. 1. Open Docker Desktop application 2. Wait for it to fully start (whale icon in system tray) 3. Try `./deploy.sh` again ### Problem: "Authentication failed" **Solution**: Using wrong or expired token. ```bash # 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. ```bash # 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 1. **Install Claude Desktop** from Anthropic 2. **Configure MCP** by editing `~/.config/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "ultimate-mcp": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch", "http://localhost:8000/mcp"], "env": { "AUTH_TOKEN": "YOUR_TOKEN_FROM_ENV_DEPLOY" } } } } ``` 3. **Restart Claude Desktop** 4. **Test it**: Ask Claude "Can you lint this Python code for me?" ### Deploying to Production **Option 1: Railway** (Recommended) ```bash # Install Railway CLI npm install -g @railway/cli # Login and deploy railway login railway init railway up ``` **Option 2: Docker Compose on VPS** ```bash # 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** ```bash # 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: ```bash # 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**: ```bash # 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**: ```bash # Prometheus format curl http://localhost:8000/metrics # JSON format curl http://localhost:8000/metrics | jq ``` ### Backup Neo4j Data ```bash # 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: 1. **Fork the repository** 2. **Create a feature branch**: `git checkout -b feature/amazing-feature` 3. **Make your changes** 4. **Run tests**: `python scripts/smoke_test.py` 5. **Commit**: `git commit -m "Add amazing feature"` 6. **Push**: `git push origin feature/amazing-feature` 7. **Open a Pull Request** See `AGENTS.md` for detailed contributor guidelines. --- ## πŸ“„ License MIT License - see [LICENSE](LICENSE) file for details. --- ## πŸ†˜ Getting Help - **Issues**: [GitHub Issues](https://github.com/Senpai-Sama7/Ultimate_MCP/issues) - **Discussions**: [GitHub Discussions](https://github.com/Senpai-Sama7/Ultimate_MCP/discussions) - **Documentation**: Check `docs/` folder for detailed guides --- ## πŸŽ‰ Quick Reference Card **Most Common Commands**: ```bash # 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 tokens - `deployment/docker-compose.yml` - Service configuration - `backend/requirements.txt` - Python dependencies --- **Made with ❀️ for the AI development community**

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Senpai-Sama7/Ultimate_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server