pythonium 0.1.5

A modular MCP (Model Context Protocol) server for AI agents with plugin-based architecture

Pythonium

A modular Model Context Protocol (MCP) server designed to enable advanced capabilities for AI agents through a robust, extensible architecture built on the official MCP SDK.

Overview

Pythonium provides a comprehensive, production-ready foundation for building sophisticated AI agent tools and capabilities. Built around the Model Context Protocol specification and leveraging the official MCP SDK (FastMCP), it offers a clean separation of concerns through its modular package structure and streamlined configuration management.

Architecture

Core Packages

• pythonium.common - Shared utilities, configuration management, and base components
• pythonium.core - Central server implementation, configuration, and tool management
• pythonium.tools - Comprehensive standard tool library with extensible framework
• pythonium.managers - Lightweight management systems for specialized functionality

Features

MCP SDK Integration

• Built on the official MCP SDK's FastMCP framework
• Full Model Context Protocol compliance
• Multiple transport support (stdio, HTTP, WebSocket)
• Native tool registration and capability negotiation

Comprehensive Tool Library

• System Operations: Command execution, environment access, system monitoring (pythonium.tools.std.execution)
• File Operations: Advanced file and directory management (pythonium.tools.std.file_ops)
• Web Operations: HTTP client, web search with multiple engines (pythonium.tools.std.web)
• Tool Management: Meta-tools for tool discovery and introspection (pythonium.tools.std.tool_ops)

Advanced Configuration

• Pydantic-based configuration with validation
• Environment variable integration
• Multiple format support (YAML, JSON, TOML)
• Hot-reload capability and override support

Production Features

• Structured logging with multiple output formats
• Comprehensive error handling and recovery
• Resource management and connection pooling
• Security considerations and rate limiting
• Performance optimizations with async architecture

Quick Start

Installation

# Clone the repository
git clone https://github.com/dwharve/pythonium.git
cd pythonium

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Basic Usage

# Run the MCP server
python -m pythonium --help

# Start with default configuration (stdio transport)
python -m pythonium serve

# Start with HTTP transport
python -m pythonium serve --transport http --host localhost --port 8080

# Start with WebSocket transport
python -m pythonium serve --transport websocket --host localhost --port 8080

# Start with custom configuration file
python -m pythonium serve --config config/server.yaml

# Alternative: Use installed script
pythonium --help
pythonium serve

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run tests with coverage
pytest --cov=pythonium --cov-report=html

# Format code
black pythonium tests
isort pythonium tests

# Type checking
mypy pythonium

Project Structure

pythonium/
├── pythonium/           # Main package
│   ├── common/         # Shared utilities and base components
│   │   ├── config.py   # Pydantic configuration management
│   │   ├── base.py     # Base classes and result types
│   │   ├── logging.py  # Structured logging system
│   │   └── ...         # HTTP client, error handling, etc.
│   ├── core/           # Core server and management
│   │   ├── server.py   # Main MCP server implementation
│   │   ├── config.py   # Configuration manager
│   │   └── tools/      # Tool registry and discovery
│   ├── tools/          # Tool implementations
│   │   ├── base.py     # Base tool framework
│   │   └── std/        # Standard tool library
│   ├── managers/       # Specialized managers
│   ├── main.py         # CLI entry point
│   └── __main__.py     # Module entry point
├── tests/              # Comprehensive test suite (335 tests)
├── docs/               # Documentation
├── config/             # Configuration examples
└── requirements.txt    # Dependencies

Testing

The project uses pytest for testing with comprehensive coverage across all components:

• Unit Tests: Individual component testing
• Integration Tests: Cross-component interaction testing
• Core Tests: Configuration, server, and tool management
• End-to-End Tests: Full MCP server functionality
• Performance Tests: Load testing and benchmarks

Current Status: Comprehensive test coverage across all modules ensuring reliability and maintainability.

# Run all tests
pytest

# Run with coverage reporting
pytest --cov=pythonium --cov-report=html

# Run specific test categories
pytest tests/core/         # Core functionality tests
pytest tests/tools/        # Tool implementation tests
pytest tests/common/       # Common utilities tests

# Quick test run
pytest -q

# Verbose test output
pytest -v

Configuration

Pythonium uses Pydantic-based configuration with support for multiple formats (YAML, JSON, TOML) and environment variable integration:

# config/server.yaml
server:
  name: "Pythonium MCP Server"
  description: "A modular MCP server for AI agents"
  host: "localhost"
  port: 8080
  transport: "stdio"  # stdio, http, websocket

tools:
  # Tool discovery and loading configuration
  auto_discover: true
  categories:
    - "system"
    - "web"
    - "file_operations"

logging:
  level: "INFO"           # DEBUG, INFO, WARNING, ERROR
  format: "structured"    # structured, plain
  output: "console"       # console, file

security:
  authentication: "none"  # none, api_key
  rate_limit:
    enabled: false
    requests_per_minute: 60

Tool Development

Creating a Custom Tool

from pythonium.tools.base import BaseTool, ToolMetadata, ToolParameter, ParameterType
from pythonium.common.base import Result
from pythonium.common.parameters import validate_parameters

class MyCustomTool(BaseTool):
    """A custom tool example with proper parameter validation."""
    
    @property
    def metadata(self) -> ToolMetadata:
        return ToolMetadata(
            name="my_custom_tool",
            description="A custom tool example that demonstrates the framework",
            brief_description="Custom tool example",
            category="custom",
            tags=["example", "custom"],
            parameters=[
                ToolParameter(
                    name="message",
                    type=ParameterType.STRING,
                    description="Message to process",
                    required=True,
                    min_length=1,
                    max_length=1000
                )
            ]
        )
    
    @validate_parameters  # Automatic parameter validation
    async def execute(self, message: str, context: ToolContext) -> Result:
        """Execute the tool with validated parameters."""
        try:
            result = f"Processed: {message}"
            return Result.success_result(
                data={"result": result, "original": message},
                metadata={"tool": "my_custom_tool"}
            )
        except Exception as e:
            return Result.error_result(f"Tool execution failed: {e}")

Tool Registration

Tools are automatically discovered and registered when placed in the appropriate package structure. The tool discovery system handles:

• Automatic tool detection and registration
• Parameter validation and schema generation
• Error handling and logging
• Integration with the MCP protocol

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

For a detailed history of changes, see CHANGELOG.md.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Code Standards

• Follow PEP 8 style guidelines
• Use type hints throughout the codebase
• Maintain comprehensive test coverage
• Document all public APIs with detailed docstrings
• Use conventional commit messages
• Leverage Pydantic for data validation and configuration
• Implement proper async/await patterns for I/O operations

License

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

Support

• Documentation: Available in the docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Official Model Context Protocol SDK and specification
• The open-source Python community
• Pydantic and FastAPI ecosystems for configuration and validation patterns
• Contributors and maintainers

---

Status: Production-ready Beta - Core functionality stable, comprehensive test coverage, active development

Current Version: 0.1.5
Last Updated: July 6, 2025
Maintainer: David Harvey