richinex/berry-mcp

Berry MCP Server

A universal Model Context Protocol (MCP) server framework that makes it easy to create and deploy custom tool servers for AI assistants like Claude.

✨ Features

• 🔧 Universal Framework: Create MCP servers for any type of tools
• 🎯 Simple Tool Creation: Decorator-based tool registration with automatic JSON schema generation
• 🔌 Plugin Architecture: Load tools from any Python module or package
• 🚀 Multiple Transports: Support for stdio and HTTP/SSE communication
• ⚙️ Flexible Configuration: Environment variables and command-line options
• 📝 Auto-Documentation: Automatic tool discovery and schema generation
• 🔒 Type Safety: Full type annotation support with validation

🚀 Quick Start

Installation

# Install from PyPI (when published)
uv add berry-mcp

# Or install from source
git clone https://github.com/richinex/berry-mcp-server.git
cd berry-mcp-server
uv pip install -e .

Create Your First Tool

# my_tools.py
from berry_mcp.tools.decorators import tool

@tool(description="Add two numbers together")
def add_numbers(a: float, b: float) -> float:
    """Add two numbers and return the result"""
    return a + b

@tool(description="Generate a greeting message")  
def greet(name: str, title: str = "friend") -> str:
    """Generate a personalized greeting"""
    return f"Hello {title} {name}!"

Run Your Server

# Load your custom tools
BERRY_MCP_TOOLS_PATH=my_tools uv run python -m berry_mcp

# Or run with built-in example tools
uv run python -m berry_mcp

VS Code Integration

Add to your .vscode/mcp.json:

{
  "inputs": [],
  "servers": {
    "my-custom-tools": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "berry_mcp"],
      "env": {
        "BERRY_MCP_TOOLS_PATH": "my_tools"
      }
    }
  }
}

📖 Documentation

• - Complete setup instructions
• - Create custom tools
• - Technical reference

🛠️ Built-in Tools

Berry MCP comes with example tools to get you started:

• Math Operations: add_numbers, generate_random
• Text Processing: format_text, find_replace_text, encode_decode_text
• System Info: get_system_info, generate_uuid
• Data Tools: validate_json, generate_report
• Async Examples: async_process_text

🔧 Advanced Usage

Multiple Tool Sources

BERRY_MCP_TOOLS_PATH="my_tools,web_tools,data_processors" uv run python -m berry_mcp

HTTP Server Mode

uv run python -m berry_mcp --transport http --port 8080

Environment Configuration

export BERRY_MCP_SERVER_NAME="my-custom-server"
export BERRY_MCP_LOG_LEVEL="DEBUG"
export BERRY_MCP_TOOLS_PATH="my_tools,another_module.tools"
uv run python -m berry_mcp

🏗️ Architecture

Berry MCP follows SOLID principles with a clean, extensible architecture:

• MCPServer: Core server orchestration
• ToolRegistry: Plugin-based tool management
• Transport Layer: Abstracted communication (stdio/HTTP)
• Protocol Handler: JSON-RPC message processing
• Tool Framework: Decorator-based tool creation

📋 Requirements

• Python 3.10+
• MCP protocol support
• Type annotations for automatic schema generation

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the existing patterns
4. Add tests for new functionality
5. Run the test suite: pytest tests/
6. Submit a pull request

📝 License

MIT License - see file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol
• Inspired by the need for easy MCP server creation
• Following clean code principles and design patterns

🚀 Start building your custom MCP tools today with Berry MCP Server!