Katamari MCP Server

An adaptive MCP (Model Context Protocol) server with ACP (Agent Control Protocol) that grows and evolves based on user needs through adaptive learning.

Features

Core Architecture

• Intelligent Routing: Tiny LLM model for efficient call routing
• Modular Capabilities: Plugin-based architecture with environment isolation
• Hot Reload: Development-friendly reload after test completion
• Security: Sandboxed execution and package validation
• Asset Tracking: Complete provenance tracking for all components

ACP Self-Modification (Phase 1)

• Self-Inspection: Analyze current capabilities and system state
• Capability Generation: Create new capabilities based on needs
• Workflow Composition: Combine capabilities into workflows
• Self-Healing: Detect and fix system issues
• Heuristic Governance: 7-tag safety system for all operations

Adaptive Learning (Phase 2) NEW

• Dynamic Heuristics: Self-adjusting decision making based on performance
• Multi-Channel Feedback: User satisfaction, automatic monitoring, test results
• Performance Analytics: Real-time capability health scoring and trends
• Learning Engine: Pattern recognition and confidence-weighted adaptations
• Feedback Loops: Continuous improvement from every execution

Advanced Agency (Phase 3) NEW

• Workflow Optimizer: Parallel execution, pattern recognition, auto-optimization
• Predictive Analytics: Performance prediction, proactive alerts, resource forecasting
• Knowledge Transfer: Cross-component learning, artifact sharing, similarity analysis
• Self-Healing System: Enhanced error recovery, pattern recognition, resilience policies

Quick Start

Option 1: Automated Setup (Recommended)

# Clone and run the auto-setup script
git clone <repository-url>
cd katamari-mcp
./start_server.sh

The start_server.sh script automatically:

• Checks Python 3.9+ compatibility
• Creates and activates virtual environment
• Installs all dependencies (PyTorch CPU-only for faster setup)
• Verifies server functionality
• Creates necessary data directories
• Starts the MCP server

Option 2: Manual Setup

# 1. Clone and setup environment
git clone <repository-url>
cd katamari-mcp
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil

# 3. Verify installation
python -c "from katamari_mcp.server import KatamariServer; print(' Ready')"

# 4. Start server
python -m katamari_mcp.server

Testing

# Run all tests
pytest

# Run Phase 2 adaptive learning tests
pytest tests/test_adaptive_learning.py

# Run Phase 3 advanced agency tests
pytest tests/test_phase3_simple.py tests/test_phase3_integration.py

# Test specific functionality
pytest tests/test_adaptive_learning.py::test_feedback_submission

Project Structure

katamari-mcp/
 katamari_mcp/          # Core server code
    router/           # LLM routing system with Phase 2 endpoints
    acp/              # ACP self-modification system
       adaptive_learning.py    # Dynamic heuristic adjustment
       feedback.py             # Feedback collection system
       performance_tracker.py  # Performance analytics
       data_models.py          # Centralized data structures
       controller.py          # ACP main orchestrator
       heuristics.py          # 7-tag safety system
       testing.py             # Parallel testing
       git_tracker.py         # Version control integration
       workflow_optimizer.py   # Phase 3: Workflow optimization
       predictive_engine.py    # Phase 3: Predictive analytics
       knowledge_transfer.py   # Phase 3: Cross-component learning
       self_healing.py        # Phase 3: Enhanced error recovery
    security/         # Security and validation
    utils/           # Utilities and helpers
 tests/               # Test suite
    test_adaptive_learning.py  # Phase 2 comprehensive tests
    test_phase3_simple.py      # Phase 3 basic functionality tests
    test_phase3_integration.py # Phase 3 integration tests
 capabilities/         # Individual capability implementations
 PLAN.md              # Detailed project plan with Phase 2 details
 README.md            # This file

Usage Examples

MCP Client Integration

Claude Desktop:
Add to claude_desktop_config.json:

{
  "mcpServers": {
    "katamari": {
      "command": "bash",
      "args": ["/path/to/katamari-mcp/start_server.sh"],
      "cwd": "/path/to/katamari-mcp"
    }
  }
}

Direct MCP Usage:

# List available capabilities
capabilities = await router.list_capabilities()

# Use web search
results = await router.call("web_search", {
    "query": "adaptive learning systems",
    "max_results": 5
})

# Use web scraping
content = await router.call("web_scrape", {
    "url": "https://example.com",
    "format": "markdown"
})

# Submit feedback for learning
await router.call("acp_feedback_submit", {
    "capability_id": "web_search",
    "rating": 5,
    "comment": "Great results!"
})

Available Capabilities

ACP Self-Modification

# Inspect system capabilities
inspection = await router.call("acp_inspect", {})

# Propose new capability
proposal = await router.call("acp_propose", {
    "need": "data visualization capability",
    "context": {"user_preference": "chart generation"}
})

# Compose workflow
workflow = await router.call("acp_compose", {
    "capabilities": ["web_search", "data_analysis"],
    "workflow_name": "research_pipeline"
})

Phase 2 Adaptive Learning

# Submit feedback for capability
await router.call("acp_feedback_submit", {
    "capability_id": "web_search",
    "rating": 5,
    "comment": "Excellent results!"
})

# Get performance analytics
metrics = await router.call("acp_performance_metrics", {
    "capability_id": "web_search",
    "days_back": 7
})

# Get learning summary
learning = await router.call("acp_learning_summary", {})

Build/Test Commands

Setup & Running

• ./start_server.sh - Recommended: Auto-setup and start server
• python -m katamari_mcp.server - Start server (manual setup required)

Testing

• pytest - Run all tests
• pytest tests/test_adaptive_learning.py - Run Phase 2 adaptive learning tests
• pytest -k "test_name" - Run specific test

Development (Manual Setup)

• source .venv/bin/activate - Activate virtual environment
• pip install torch --index-url https://download.pytorch.org/whl/cpu - Install PyTorch
• pip install transformers pydantic aiohttp mcp pytest-asyncio beautifulsoup4 psutil - Install deps
• ruff check . - Lint code
• black . - Format code
• mypy . - Type checking

Development

See PLAN.md for detailed architecture and implementation roadmap.

Phase 2 Features

• Adaptive Learning Engine - Dynamic heuristic adjustment
• Feedback Collection - Multi-channel feedback system
• Performance Tracking - Real-time analytics and health scoring
• Data Models - Centralized validation and serialization
• Router Integration - New MCP endpoints for learning features
• Comprehensive Testing - Full test coverage for adaptive components

Phase 3 Features

• Workflow Optimizer - Parallel execution, pattern recognition, auto-optimization
• Predictive Analytics Engine - Performance prediction, proactive alerts, resource forecasting
• Knowledge Transfer System - Cross-component learning, artifact sharing, similarity analysis
• Self-Healing System - Enhanced error recovery, pattern recognition, resilience policies
• System Integration - All Phase 3 components integrated with main server
• Comprehensive Testing - Full test coverage for Phase 3 components

Architecture Evolution

• Phase 1: Foundation - ACP self-modification and basic capabilities
• Phase 2: Intelligence - Adaptive learning and feedback systems
• Phase 3: Agency - Advanced workflow optimization, predictive capabilities, and self-healing

Future Stretch Goals

See TODO.md for planned enhancements:

• Named Pipe Communication - Faster startup and persistent context
• MCP TaskMaster - Stateful background task management
• Enhanced Context Management - Cross-call conversation context
• Performance Optimization Suite - Advanced monitoring and tuning