BROKKOLY MCP Server Debugger

A simplified chat interface for interacting with Python MCP (Model Context Protocol) servers in-process.

Overview

BROKKOLY is a simple chat interface designed specifically for Python MCP servers. It allows you to:

• Run MCP servers in-process using threads
• Simulate stdin/stdout communication using memory streams
• Chat with an LLM agent (powered by LangChain and OpenAI) that can interact with MCP servers

Features

• In-process execution: Run MCP servers in the same process as the chat interface
• Memory streams: Simulate stdin/stdout communication using memory streams
• LLM agent: Chat with an LLM agent that can interact with MCP servers
• Automatic server management: Automatically start all MCP servers at initialization
• Message handling: Send and receive messages to/from MCP servers through the LLM
• Configuration: Configure MCP servers using a JSON configuration file

Installation

Prerequisites

• Python 3.9 or higher
• OpenAI API key (for the LLM agent)

Installation Steps

1. Clone the repository:

git clone https://github.com/yourusername/brokkoly.git
cd brokkoly

2. Install the package:

pip install -e .

3. Create a .env file with your OpenAI API key:

echo "OPENAI_API_KEY=your-api-key" > .env

Usage

Configuration

Create a mcp.json file with your MCP server configurations:

{
  "mcpServers": {
    "example": {
      "command": "python",
      "args": [
        "/path/to/mcp_server.py",
        "--mode",
        "stdio"
      ],
      "env": {
        "EXAMPLE_VAR": "example_value"
      }
    }
  }
}

Running the Debugger

Run the debugger:

python main.py

Or, if you installed the package:

brokkoly

Command-line Arguments

• --config: Path to the MCP configuration file
• --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• --log-file: Path to the log file
• --env-file: Path to the .env file
• --verbose: Enable verbose output

Chat Interface

The chat interface is a simple text-based interface that allows you to:

• Chat with the LLM agent
• Type 'exit' or 'quit' to exit the application
• The LLM agent can interact with MCP servers using tools

Development

Project Structure

• brokkoly/: Main package directory
  • config/: Configuration module
  • memory_streams/: Memory streams module
  • server_manager/: Server manager module
  • llm_agent/: LLM agent module
  • utils/: Utility functions
• tests/: Test directory
• main.py: Entry point
• setup.py: Setup script

License

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

Acknowledgements

• LangChain for the LLM agent
• OpenAI for the LLM API
• Pydantic for the configuration models
• AnyIO for the memory streams