AI MCP Host

A Python application that hosts AI assistants (OpenAI GPT or Claude) with Model Context Protocol (MCP) integration, allowing AI to use external tools and services. Now with library-like architecture for easy integration into other applications!

Features

• 🤖 Multi-AI Support: Works with both OpenAI GPT and Claude
• 🔧 MCP Integration: Connect to various MCP servers for extended functionality
• 🎯 Tool Calling: AI can automatically use available MCP tools
• ⚙️ Configurable: Easy JSON-based configuration
• 💬 Interactive CLI: Chat interface with command support
• 🔌 Extensible: Add new MCP servers easily
• 📚 Library-like: Core chat functionality can be used programmatically in other applications

Quick Start

1. Installation

# Clone the repository
git clone <repository-url>
cd ai-mcp-host

# Quick setup with Makefile (recommended)
make install

# Or manual setup:
# pip install -r requirements.txt
# Install Node.js (required for MCP servers)
# On macOS: brew install node
# On Ubuntu: sudo apt install nodejs npm

2. Configuration

Note: Configuration files are automatically created when you run make install.

API Keys Setup

Set up your API keys by creating a .env file:

# Create .env file with your API keys
cat > .env << EOF
# Choose one or both AI providers
ANTHROPIC_API_KEY=your-anthropic-api-key-here
OPENAI_API_KEY=your-openai-api-key-here

# Optional: MCP server tokens (configure as needed)
# SLACK_MCP_XOXP_TOKEN=your-slack-bot-token
# SLACK_TEAM_ID=your-slack-team-id
# NOTION_API_KEY=your-notion-api-key
# SUPABASE_ACCESS_TOKEN=your-supabase-token
EOF

Important: Never commit .env files to git. They are automatically ignored by .gitignore.

MCP Servers Configuration

Configure MCP servers by editing mcp_config.json:

# Copy the example file (done automatically by make install)
cp mcp_config.example.json mcp_config.json

# Edit mcp_config.json to configure your desired MCP servers

Example configuration:

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key_env": "OPENAI_API_KEY"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. Run the Application

# Using Makefile (recommended)
make run

# Or directly
python mcp-use-cli.py

# Or using the run script
./run_mcp_use.sh

🛠️ Makefile Commands

The project includes a comprehensive Makefile for easy development:

# Setup and installation
make install          # Complete setup (dependencies, venv, env)
make setup           # Alias for install

# Development
make run             # Start the application
make dev             # Alias for run
make test            # Run tests
make lint            # Run linting checks
make format          # Format code with black
make check           # Run lint + test

# Utilities
make clean           # Clean cache files
make clean-all       # Clean everything including venv
make status          # Show system status
make logs            # Show recent logs
make update          # Update dependencies

# Quick shortcuts
make i               # Quick install
make r               # Quick run
make c               # Quick clean
make t               # Quick test
make l               # Quick lint
make f               # Quick format

# Help
make help            # Show all available commands

Available MCP Servers

The configuration includes several pre-configured MCP servers:

• Filesystem: File system operations
• Brave Search: Web search capabilities
• SQLite: Database operations
• GitHub: GitHub repository access
• PostgreSQL: PostgreSQL database operations

Enable them by setting "disabled": false and providing required API keys.

Usage

Chat Commands

• help - Show available commands
• clear - Clear conversation history
• tools - List available MCP tools
• status - Show MCP connection status
• quit - Exit application

Example Interaction

You: Can you search for information about Python async programming?

🤖 Assistant: I'll search for information about Python async programming for you.

🔧 Calling tool: brave_search
✅ Tool result: {...}

Based on my search, here's what I found about Python async programming...

Configuration Options

AI Provider Settings

{
  "ai": {
    "provider": "openai",     // "openai" or "claude"
    "model": "gpt-4",         // Model name
    "api_key_env": "OPENAI_API_KEY"  // Environment variable name
  }
}

MCP Server Configuration

{
  "mcpServers": {
    "server_name": {
      "command": "npx",                    // Command to run
      "args": ["-y", "package-name"],      // Command arguments
      "env": {                             // Environment variables
        "API_KEY": "your-key"
      },
      "disabled": false,                   // Enable/disable server
      "autoApprove": ["tool_name"]         // Auto-approve specific tools
    }
  }
}

Adding New MCP Servers

1. Find an MCP server package (usually npm packages)
2. Add configuration to mcp_config.json
3. Set required environment variables
4. Enable the server and restart

Example:

{
  "my_custom_mcp": {
    "command": "python",
    "args": ["-m", "my_mcp_server"],
    "env": {
      "CUSTOM_API_KEY": "key-here"
    },
    "disabled": false,
    "autoApprove": ["safe_tool_name"]
  }
}

Troubleshooting

Common Issues

1. MCP Server Not Starting

   • Check if Node.js is installed
   • Verify command and arguments in config
   • Check environment variables

2. AI API Errors

   • Verify API key is set correctly
   • Check internet connection
   • Ensure sufficient API credits

3. Tool Calls Failing

   • Check MCP server logs
   • Verify tool parameters
   • Ensure MCP server is connected

Debug Mode

Enable debug logging by setting:

export PYTHONPATH=.
python -c "import logging; logging.basicConfig(level=logging.DEBUG)"
python mcp-use-cli.py

🏗️ Architecture

Library-Like Design

The application now features a library-like architecture where core chat functionality is separated from interface-specific code, making it easy to integrate into other applications.

Before Refactoring:

┌─────────────────┐
│   CLI Interface │ ← All chat logic embedded here
│                 │ ← Tightly coupled to console
│  • User input   │ ← Hard to reuse elsewhere
│  • AI calls     │
│  • Tool calls   │
│  • History mgmt │
└─────────────────┘

After Refactoring:

┌─────────────────┐    ┌─────────────────┐
│   CLI Interface │───▶│   ChatService   │ ← Core library
│                 │    │    (Library)    │ ← Reusable
└─────────────────┘    └─────────────────┘
                              ▲
┌─────────────────┐           │
│   API Interface │───────────┘
│                 │
└─────────────────┘
                              ▲
┌─────────────────┐           │
│  Custom App     │───────────┘
│                 │
└─────────────────┘

Core Components

1. ChatService Class (chat_service.py)

The main library that handles all chat functionality:

class ChatService:
    def __init__(self, ai_client, mcp_manager, verbose=False, output_handler=None):
        # Core dependencies
        self.ai_client = ai_client          # AI/LLM client
        self.mcp_manager = mcp_manager      # MCP tools manager
        self.verbose = verbose              # Detail level
        self.output_handler = output_handler # Custom output handling

2. Data Structures

@dataclass
class ChatMessage:
    role: str           # 'user', 'assistant', 'system'
    content: str        # Message content
    tool_calls: List    # Any tool calls made
    usage: Dict         # Token usage info

@dataclass
class ChatResponse:
    message: ChatMessage           # AI's response
    tool_calls_executed: List     # Tools that were executed
    success: bool                 # Whether chat succeeded
    error: Optional[str]          # Any error message

3. Output Handler System

Allows different interfaces to handle output differently:

def custom_output_handler(message_type: str, content: str, data=None):
    if message_type == "assistant_response":
        # CLI: print to console
        # API: add to JSON response
        # GUI: update chat window
    elif message_type == "tool_call":
        # Handle tool execution notifications

Chat Flow Process

Here's what happens when you send a message:

1. User Message
   ↓
2. ChatService.chat(message)
   ↓
3. Format available MCP tools for AI
   ↓
4. Call AI client with message + tools
   ↓
5. AI responds with content ± tool calls
   ↓
6. If tool calls exist:
   ├─ Execute tools via MCP manager
   ├─ Get tool results
   ├─ Send results back to AI
   └─ Get follow-up AI response
   ↓
7. Return structured ChatResponse
   ↓
8. Output handler displays results

Usage Examples

1. CLI Usage (Current)

# In cli_interface.py
self.chat_service = ChatService(ai_client, mcp_manager, verbose=self.verbose)
response = await self.chat_service.chat(user_input)
# Output automatically handled by default console handler

2. Programmatic Usage

# In your own code
from chat_service import ChatService

# Initialize
chat_service = ChatService(ai_client, mcp_manager, verbose=True)

# Use directly
response = await chat_service.chat("What tools do you have?")
print(f"AI said: {response.message.content}")
print(f"Tools used: {len(response.tool_calls_executed)}")

3. API Usage

# In a web API
async def handle_chat_request(message: str):
    # Custom output handler for API responses
    api_output = []
    
    def api_handler(msg_type, content, data=None):
        api_output.append({"type": msg_type, "content": content})
    
    chat_service = ChatService(ai_client, mcp_manager, 
                              output_handler=api_handler)
    
    response = await chat_service.chat(message)
    
    return {
        "response": response.message.content,
        "tools_used": response.tool_calls_executed,
        "output_log": api_output
    }

Key Benefits

1. Separation of Concerns

• ChatService: Core chat logic, AI interactions, tool management
• CLIInterface: User interface, command parsing, console output
• Other interfaces: Can focus on their specific UI/API concerns

2. Reusability

• Same chat logic works in CLI, web APIs, desktop apps, etc.
• No code duplication
• Consistent behavior across interfaces

3. Customizable Output

• CLI: Prints to console with colors/emojis
• API: Collects output for JSON responses
• GUI: Updates chat windows/notifications
• Custom: Whatever you need

4. Easy Testing

• ChatService can be tested independently
• Mock output handlers for testing
• Clear separation makes debugging easier

How to Extend

To add a new interface (e.g., web API):

1. Create your interface class
2. Initialize ChatService with custom output handler
3. Call chat_service.chat(message) for interactions
4. Handle the structured response as needed

The core chat functionality remains the same - you just change how input comes in and output goes out!

File Structure

• mcp-use-cli.py - Application entry point using mcp-use library
• chat_service.py - Core chat library (NEW) - reusable chat functionality
• ai_client.py - AI provider abstraction (OpenAI/Claude)
• mcp_manager.py - MCP connection and tool management
• cli_interface.py - Interactive command-line interface (now uses ChatService)
• mcp_config.json - Configuration file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and test
4. Submit a pull request

License

MIT License - see LICENSE file for details.