state-of-mika 0.2.2

A streamlined connector for Language Models to interact with MCP servers

State of Mika SDK

Overview

State of Mika SDK (SoM) is a comprehensive framework that connects large language models (LLMs) with specialized capability servers using the Model Context Protocol (MCP). This integration enables AI systems to access a wide range of tools and services through a standardized interface.

Key benefits include:

• Seamless Connection: Connect LLMs and external capabilities with minimal code
• Standardized Communication: Leverage the Model Context Protocol for consistent interfaces
• Dynamic Discovery: Automatically find and use appropriate capability servers
• Intelligent Error Handling: Get actionable suggestions when things go wrong
• Simple Integration: Add new capabilities to AI workflows with minimal effort

Installation

Install the State of Mika SDK via pip:

pip install state-of-mika

Or from the source code:

git clone https://github.com/state-of-mika/sdk.git
cd sdk
pip install -e .

Quick Start

import asyncio
from state_of_mika import SoMAgent

async def main():
    # Initialize the agent with auto-installation
    agent = SoMAgent(auto_install=True)
    await agent.setup()
    
    try:
        # Process a natural language request
        result = await agent.process_request("What's the weather in Tokyo today?")
        
        if result.get("status") == "success":
            print(f"Result: {result.get('result')}")
        else:
            print(f"Error: {result.get('error')}")
            print(f"Suggestion: {result.get('suggestion')}")
    finally:
        # Clean up resources
        await agent.aclose()

if __name__ == "__main__":
    asyncio.run(main())

Core Features

• Capability Connection: Connect LLMs to MCP capability servers with standardized interfaces
• Server Discovery & Management: Automatically find, install, and manage the appropriate servers for requested capabilities
• Request Analysis: Analyze natural language requests to determine required capabilities using Claude's language understanding
• Auto-Installation: Install required servers on-demand when capabilities are requested
• Comprehensive Registry: Access a growing catalog of available MCP servers and their capabilities
• Intelligent Error Handling: Receive detailed error analysis with human-readable suggestions for resolution
• Environment Variable Management: Configure API keys and other settings securely through environment variables
• Context Management: Properly manage server connections and resources throughout the application lifecycle
• CLI Tools: Command-line utilities for server management and capability execution

API Access Requirements

Important: This SDK requires an Anthropic API key to function properly, as it uses Claude for request analysis. You can set your API key as an environment variable:

export ANTHROPIC_API_KEY="your_anthropic_api_key_here"

You can obtain an API key by signing up at Anthropic's website.

Some MCP servers may require additional API keys depending on the services they integrate with. For example, the weather capability requires:

export ACCUWEATHER_API_KEY="your_accuweather_api_key_here"

How It Works

The State of Mika SDK provides a bridge between natural language requests and specialized capability servers:

1. A natural language request is received from the user or an LLM
2. Claude analyzes the request to determine the required capability and parameters
3. The SDK locates the appropriate MCP server for that capability
4. If needed, the server is automatically installed
5. The SDK connects to the server and executes the requested operation
6. Results or helpful error information are returned to the calling application

Usage Examples

High-Level Interface with SoMAgent

import asyncio
from state_of_mika import SoMAgent

async def process_request():
    # Initialize the agent with your API key (or set env var ANTHROPIC_API_KEY)
    agent = SoMAgent(api_key="your_api_key_here", auto_install=True)
    await agent.setup()
    
    # Process a user request
    result = await agent.process_request("What's the weather like in Tokyo today?")
    
    # Handle the response
    if result.get("status") == "success":
        print("Success:", result.get("result"))
    else:
        print("Error:", result.get("error"))
        print("Suggestion:", result.get("suggestion"))
    
    await agent.aclose()

asyncio.run(process_request())

Direct Capability Access

import asyncio
from state_of_mika import Connector

async def execute_capability():
    connector = Connector(auto_install=True)
    await connector.setup()
    
    # Execute a specific capability with predefined parameters
    result = await connector.execute_capability(
        capability="weather",
        tool_name="get_hourly_weather",
        parameters={"location": "Tokyo"}
    )
    
    print(result)
    await connector.aclose()

asyncio.run(execute_capability())

Context Manager Pattern

async def with_context_manager():
    connector = Connector(auto_install=True)
    await connector.setup()
    
    async with connector.connect_session("weather") as (server_name, client):
        result = await client.call_tool("get_hourly_weather", {"location": "London"})
        print(f"Result from {server_name}:", result)

asyncio.run(with_context_manager())

Error Handling

SoM provides comprehensive error interpretation. When a tool connection fails, it returns:

{
  "error": "Error message details",
  "error_type": "ApiKeyMissing",
  "status": "error",
  "explanation": "The operation failed because the required API key is missing",
  "suggestion": "Set the ACCUWEATHER_API_KEY environment variable",
  "requires_user_action": true,
  "tool_name": "get_hourly_weather",
  "capability": "weather"
}

This structured error format helps developers and LLMs understand what went wrong and how to fix it.

Auto-Installation Settings

SoM can automatically install MCP servers as needed. You can enable this feature in two ways:

1. Set an environment variable:

   export AUTO_INSTALL_SERVERS="true"
   

2. Specify it directly in code:

   connector = Connector(auto_install=True)
   # or
   agent = SoMAgent(auto_install=True)
   

Command Line Interface (CLI)

SoM provides a command-line interface for managing servers and executing capabilities:

View Available Servers

som list-servers

Search for Servers by Capability

som search weather

Install a Server

som install mcp_weather

Execute a Capability

som execute weather get_hourly_weather --params '{"location": "Tokyo"}'

Check if a Server is Installed

som check mcp_weather

Update the Registry

som update-registry

Interactive Mode

som interactive

This launches an interactive shell where you can test capabilities directly.

Environment Variables

• ANTHROPIC_API_KEY: Required for Claude analysis
• AUTO_INSTALL_SERVERS: Set to "true" to automatically install needed servers
• USE_MOCK_DATA: Set to "true" to use mock data instead of real server calls (for testing)
• SOM_LOCAL_DEV: Set to "true" to prioritize locally installed servers over registry versions
• Server-specific API keys (as required by individual servers)

Adding Custom MCP Servers

1. Adding to Local Registry

You can add custom MCP servers to your local registry in two ways:

Using the CLI:

som add-server --name "my_custom_server" --description "My custom MCP server" --capabilities "custom,tools" --install-type "pip" --package "my-custom-package"

Editing the Registry File Directly:

The registry is stored in ~/.som/registry.json or in the package's registry directory. You can add a new server entry:

{
  "name": "mcp_custom",
  "description": "My custom MCP server",
  "categories": ["custom"],
  "capabilities": ["custom_capability"],
  "version": "0.1.0",
  "install": {
    "type": "pip",
    "repository": "https://github.com/yourusername/your-repo.git",
    "package": "mcp-custom-package",
    "global": true
  }
}

2. Installing Custom Packages Not in Registry

You can install any MCP-compatible package directly:

# Install from PyPI
pip install mcp-custom-package

# Install from GitHub
pip install git+https://github.com/yourusername/your-repo.git

# Then register it with SoM
som add-server --name "mcp_custom" --description "Custom server" --capabilities "custom" --install-type "already-installed"

3. Creating Your Own MCP Server

To create your own MCP server:

1. Start with the MCP template: https://github.com/outlines-dev/mcp-server-template
2. Implement your server's functionality
3. Install your package: pip install -e .
4. Register it with SoM using the CLI

Advanced Configuration

Custom Registry Location

from pathlib import Path
from state_of_mika import Registry, Connector

registry = Registry(registry_file=Path("/path/to/custom/registry.json"))
connector = Connector(registry=registry)

Semantic Search in the Registry

from state_of_mika import Registry

registry = Registry()
# Enhanced search with multiple criteria
servers = registry.enhanced_search(
    query="Find weather information", 
    categories=["weather"], 
    capabilities=["forecast"],
    include_score=True
)

Available Capabilities

The SDK provides access to a growing ecosystem of capabilities, including:

• Weather Information: Current conditions, forecasts, and historical data
• Web Search: Query search engines and retrieve results
• Time and Date: Time zones, conversions, and scheduling
• File Operations: Reading, writing, and managing files
• Web Browsing: Automated browser interactions
• Code Execution: Run code in various languages
• Data Analysis: Process and analyze structured data
• API Integration: Connect to external API services
• Database Access: Query and manage databases
• Media Processing: Image, audio, and video operations

Model Context Protocol (MCP)

The Model Context Protocol provides a standardized way for language models to communicate with capability servers. By using MCP, State of Mika SDK enables:

• Consistent interfaces across different capabilities
• Structured parameter passing and validation
• Standardized error handling
• Dynamic discovery of available tools
• Clear documentation of capabilities

Troubleshooting

Common issues and solutions:

API Key Issues

If you encounter errors about missing API keys:

Error: Authentication failed. API key is missing.

Make sure you've set the required environment variables.

Server Installation Failures

If a server fails to install:

Error: Failed to install server for capability: weather

Try manually installing with pip and check for dependency conflicts.

Connection Errors

If you see connection errors:

Error: Failed to connect to any server for capability: weather

Check your internet connection and server status.

Development and Testing

For development, install the package with development dependencies:

pip install -e ".[dev]"

Run tests:

pytest

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Please include tests for new functionality.

License

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

Support

For additional help or to report issues:

• GitHub Issues: Report an issue
• Documentation: Full documentation