Skip to main content
Glama

Katamari MCP Server

by ciphernaut
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

Capability

Description

Parameters

web_search

Search web without API tokens

query

(string),

max_results

(int)

web_scrape

Extract web page content

url

(string),

format

(string)

acp_feedback_submit

Submit execution feedback

capability_id

,

rating

,

comment

acp_performance_metrics

View capability analytics

capability_id

(optional)

acp_learning_summary

Learning progress overview

None

acp_inspect

System inspection

None

phase3_workflow_status

Workflow optimization status

workflow_id

(optional)

phase3_predictions

Predictive analytics

capability_id

(optional)

phase3_knowledge_artifacts

Knowledge transfer artifacts

capability_id

(optional)

phase3_healing_status

Self-healing system status

capability_id

(optional)

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

An adaptive MCP server that grows and evolves based on user needs through self-modification, dynamic learning from feedback, and intelligent capability composition with workflow optimization.

  1. Features
    1. Core Architecture
    2. ACP Self-Modification (Phase 1)
    3. Adaptive Learning (Phase 2) ✨ NEW
    4. Advanced Agency (Phase 3) 🚀 NEW
  2. Quick Start
    1. 🚀 Option 1: Automated Setup (Recommended)
    2. 🔧 Option 2: Manual Setup
    3. 🧪 Testing
  3. Project Structure
    1. Usage Examples
      1. MCP Client Integration
      2. Available Capabilities
      3. ACP Self-Modification
      4. Phase 2 Adaptive Learning
    2. Build/Test Commands
      1. Setup & Running
      2. Testing
      3. Development (Manual Setup)
    3. Development
      1. Phase 2 Features
      2. Phase 3 Features
      3. Architecture Evolution
      4. Future Stretch Goals 🚀

    New MCP Servers

    MCP directory API

    We provide all the information about MCP servers via our MCP API.

    curl -X GET 'https://glama.ai/api/mcp/v1/servers/ciphernaut/katamari-mcp'

    If you have feedback or need assistance with the MCP directory API, please join our Discord server