Quick Start

This guide shows the shortest correct path to run the project today.

Current validated project version: 0.2.2.

1. Prerequisites

Required:

Python 3.10+
uv
Git

Required only for the default managed Neo4j mode:

Docker running locally

Install uv if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install

git clone <repository-url>
cd codebase_state_manager_mcp
./scripts/setup.sh

Alternative:

uv sync --extra dev

3. Start the server locally

Recommended launcher:

python run_mcp_server.py

Alternative:

python -m src.mcp_server

Legacy compatibility alias still exists, but is deprecated:

python init_neo4j_and_mcp.py

4. Minimal MCP client configuration

Default: managed Neo4j

{
  "mcp": {
    "codebase-state-manager": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        "/absolute/path/to/codebase_state_manager_mcp",
        "python",
        "run_mcp_server.py"
      ],
      "enabled": true
    }
  }
}

This mode does not require:

NEO4J_URI
NEO4J_USER
NEO4J_PASSWORD

Note: `uv --project` vs managed codebase

In editor MCP configs, uv run --project ... selects the Python environment used to run this MCP server. It is not the codebase being managed.

If you want to manage a different codebase directory (for example, the repo you are actively editing), set:

{
  "env": {
    "MANAGED_PROJECT_PATH": "/absolute/path/to/your/codebase"
  }
}

5. Optional runtime modes

SQLite

{
  "env": {
    "DB_MODE": "sqlite"
  }
}

External Neo4j

{
  "env": {
    "DB_MODE": "neo4j",
    "NEO4J_BOOTSTRAP_MODE": "external",
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USER": "neo4j",
    "NEO4J_PASSWORD": "your_password"
  }
}

6. Verify the setup

Managed Neo4j mode

docker ps | grep codebase-state-manager-neo4j
ls ./.data/neo4j/

Full validation

python -m pytest tests -q
uv run mypy src/
uv run bandit -r src/ -q

Latest validation result on the current codebase:

568 passed
mypy passing
bandit clean

7. Main exposed MCP tools

genesis_tool
new_state_transition_tool
get_current_state_info_tool
get_current_state_compact_context_tool
get_rewarded_transitions_tool
set_transition_reward_tool
fix_volume_path_tool
check_consistency_tool
repair_consistency_tool

For the full list and exact semantics, see README.md and ARCHITECTURE.md.

FilesExpand file tree

QUICKSTART.md

Latest commit

History