Codebase State Manager MCP Server

A sophisticated Model Context Protocol (MCP) server for managing codebase states with version control, graph database tracking, and containerized execution environments.

⚠️ WORK IN PROGRESS (WIP) - This project is actively under development. Features may change, APIs may evolve, and breaking changes are expected during the development phase.

⚠️ Important Notice

USE AT YOUR OWN RISK

This software is provided "as-is" without any warranties or guarantees. Users assume full responsibility for:

Any data loss or corruption
Security vulnerabilities introduced through usage
Compliance with applicable laws and regulations
Proper backup and recovery procedures
Testing in isolated environments before production use

The developers are not liable for any damages, losses, or issues arising from the use of this software.

🚀 Features

Core Capabilities

State Machine Management: Track codebase evolution through numbered states
Git Integration: Capture diffs, branches, and commit history
Graph Database Storage: Neo4j for relationship-based state tracking
SQLite Fallback: Relational database support when Neo4j is unavailable
Docker Containerization: Isolated execution environments for git operations

Advanced Features

State Transitions: Linear and arbitrary transitions between codebase states
Content Hashing: SHA256 hashing for state integrity verification
Search & Query: Full-text search across state prompts and diffs
Performance Metrics: Detailed timing and operation statistics
Structured Logging: JSON-formatted logs with session context
Security Layers: Input validation, rate limiting, and audit logging

🏗️ Architecture

The system follows Clean Architecture principles with clear separation of concerns:

MCP Client → Tools Layer → Services Layer → Repositories Layer → Database

Key Components

MCP Tools Layer: Protocol interface and tool definitions
Services Layer: Business logic (StateService, GitManager)
Repositories Layer: Data access abstraction (Neo4j/SQLite)
Utilities: Security, logging, metrics, and validation modules

For detailed architecture documentation, see ARCHITECTURE.md.

🚀 Quick Start

Prerequisites

Python 3.10+
Docker & Docker Compose
Git
Neo4j (optional, for graph database features)

Installation

# Clone the repository
git clone https://github.com/apolosan/codebase_state_manager_mcp.git
cd codebase_state_manager_mcp

# Setup environment (uses uv if available)
./scripts/setup.sh

# Verify installation with tests
./scripts/run_tests.sh

Using uv (Recommended)

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup with uv
./scripts/setup.sh --sync

# Run development server
./scripts/dev.sh

🛠️ Usage

Starting the MCP Server

# Using the launcher script
python run_mcp_server.py

# Or directly via module
python -m src.mcp_server

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Run test suite in Docker
docker-compose -f docker-compose.test.yml up --build

Available MCP Tools

State Management

genesis() - Create initial state #0
new_state_transition(prompt) - Create next sequential state
arbitrary_state_transition(target_state, prompt) - Jump to any existing state
get_current_state_info() - Get details of current state
get_state_info(state_number) - Get details of specific state
total_states() - Count total states
search_states(text) - Search across state prompts

Transition Tracking

get_state_transitions(state_number) - Get transitions from/to a state
get_transition_info(transition_id) - Get transition details
track_transitions() - Monitor recent transitions
get_current_state_transitions() - Get transitions for current state

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# Database Configuration
DB_MODE=neo4j  # or sqlite
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Docker Settings
DOCKER_VOLUME_NAME=codebase_volume
VOLUME_PATH=/path/to/volume

# Security Settings
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60

Database Modes

Neo4j Mode (Recommended)

# docker-compose.yml
neo4j:
  image: neo4j:5.24
  environment:
    NEO4J_AUTH: neo4j/password
  ports:
    - "7474:7474"  # Browser UI
    - "7687:7687"  # Bolt protocol

SQLite Mode (Fallback)

Automatically falls back to SQLite when Neo4j is unavailable. Data is stored in data/state_manager.db.

📊 Testing

Test Suite

# Run all tests
./scripts/run_tests.sh

# Specific test categories
./scripts/run_tests.sh unit
./scripts/run_tests.sh integration
./scripts/run_tests.sh security
./scripts/run_tests.sh e2e

# With coverage report
./scripts/run_tests.sh --coverage

Test Statistics

440 Total Tests: 100% passing
90% Code Coverage: Comprehensive test suite
Security Tests: Bandit, audit logging, rate limiting
Performance Tests: Stress testing and metrics validation
Integration Tests: Docker, Neo4j, SQLite integration

🔒 Security

Built-in Security Features

Input Validation: Sanitization of all user inputs
Rate Limiting: Token bucket algorithm per client
Audit Logging: Comprehensive operation tracking
Content Hashing: SHA256 verification of state integrity
Container Isolation: Docker-based git operations
No Hardcoded Secrets: Environment-based configuration only

Security Testing

# Run security tests
./scripts/run_tests.sh security

# Bandit security scan
uv run bandit -r src/

# Custom security validation
python -m pytest tests/security/ -v

📈 Performance

Monitoring & Metrics

PerformanceMonitor: Tracks state transitions, DB queries, git operations
MetricsCollector: Aggregates counters and timing statistics
@timed_operation: Decorator for automatic performance profiling
Structured Logging: JSON output for easy parsing and analysis

Optimization Features

Connection Pooling: Efficient database connection management
Lazy Loading: On-demand resource initialization
Caching: Frequently accessed state information
Async Operations: Non-blocking I/O where applicable

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for detailed guidelines.

Development Setup

# Install development dependencies
./scripts/setup.sh

# Activate pre-commit hooks
chmod +x .git/hooks/pre-commit
.git/hooks/pre-commit

# Run development server
./scripts/dev.sh

Code Quality

Type Checking: mypy with strict settings
Code Formatting: Black and isort
Linting: Custom pre-commit hooks
Documentation: Comprehensive docstrings and API references

Testing Guidelines

Write tests for all new functionality
Maintain 90%+ code coverage
Include security tests for sensitive operations
Add integration tests for database interactions
Include performance tests for critical paths

For comprehensive agent guidelines, see AGENTS.md.

📚 Documentation

Key Documents

ARCHITECTURE.md - System architecture and design decisions
CONTRIBUTING.md - Development guidelines and processes
CHANGELOG.md - Version history and changes
AGENTS.md - Agent guidelines and operational requirements
QUICKSTART.md - Quick start guide
SETUP.md - Detailed setup instructions

Code Documentation

Comprehensive docstrings following Google style
Type hints for all function signatures
Example usage in docstrings
Error handling documentation

📄 License

MIT License - see LICENSE file for details.

⚠️ Disclaimer (Reiterated)

This software is experimental and should be used with extreme caution. Always:

Backup your data before use
Test in isolated environments first
Monitor system resources during operation
Review security configurations regularly
Assume responsibility for all usage consequences

The developers provide no warranties and accept no liability for any issues arising from the use of this software.

Note: This is a Work in Progress (WIP) project. The software is in active development and may undergo significant changes, including breaking API modifications, feature additions, and architectural improvements. Users should expect ongoing evolution and should not consider this a stable production-ready solution at this stage.