Berry MCP Server

Berry MCP Server

Um framework de servidor Model Context Protocol (MCP) universal que facilita a criação e implantação de servidores de ferramentas personalizados para assistentes de IA como o Claude.

✨ Recursos

• 🔧 Framework Universal: Crie servidores MCP para qualquer tipo de ferramenta
• 🎯 Criação Simples de Ferramentas: Registro de ferramentas baseado em decoradores com geração automática de esquema JSON
• 🔌 Arquitetura de Plugins: Carregue ferramentas de qualquer módulo ou pacote Python
• 🚀 Múltiplos Transportes: Suporte para comunicação stdio e HTTP/SSE
• ⚙️ Configuração Flexível: Variáveis de ambiente e opções de linha de comando
• 📝 Documentação Automática: Descoberta automática de ferramentas e geração de esquemas
• 🔒 Segurança de Tipos: Suporte completo a anotações de tipo com validação

🚀 Início Rápido

Instalação

# 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 .

Crie Sua Primeira Ferramenta

# 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}!"

Execute Seu Servidor

# 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

Integração com VS Code

Adicione ao seu .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"
      }
    }
  }
}

📖 Documentação

• Guia de Configuração do VS Code - Instruções completas de configuração
• Guia de Desenvolvimento de Ferramentas - Crie ferramentas personalizadas
• Documentação da API - Referência técnica

🛠️ Ferramentas Integradas

O Berry MCP vem com ferramentas de exemplo para você começar:

• Operações Matemáticas: add_numbers, generate_random
• Processamento de Texto: format_text, find_replace_text, encode_decode_text
• Informações do Sistema: get_system_info, generate_uuid
• Ferramentas de Dados: validate_json, generate_report
• Exemplos Assíncronos: async_process_text

🔧 Uso Avançado

Múltiplas Fontes de Ferramentas

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

Modo de Servidor HTTP

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

Configuração de Ambiente

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

🏗️ Arquitetura

O Berry MCP segue princípios SOLID com uma arquitetura limpa e extensível:

• MCPServer: Orquestração central do servidor
• ToolRegistry: Gerenciamento de ferramentas baseado em plugins
• Transport Layer: Comunicação abstraída (stdio/HTTP)
• Protocol Handler: Processamento de mensagens JSON-RPC
• Tool Framework: Criação de ferramentas baseada em decoradores

📋 Requisitos

• Python 3.10+
• Suporte ao protocolo MCP
• Anotações de tipo para geração automática de esquemas

🤝 Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade: git checkout -b feature/amazing-feature
3. Faça suas alterações seguindo os padrões existentes
4. Adicione testes para novas funcionalidades
5. Execute a suíte de testes: pytest tests/
6. Envie um pull request

📝 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🙏 Agradecimentos

• Construído sobre o Model Context Protocol
• Inspirado pela necessidade de criação fácil de servidores MCP
• Seguindo princípios de código limpo e padrões de design

---

🚀 Comece a criar suas ferramentas MCP personalizadas hoje com o Berry MCP Server!