ultimate-mcp 0.1.1

Production-ready Model Context Protocol (MCP) stack

Ultimate MCP Platform

Production-ready Model Context Protocol (MCP) stack that bundles a FastAPI backend, Neo4j graph store, and React front-end for linting, sandboxed execution, test orchestration, graph persistence, and code generation.

Highlights

• 🔐 Security-first – Bearer auth, SlowAPI rate limits, sandboxed execution, configurable secrets.
• 🧪 Rich tooling – Lint code, run pytest suites, execute snippets with resource limits, generate code from templates.
• 🧠 Graph-native storage – Persist lint/test/execute results and custom nodes to Neo4j; query them with Cypher.
• 📊 Observability – /health and /metrics endpoints, structured logging, reusable smoke tests.
• 🛠️ MCP compatible – Backed by FastMCP so Claude or any MCP client can consume the same tools.

---

Quickstart

Option 0 – Published CLI (fastest)

npx @ultimate-mcp/cli init my-ultimate-mcp
cd my-ultimate-mcp
npx @ultimate-mcp/cli start

Latest CLI: v0.1.3 adds port override flags and Neo4j password validation so you can avoid collisions during local testing.

The CLI scaffolds a deployment directory, generates secrets, and launches Docker Compose. For offline or air-gapped usage you can still run it from this repo (cd Ultimate_MCP/cli && npm install && node bin/ultimate-mcp.js …). Override backend/frontend images by editing UMCP_BACKEND_IMAGE / UMCP_FRONTEND_IMAGE in the generated .env file if you host custom images.

Common flags

• --backend-port, --frontend-port, --neo4j-http-port, --neo4j-bolt-port customise the host ports and are written to .env so follow-up start, stop, and upgrade commands respect the overrides.
• --neo4j-password lets you supply your own credential (must be ≥12 chars with letters and numbers) if you want to reuse an existing secret manager.
• --local-images builds the backend/frontend from source instead of pulling container images.

Heads-up: The published defaults reference ghcr.io/ultimate-mcp/* images. Authenticate first (docker login ghcr.io) or run npx @ultimate-mcp/cli init my-ultimate-mcp --local-images from a repository checkout and copy the backend/ and frontend/ directories next to the generated deployment before calling start.

Option 1 – Deploy script (from this repo)

git clone https://github.com/Senpai-Sama7/Ultimate_MCP.git
cd Ultimate_MCP
./deploy.sh

• Frontend UI: http://localhost:3000
• Backend API docs: http://localhost:8000/docs
• Health check: http://localhost:8000/health
• Neo4j Browser: http://localhost:7474 (or the ports in .env.deploy)

Tear down with:

docker compose --project-name ultimate-mcp --env-file .env.deploy -f deployment/docker-compose.yml down

Port conflicts? After the first run, edit .env.deploy and change FRONTEND_HTTP_PORT, NEO4J_HTTP_PORT, or NEO4J_BOLT_PORT before re-running ./deploy.sh. The backend exposes port 8000 by default; the other ports are configurable via the env file.

Option 2 – Manual developer setup

# Clone and install backend
git clone https://github.com/Senpai-Sama7/Ultimate_MCP.git
cd Ultimate_MCP/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_enhanced.txt  # use Python ≤3.12 or skip if asyncpg build fails

# Start Neo4j
export NEO4J_PASSWORD=$(openssl rand -hex 16)
docker run -d --name ultimate-mcp-dev-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e "NEO4J_AUTH=neo4j/${NEO4J_PASSWORD}" \
  neo4j:5.23.0

# Run backend (default token change recommended)
export AUTH_TOKEN=$(openssl rand -hex 24)
uvicorn mcp_server.enhanced_server:app --host 0.0.0.0 --port 8000 --reload

# In another terminal – frontend
cd ../frontend
npm install
npm run dev

---

Full MCP capability demo

With the stack running (via any option above) and requests installed, execute the end-to-end demo:

python demo/full_demo.py --base-url http://localhost:8000 \
  --auth-token $(grep '^AUTH_TOKEN=' .env.deploy | cut -d= -f2-)

The script sequentially:

1. Lints a Python snippet.
2. Executes code in the sandbox.
3. Runs pytest.
4. Generates code from a template.
5. Upserts a pair of service nodes + relationship in Neo4j.
6. Queries the graph and prints aggregate metrics.

Use it whenever you need a “show me it works” proof for MCP clients or demos.

---

Built-in prompt library

curl http://localhost:8000/prompts | jq
curl http://localhost:8000/prompts/proceed | jq '.body'

Use the MCP tools list_prompts and get_prompt to retrieve the same definitions from an MCP client.

---

Set MCP_BASE_URL to point agent clients (e.g. export MCP_BASE_URL=https://mcp.example.com). AgentDiscovery and the demo script default to this value.

Core API recipes

Replace $AUTH_TOKEN with the bearer token from .env.deploy or your own secret.

Lint code

curl --json '{"code":"def add(a, b):\n    return a + b\n","language":"python"}' \
  http://localhost:8000/lint_code

Execute code (auth required)

curl --json '{"code":"print(6 * 7)","language":"python"}' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  http://localhost:8000/execute_code

Run pytest (auth required)

curl --json '{"code":"def test_math():\n    assert 1 + 1 == 2\n","language":"python"}' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  http://localhost:8000/run_tests

Generate code (auth required)

curl --json '{"template":"def {{ name }}():\n    return {{ value }}","context":{"name":"answer","value":42}}' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  http://localhost:8000/generate_code

Graph upsert & query (auth required for upsert)

curl --json '{"nodes":[{"key":"service_frontend","labels":["Service"],"properties":{"name":"frontend","language":"typescript"}},{"key":"service_backend","labels":["Service"],"properties":{"name":"backend","language":"python"}}],"relationships":[{"start":"service_frontend","end":"service_backend","type":"CALLS","properties":{"latency_ms":120}}]}' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  http://localhost:8000/graph_upsert

curl --json '{"cypher":"MATCH (s:Service) RETURN s.name AS name, s.language AS language","parameters":{}}' \
  http://localhost:8000/graph_query

Monitoring

curl http://localhost:8000/health
curl http://localhost:8000/metrics | jq

---

Neo4j

• Browser: http://localhost:7474 (credentials neo4j / value in NEO4J_PASSWORD).
• All lint/test/execute results and custom graph nodes are persisted automatically.

---

Contributing & further docs

• AGENTS.md – contributor workflow and PR expectations.
• docs/RELEASE.md – tagging & publishing instructions.
• docs/SECURITY_BACKLOG.md – tracked hardening follow-ups.

Pull requests welcome! Use feature branches off main and run the smoke tests (python scripts/smoke_test.py, demo/full_demo.py) before opening a PR.