MCP Codebase Insight - WIP

🚧 Development in Progress

This project is actively under development. Features and documentation are being continuously updated.

Overview

MCP Codebase Insight is a system for analyzing and understanding codebases through semantic analysis, pattern detection, and documentation management.

Current Development Status

Completed Features

✅ Core Vector Store System
✅ Basic Knowledge Base
✅ SSE Integration
✅ Testing Framework
✅ TDD and Debugging Framework (rules_template integration)

In Progress

🔄 Documentation Management System
🔄 Advanced Pattern Detection
🔄 Performance Optimization
🔄 Integration Testing
🔄 Debugging Utilities Enhancement

Planned

📋 Extended API Documentation
📋 Custom Pattern Plugins
📋 Advanced Caching Strategies
📋 Deployment Guides
📋 Comprehensive Error Tracking System

Quick Start

Installation
```
pip install mcp-codebase-insight
```

Basic Usage

from mcp_codebase_insight import CodebaseAnalyzer

analyzer = CodebaseAnalyzer()
results = analyzer.analyze_code("path/to/code")

Running Tests

# Run all tests
pytest tests/

# Run unit tests
pytest tests/unit/

# Run component tests
pytest tests/components/

# Run tests with coverage
pytest tests/ --cov=src --cov-report=term-missing

Debugging Utilities

from mcp_codebase_insight.utils.debug_utils import debug_trace, DebugContext, get_error_tracker

# Use debug trace decorator
@debug_trace
def my_function():
    # Implementation

# Use debug context
with DebugContext("operation_name"):
    # Code to debug

# Track errors
try:
    # Risky operation
except Exception as e:
    error_id = get_error_tracker().record_error(e, context={"operation": "description"})
    print(f"Error recorded with ID: {error_id}")

Testing and Debugging

Test-Driven Development

This project follows Test-Driven Development (TDD) principles:

Write a failing test first (Red)
Write minimal code to make the test pass (Green)
Refactor for clean code while keeping tests passing (Refactor)

Our TDD documentation can be found in docs/tdd/workflow.md.

Debugging Framework

We use Agans' 9 Rules of Debugging:

Understand the System
Make It Fail
Quit Thinking and Look
Divide and Conquer
Change One Thing at a Time
Keep an Audit Trail
Check the Plug
Get a Fresh View
If You Didn't Fix It, It Isn't Fixed

Learn more about our debugging approach in docs/debuggers/agans_9_rules.md.

Documentation

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Current Development Status

Completed Features

✅ Core Vector Store System

✅ Basic Knowledge Base

✅ SSE Integration

✅ Testing Framework

✅ TDD and Debugging Framework (rules_template integration)

In Progress

🔄 Documentation Management System

🔄 Advanced Pattern Detection

🔄 Performance Optimization

🔄 Integration Testing

🔄 Debugging Utilities Enhancement

Planned

📋 Extended API Documentation

📋 Custom Pattern Plugins

📋 Advanced Caching Strategies

📋 Deployment Guides

📋 Comprehensive Error Tracking System

Quick Start

Installation

pip install mcp-codebase-insight

Basic Usage

from mcp_codebase_insight import CodebaseAnalyzer

analyzer = CodebaseAnalyzer()
results = analyzer.analyze_code("path/to/code")

Running Tests

# Run all tests
pytest tests/

# Run unit tests
pytest tests/unit/

# Run component tests
pytest tests/components/

# Run tests with coverage
pytest tests/ --cov=src --cov-report=term-missing

Debugging Utilities

from mcp_codebase_insight.utils.debug_utils import debug_trace, DebugContext, get_error_tracker

# Use debug trace decorator
@debug_trace
def my_function():
    # Implementation

# Use debug context
with DebugContext("operation_name"):
    # Code to debug

# Track errors
try:
    # Risky operation
except Exception as e:
    error_id = get_error_tracker().record_error(e, context={"operation": "description"})
    print(f"Error recorded with ID: {error_id}")

Testing and Debugging

Test-Driven Development

This project follows Test-Driven Development (TDD) principles:

Write a failing test first (Red)

Write minimal code to make the test pass (Green)

Refactor for clean code while keeping tests passing (Refactor)

Our TDD documentation can be found in docs/tdd/workflow.md.

Debugging Framework

We use Agans' 9 Rules of Debugging:

Understand the System

Make It Fail

Quit Thinking and Look

Divide and Conquer

Change One Thing at a Time

Keep an Audit Trail

Check the Plug

Get a Fresh View

If You Didn't Fix It, It Isn't Fixed