Gravitas-Core

Gravitas核心MCP

版本： 0.1.0\ 角色： 核心系统蓝图/自主AI控制平面\ 目标平台： VS代码（Cline/Claude Dev）、光标、风帆、克劳德桌面

生产级，自主 模型上下文协议（MCP）服务器 将人工智能模型从无状态代码生成器提升到 坚持不懈、自我验证的软件工程师.

特性

• 持久内存 --SQLite支持的任务分类账、上下文快照、规范状态、故障记忆、工具使用模式
• 认知控制 --确定性任务状态机（规划→ 编程→ 执行→ 验证→ 已完成/FAILED_RETRY/ROLLBACK），重试策略，重复失败时回滚
• 终端发动机 --带超时的Shell执行、cwd隔离、allowlist/denylist、后台进程管理
• 浏览器引擎 --基于剧作家的导航、DOM快照、屏幕截图、控制台错误流
• 项目智能 --带噪声滤波的递归结构分析(.git, node_modules，构建工件）
• 模型移交 --自动生成的模型恢复包（目标、任务、约束、失败、安全/不可触碰文件），用于模型交换、编辑器重启或崩溃恢复

需求

• Python 3.10+
• 紫外线 （Astral）用于安装/运行
• 浏览器： 用途 现有的Chrome或Edge浏览器 在您的机器上可用时-- 不 playwright install 必需的如果你两者都没有，就跑 playwright install chromium 一次。

安装

无需本地安装 --直接从GitHub运行（请参阅 在......下面

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

或者从PyPI安装：

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

或者安装到项目中：

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

浏览器工具： 如果您已经安装了Chrome或Edge浏览器，则不需要其他任何东西。否则，运行一次： uv run playwright install chromium.

从GitHub使用（直接配置）

运行服务器 直接来自此存储库 随着 无本地安装 --UV获取仓库并运行它。仓库： ahmed编码/重力核心.

回购包括 GitHub行动 (.github/workflows/ci.yml)运行测试并验证服务器是否启动；推送后，您可以在“操作”选项卡中看到它。

使用uvx从GitHub运行

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

或者固定一个分支/标签：

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客户端配置（GitHub直接）

需要 紫外线 待安装和 uvx 在你的路径。 如果你看到 spawn uvx ENOENT，使用 本地主机配置 取而代之的是（不需要紫外线/紫外线）。

光标 --例如。 ~/.cursor/mcp.json 或 .cursor/mcp.json:

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

使用特定的ref（分支或标签）：

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

克隆的仓库（从本地路径运行）：

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

*（先创建venv： cd /path/to/Gravitas-Core && uv venv && uv sync，然后使用 .venv/bin/python 在 command.)*

从本地主机（本地克隆）运行

使用机器上克隆的服务器，这样你就可以在没有GitHub的情况下进行开发和测试。

1.克隆并安装（一次）

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

*（如果你没有 紫外线: pip install uv 或使用 python -m venv .venv && .venv/bin/pip install -e . 然后使用 .venv/bin/python 在下面的配置中。)*

2.在终端中运行服务器（可选）

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

或与玉米

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

服务器使用stdio；配置后，您的MCP客户端（游标等）将自动启动它。

3.本地主机的MCP配置

选项A——将此仓库用作Cursor项目（推荐）\ 打开 Gravitas-Core Cursor中的文件夹。该项目已经包括 .cursor/mcp.json 所以 庄重 MCP服务器从本地克隆运行（不需要GitHub）。

选项B——从任何项目中使用（用户级配置）\ 将此复制到 ~/.cursor/mcp.json 并替换 YOUR_PATH 带有克隆的完整路径（例如。 /home/ahmed/Desktop/Gravitas-MCP-Core 或 C:\Users\You\Gravitas-Core):

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

关于Windows的使用 YOUR_PATH\\.venv\\Scripts\\python.exe 和 "args": ["-m", "gravitas_mcp.server"].

选项C——使用 uv 具有项目路径（无venv路径）\ 如果Cursor使用固定的cwd运行命令，则可以使用：

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

替换 /path/to/Gravitas-Core 使用您的实际克隆路径。

故障排除

MCP客户端配置

黑匣子/光标（用户级配置）

增添 ~/.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"
      ]
    }
  }
}

使用特定的ref（分支或标签）：

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

从本地克隆：

{
  "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/mcp.json 或 .vscode/mcp.json:

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

存储库结构

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

工具合同

所有工具都返回确定性JSON：

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

强制性工具（PRD）

大脑数据库

状态存储在 .gravitas_brain.db 在项目根（或cwd）中。可选：添加 .gravitas_brain.db 到 .gitignore 如果你不想承诺。

许可证

MIT——本地优先，用户主权，默认安全。