# Berry MCP Server
[](https://github.com/richinex/berry-mcp/actions/workflows/ci.yml)
[](https://github.com/richinex/berry-mcp/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/uv)
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
```bash
# 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
```python
# 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
```bash
# 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`:
```json
{
"inputs": [],
"servers": {
"my-custom-tools": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "-m", "berry_mcp"],
"env": {
"BERRY_MCP_TOOLS_PATH": "my_tools"
}
}
}
}
```
## 📖 Documentation
- **[VS Code Configuration Guide](docs/VSCODE_CONFIGURATION.md)** - Complete setup instructions
- **[Tool Development Guide](docs/TOOL_DEVELOPMENT.md)** - Create custom tools
- **[API Documentation](docs/API.md)** - 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
```bash
BERRY_MCP_TOOLS_PATH="my_tools,web_tools,data_processors" uv run python -m berry_mcp
```
### HTTP Server Mode
```bash
uv run python -m berry_mcp --transport http --port 8080
```
### Environment Configuration
```bash
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 [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
- 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!**
