How do I use Gravitas-Core-MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gravitas-Core-MCP Start a new task to refactor the authentication module" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Gravitas-Core-MCP

by ahmed-coding

Overview Schema Source Related Servers Discussions Admin

Python

Local

Gravitas-Core-MCP

Version: 0.1.0
Role: Core System Blueprint / Autonomous AI Control Plane
Target Platforms: VS Code (Cline / Claude Dev), Cursor, Windsurf, Claude Desktop

Production-grade, autonomous Model Context Protocol (MCP) server that elevates AI models from stateless code generators into persistent, self-verifying software engineers.

Features

Persistent memory — SQLite-backed task ledger, context snapshots, canonical state, failure memory, tool usage patterns
Cognitive control — Deterministic task state machine (PLANNING → CODING → EXECUTING → VERIFYING → COMPLETED / FAILED_RETRY / ROLLBACK), retry policies, rollback on repeated failures
Terminal engine — Shell execution with timeout, cwd isolation, allowlist/denylist, background process management
Browser engine — Playwright-based navigation, DOM snapshot, screenshots, console error streaming
Project intelligence — Recursive structure analysis with noise filtering (.git, node_modules, build artifacts)
Model handover — Auto-generated Model Resume Package (goal, task, constraints, failures, safe/do-not-touch files) for model swap, editor restart, or crash recovery

Related MCP server: trw-mcp

Requirements

Python 3.10+
UV (Astral) for install/run
Browser: Uses existing Chrome or Edge on your machine when available — no playwright install required. If you have neither, run playwright install chromium once.

Installation

No local install needed — run directly from GitHub (see Use it from GitHub below):

uvx run git+https://github.com/ahmed-coding/Gravitas-Core.git

Or install from PyPI:

# Install and run via uvx (no global install)
uvx Gravitas-Core-MCP

Or install into a project:

uv add Gravitas-Core-MCP
# Then run: uv run Gravitas-Core-MCP

Browser tools: If you already have Chrome or Edge installed, nothing else is needed. Otherwise, run once: uv run playwright install chromium.

Use it from GitHub (direct configuration)

Run the server directly from this repository with no local installation — UV fetches the repo and runs it. Repository: ahmed-coding/Gravitas-Core.

The repo includes a GitHub Action (.github/workflows/ci.yml) that runs tests and verifies the server starts; you can see it in the Actions tab after push.

Run from GitHub with uvx

uvx run git+https://github.com/ahmed-coding/Gravitas-Core.git

Or pin a branch/tag:

uvx run "git+https://github.com/ahmed-coding/Gravitas-Core.git@main"
uvx run "git+https://github.com/ahmed-coding/Gravitas-Core.git@v1.1.0"

MCP client config (GitHub direct)

Requires UV to be installed and uvx in your PATH. If you see spawn uvx ENOENT, use the localhost config below instead (no uv/uvx needed).

Cursor — e.g. ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ahmed-coding/Gravitas-Core.git",
        "Gravitas-Core-MCP"
      ]
    }
  }
}

With a specific ref (branch or tag):

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ahmed-coding/Gravitas-Core.git@main",
         "Gravitas-Core-MCP"
      ]
    }
  }
}

Cloned repo (run from local path):

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "/path/to/Gravitas-Core/.venv/bin/python",
      "args": ["-m", "gravitas_mcp.server"]
    }
  }
}

(Create the venv first: cd /path/to/Gravitas-Core && uv venv && uv sync, then use .venv/bin/python in command.)

Run from localhost (local clone)

Use the server from a clone on your machine so you can develop and test without GitHub.

1. Clone and install (one time)

git clone https://github.com/ahmed-coding/Gravitas-Core.git
cd Gravitas-Core
uv sync

(If you don’t have UV: pip install uv or use python -m venv .venv && .venv/bin/pip install -e . and then use .venv/bin/python in the configs below.)

2. Run the server in a terminal (optional)

cd /path/to/Gravitas-Core
uv run python -m gravitas_mcp.server

OR with uvicorn

cd /path/to/Gravitas-Core
uv run python -m  gravitas_mcp.mcp_webapp

The server uses stdio; your MCP client (Cursor, etc.) will start it automatically when configured.

3. MCP config for localhost

Option A — Use this repo as the Cursor project (recommended)
Open the Gravitas-Core folder in Cursor. The project already includes .cursor/mcp.json so the gravitas MCP server runs from your local clone (no GitHub needed).

Option B — Use from any project (user-level config)
Copy this into ~/.cursor/mcp.json and replace YOUR_PATH with the full path to your clone (e.g. /home/ahmed/Desktop/Gravitas-MCP-Core or C:\Users\You\Gravitas-Core):

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "YOUR_PATH/.venv/bin/python",
      "args": ["-m", "gravitas_mcp.server"]
    }
  }
}

On Windows use YOUR_PATH\\.venv\\Scripts\\python.exe and "args": ["-m", "gravitas_mcp.server"].

Option C — Use uv with project path (no venv path)
If Cursor runs the command with a fixed cwd, you can use:

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/Gravitas-Core", "python", "-m", "gravitas_mcp.server"]
    }
  }
}

Replace /path/to/Gravitas-Core with your actual clone path.

Troubleshooting

Error	Fix
`spawn uvx ENOENT`	Cursor can’t find `uvx`. Either install UV and ensure `uvx` is in your PATH, or use localhost: open this repo in Cursor (so it uses the project’s `.cursor/mcp.json`) and run `python3 -m venv .venv && .venv/bin/pip install -e .` in the project folder. The project config uses the venv’s Python, so no uv needed.
Server not starting	Ensure `.venv` exists: from the project root run `python3 -m venv .venv` then `.venv/bin/pip install -e .` (or `uv sync` if you have uv).

MCP client configuration

Blackbox / Cursor (user-level config)

Add to ~/.config/Code/User/globalStorage/blackboxapp.blackboxagent/settings/blackbox_mcp_settings.json:

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ahmed-coding/Gravitas-Core.git",
        "Gravitas-Core-MCP"
      ]
    }
  }
}

With a specific ref (branch or tag):

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ahmed-coding/Gravitas-Core.git@v1.1.0",
        "Gravitas-Core-MCP"
      ]
    }
  }
}

From local clone:

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "/path/to/Gravitas-Core/.venv/bin/python",
      "args": ["-m", "gravitas_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/Gravitas-Core"
      },
      "type": "stdio"
    }
  }
}

Cursor (project-level config)

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "gravitas-mcp": {
      "command": "uvx",
      "args": ["Gravitas-Core-MCP"]
    }
  }
}

Repository structure

Gravitas-Core-MCP/
├── gravitas_mcp/
│   ├── __init__.py
│   ├── server.py      # MCP entrypoint, tool wiring
│   ├── memory.py      # SQLite persistence, task ledger, state APIs
│   ├── controller.py  # State machine, retry/rollback
│   ├── terminal.py    # Subprocess execution, allowlist/denylist
│   ├── browser.py     # Playwright automation
│   └── project_intel.py # Structure analysis, noise filtering
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

Tool contract

All tools return deterministic JSON:

{
  "status": "success | failure",
  "observations": {},
  "errors": [],
  "next_recommended_action": ""
}

Mandatory tools (PRD)

Tool	Description
`get_last_state`	Last known state (snapshot + active task)
`get_canonical_state`	Last verified immutable state (rollback/recovery)
`record_failure`	Record failed strategy/command
`resume_task`	Load task context for resumption
`controller_create_task`	Create task, state PLANNING
`controller_transition`	Move task to PLANNING/CODING/EXECUTING/VERIFYING/FAILED_RETRY/ROLLBACK/COMPLETED
`controller_record_step_failure`	Record step failure (may trigger rollback)
`terminal_execute`	Run shell command with timeout
`browser_navigate` / `browser_snapshot` / `browser_screenshot`	UI verification
`project_get_map`	Project structure with noise filtering
`get_model_resume_package`	Model handover package

Brain database

State is stored in .gravitas_brain.db in the project root (or cwd). Optional: add .gravitas_brain.db to .gitignore if you do not want to commit it.

License

MIT — Local-first, user-sovereign, safe by default.

Available Tools

21 tools

browser_get_console_errorsA

Return collected JS console errors since last navigate.

Inputs: no named parameters.

browser_hoverB

Hover over an element by CSS selector.

Inputs: selector (required).

browser_navigateC

Navigate to URL (Playwright).

Inputs: url (required), wait_until.

browser_screenshotB

Take screenshot; optional path to save file.

Inputs: path.

browser_snapshotB

Capture DOM accessibility tree and console errors.

Inputs: no named parameters.

controller_create_taskC

Create a new task and set state to PLANNING.

Inputs: goal (required), task_id.

controller_get_stateC

Return current task state and policy info.

Inputs: task_id (required).

controller_record_step_failureB

Record a step failure; may trigger FAILED_RETRY or ROLLBACK.

Inputs: reason (required), task_id (required).

controller_transitionC

Transition task to a new state (PLANNING, CODING, EXECUTING, VERIFYING, FAILED_RETRY, ROLLBACK, COMPLETED).

Inputs: task_id (required), new_state (required).

get_canonical_stateA

Return the last verified, immutable working state for rollback/recovery.

Inputs: no named parameters.

get_last_stateA

Return the last known state (most recent snapshot + active task). Authoritative memory.

Inputs: no named parameters.

get_model_resume_packageB

Generate Model Resume Package for model swap/editor restart/crash recovery: goal, task, constraints, failures, safe/do-not-touch files.

Inputs: task_id.

memory_save_snapshotC

Save a context snapshot for current task (internal use).

Inputs: task_id (required), project_map (required), snapshot_id (required), do_not_touch (required), +1 more.

memory_set_canonicalC

Set the canonical (immutable) state to a snapshot (after verification).

Inputs: snapshot_id (required).

project_get_mapC

Recursive project structure with noise filtering.

Inputs: max_depth, max_entries, project_root.

record_failureC

Record a failed strategy/command to prevent repetition.

Inputs: reason (required), context (required).

resume_taskB

Load task and its context for resumption (model handover/restart).

Inputs: task_id (required).

terminal_executeB

Execute a shell command with timeout and cwd. Returns stdout, stderr, exit_code.

Inputs: command (required), cwd, timeout_sec.

terminal_list_backgroundA

List active background process ids.

Inputs: no named parameters.

terminal_start_backgroundC

Start a background process; use process_id to stop later.

Inputs: command (required), process_id (required), cwd.

terminal_stop_backgroundC

Terminate a background process by process_id.

Inputs: process_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-07-05 19:50 across 21 tools

Disambiguation4/5

Most tools have distinct purposes within their domains (browser, controller, terminal, state). However, `record_failure` and `controller_record_step_failure` overlap in concept, potentially causing confusion. The state retrieval tools (`get_canonical_state`, `get_last_state`, `get_model_resume_package`) are distinct but require careful reading of descriptions.

Naming Consistency4/5

Naming is consistent within domains: browser_*, controller_*, terminal_*. However, across domains, there is inconsistency: some tools use verb_noun order (e.g., `browser_get_console_errors`) while others use noun_verb (e.g., `get_canonical_state`). The pattern is mostly predictable but not uniform.

Tool Count4/5

21 tools is on the higher side but still reasonable for the server's scope, which includes browser automation, task management, terminal execution, and state persistence. Each tool has a clear role, and no tool feels redundant or out of place.

Completeness4/5

The tool set covers the core workflows: browser interaction, task lifecycle, terminal commands, and state recovery. Minor gaps exist (e.g., no file read/edit tool), but the server is focused on orchestration rather than full development, so these omissions are acceptable.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
https://api.microservices.sh/mcp
pronto-streamA
io.github.nmxmxh
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Agent Orchestration Cryptocurrency Finance
151
https://pronto.stream/mcp
hithereiamaliff-mcp-nextcloud
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
239
https://server.smithery.ai/@hithereiamaliff/mcp-nextcloud/mcp
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
https://api.anotherai.dev/mcp

Related MCP Servers

Claude Team MCP
Agent Orchestration Coding Agents Autonomous Agents
Lakshan12367
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that turns multiple AI coding agents into a coordinated team that chats, debates, remembers, audits security, and works in parallel on the same project.
Updated 5 months ago (2026-06-04 01:55 UTC)
MIT
trw-mcp
Knowledge & Memory Developer Tools Coding Agents
wallter
A
license
B
quality
B
maintenance
MCP server providing persistent engineering memory and spec-driven development workflows for AI coding agents, preserving learnings across sessions.
Updated 9 days ago (2026-11-02 23:41 UTC)
41
Business Source 1.1
myBrAIn
Knowledge & Memory Developer Tools
lilium360
A
license
Not graded
quality
D
maintenance
MCP server that provides persistent memory and contextual awareness to language models, enabling project onboarding, recall of architectural rules, and code consistency across sessions.
Updated 9 months ago (2026-02-17 08:39 UTC)
32
MIT
A-Modular-Kingdom
RAG Systems Knowledge & Memory Agent Orchestration
MasihMoafi
A
license
Not graded
quality
B
maintenance
Production-ready MCP server providing RAG, hierarchical memory, and 8+ tools for AI agents via the Model Context Protocol.
Updated 4 days ago (2026-11-08 18:27 UTC)
51
Apache 2.0

Gravitas-Core-MCP

Features

Requirements

Installation

Use it from GitHub (direct configuration)

Run from GitHub with uvx

MCP client config (GitHub direct)

Run from localhost (local clone)

1. Clone and install (one time)

2. Run the server in a terminal (optional)

3. MCP config for localhost

Troubleshooting

MCP client configuration

Blackbox / Cursor (user-level config)

Cursor (project-level config)

Repository structure

Tool contract

Mandatory tools (PRD)

Brain database

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Claude Team MCP

trw-mcp

myBrAIn

A-Modular-Kingdom