Skip to content

SETUP.md

Latest commit

 

History

History
455 lines (342 loc) · 10.3 KB

SETUP.md

File metadata and controls

455 lines (342 loc) · 10.3 KB
Raw

Setup Guide

This document describes the current installation and configuration paths for version 0.2.2 of the project.

It replaces older exploratory setup notes and reflects the repository as it exists now.

1. Supported Operating Modes

The server supports three runtime modes.

Managed Neo4j (default)

Use this when Docker is available and you want the server to manage persistence automatically.

Behavior:

  • starts a project-scoped Neo4j container automatically;
  • persists data in ./.data/neo4j/;
  • reuses the same database on the next session in the same project;
  • does not require Neo4j credentials in the MCP client configuration.

External Neo4j

Use this when you already have a Neo4j service you want to control yourself.

SQLite

Use this when you want the simplest local setup and do not want Neo4j at all.

2. Prerequisites

Required:

  • Python 3.10+
  • uv
  • Git

Required only for managed Neo4j:

  • Docker daemon available and running

Optional:

  • Neo4j server, if you choose external Neo4j mode

Install uv if necessary:

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

3. Clone and Install

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

The setup script:

  • creates .venv/ with uv;
  • installs the package in editable mode;
  • installs dev dependencies by default.

Alternative direct install:

uv sync --extra dev

Activate the virtual environment if desired:

source .venv/bin/activate

4. Start the Server

Recommended launcher

python run_mcp_server.py

Alternative module entrypoint

python -m src.mcp_server

Deprecated compatibility alias

python init_neo4j_and_mcp.py

The alias still works, but the canonical launcher is now run_mcp_server.py.

5. MCP Client Configuration

5.1 Minimal configuration for 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
    }
  }
}

Nothing else is required for Neo4j in this mode.

5.1.1 Important: uv --project is the server environment, not the managed codebase

The --project flag passed to uv run controls which Python project/environment is used to resolve and install dependencies for the MCP server process.

It is not the codebase being managed.

  • Use --project /absolute/path/to/codebase_state_manager_mcp so the server runs with its own dependencies installed.
  • Configure the managed codebase explicitly via MANAGED_PROJECT_PATH (below), or by starting the server with the managed codebase as the current working directory.

5.2 SQLite mode

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

5.3 External Neo4j mode

{
  "mcp": {
    "codebase-state-manager": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        "/absolute/path/to/codebase_state_manager_mcp",
        "python",
        "run_mcp_server.py"
      ],
      "environment": {
        "DB_MODE": "neo4j",
        "NEO4J_BOOTSTRAP_MODE": "external",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      },
      "enabled": true
    }
  }
}

5.4 EVM mode (PoC)

EVM mode anchors state hashes on-chain and serves reads from a local SQLite mirror. Status: proof of concept.

Prerequisites beyond §2:

  • Foundry (forge + anvil) for the local devnet and contract deploy
  • kubo (IPFS) running locally (ipfs daemon, API on 127.0.0.1:5001)
  • Deployed CodebaseStateRegistry contract (contracts/src/CodebaseStateRegistry.sol)

Local devnet flow (Anvil, zero cost):

anvil                                                          # terminal 1
ipfs daemon                                                    # terminal 2
cd contracts && forge create \
  --rpc-url http://127.0.0.1:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --broadcast \
  src/CodebaseStateRegistry.sol:CodebaseStateRegistry          # note the deployed address
{
  "mcp": {
    "codebase-state-manager": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        "/absolute/path/to/codebase_state_manager_mcp",
        "python",
        "run_mcp_server.py"
      ],
      "environment": {
        "DB_MODE": "evm",
        "EVM_RPC_URL": "http://127.0.0.1:8545",
        "EVM_CHAIN_ID": "31337",
        "EVM_CONTRACT_ADDRESS": "0x<deployed-address>",
        "EVM_PRIVATE_KEY": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
        "EVM_IPFS_API_URL": "http://127.0.0.1:5001",
        "EVM_MIRROR_PATH": "./data/evm_mirror.db"
      },
      "enabled": true
    }
  }
}

Notes:

  • DB_MODE=evm fails fast on startup if the chain or contract is unreachable — there is no silent fallback to another backend.
  • The private key above is the Anvil well-known dev key #0 (public, local-only). Never use it with real funds.
  • All EVM tests run against a local Anvil instance. A one-time live Base Sepolia run that closed AC-11-OPT on 2026-07-21 is preserved at docs/measurements/archive/sepolia_2026-07/ for reference only; the live-testnet code path is no longer maintained.

6. Environment Variables

The application reads .env automatically when present.

Common

DB_MODE=neo4j
LOG_LEVEL=INFO
RATE_LIMIT_ENABLED=true
AUDIT_ENABLED=true
VOLUME_PATH=/opt/codebase-state-manager/volumes/<current-project-dir-name>
SQLITE_PATH=./data/state_manager.db

If VOLUME_PATH is omitted, the server automatically falls back to /opt/codebase-state-manager/volumes/<current-project-dir-name> so the managed snapshot stays outside the project tree.

Managed codebase selection

The server needs to know which codebase directory it is managing. It resolves the managed project path in this order:

  1. MANAGED_PROJECT_PATH (environment variable)
  2. persisted metadata in the repository backend (when available)
  3. tool-provided project path (for tool calls that accept it)
  4. the service's current in-memory project path

To force the managed project to be a specific directory (recommended for editor integrations), set:

MANAGED_PROJECT_PATH=/absolute/path/to/your/codebase

Important: in managed Neo4j mode the same MANAGED_PROJECT_PATH anchors the project-scoped Neo4j container identity (container name, data volumes, and runtime ports). It must stay stable across launches; otherwise the server starts a new Neo4j instance per run and orphaned containers accumulate. When unset, the bootstrap falls back to the process working directory at startup.

Managed Neo4j

NEO4J_BOOTSTRAP_MODE=auto
NEO4J_AUTO_IMAGE=neo4j:5.24
NEO4J_AUTO_HOME=./.data/neo4j
NEO4J_CONNECTION_TIMEOUT=90

External Neo4j

NEO4J_BOOTSTRAP_MODE=external
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

EVM (PoC)

DB_MODE=evm
EVM_RPC_URL=http://127.0.0.1:8545
EVM_CHAIN_ID=31337
EVM_CONTRACT_ADDRESS=0x<deployed-address>
EVM_PRIVATE_KEY=0x<signing-key>          # Anvil dev key #0 for local; never a real-funds key
EVM_IPFS_API_URL=http://127.0.0.1:5001
EVM_MIRROR_PATH=./data/evm_mirror.db

Defaults target the local Anvil devnet, so DB_MODE=evm works with zero configuration once Anvil, kubo, and the contract deploy exist. See §5.4.

7. Verification

Managed Neo4j verification

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

General validation

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

Current validation status on the repository:

  • tests: 568 passed
  • mypy: pass
  • bandit: clean

8. Development Helpers

Development runner

./scripts/dev.sh

Test runner helper

./scripts/run_tests.sh
./scripts/run_tests.sh unit
./scripts/run_tests.sh integration
./scripts/run_tests.sh security
./scripts/run_tests.sh e2e

The canonical and most direct command remains:

python -m pytest tests -q

9. Tooling Notes

State-returning tools support representation selection

The following tools accept state_representation:

  • genesis_tool
  • get_genesis_result_tool
  • new_state_transition_tool
  • arbitrary_state_transition_tool
  • get_current_state_info_tool
  • get_state_info_tool

Accepted values:

  • raw
  • compact
  • both

Compact preview tool

The server also exposes:

  • get_current_state_compact_context_tool

This generates an SCC-E (State Compression Code — Embedding) preview for the current workspace without creating a new state.

10. Troubleshooting

The server falls back to SQLite unexpectedly

If DB_MODE=neo4j and the server cannot connect to Neo4j, it falls back to SQLite.

Check:

  • Docker is running for managed Neo4j mode
  • your external credentials are correct for external mode
  • NEO4J_BOOTSTRAP_MODE matches the intended mode

Managed Neo4j did not start

Check:

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

SQLite file location

Default SQLite path:

./data/state_manager.db

Override with:

SQLITE_PATH=/custom/path/state_manager.db

11. Production Recommendations

Recommended mode

Use managed Neo4j when:

  • you want graph persistence;
  • Docker is available;
  • you want the project to carry its own persistent graph database.

Use SQLite when

  • Docker is unavailable;
  • you prefer a single local file database;
  • operational simplicity is more important than graph-native storage.

Use external Neo4j when

  • your infrastructure already provides Neo4j;
  • authentication and backup policies are handled outside the project.

12. Canonical References