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