Dolphin-MCP é uma implementação de código aberto que estende o Protocolo de Contexto de Modelo (MCP) da Anthropic para funcionar com vários modelos de linguagem além do Claude. Este guia técnico irá guiá-lo na configuração e utilização do Dolphin-MCP especificamente com a API da OpenAI, permitindo que você aproveite os modelos GPT através da arquitetura do MCP.
Dolphin-MCP atua como uma camada de tradução entre a especificação do MCP e várias APIs de LLM. Para integração com a OpenAI, ele:
Antes de começar, certifique-se de que você possui:
# Clone o repositório do Dolphin-MCP
git clone https://github.com/cognitivecomputations/dolphin-mcp.git
cd dolphin-mcp
# Crie um ambiente virtual
python -m venv venv
source venv/bin/activate # No Windows: venv\Scripts\activate
# Instale as dependências
pip install -r requirements.txt
# Instale o pacote em modo de desenvolvimento
pip install -e .
Crie um arquivo .env na raiz do seu projeto:
OPENAI_API_KEY=sk-sua-chave-de-api-openai-aqui
MCP_MODEL=gpt-4-0125-preview
MCP_PROVIDER=openai
Crie um arquivo config.json:
{
"provider": "openai",
"model_settings": {
"model": "gpt-4-0125-preview",
"temperature": 0.7,
"max_tokens": 2048
},
"api_config": {
"api_key": "sk-sua-chave-de-api-openai-aqui",
"base_url": "https://api.openai.com/v1",
"timeout": 120
}
}
from dolphin_mcp import DolphinMCP
# Inicializando o cliente
mcp_client = DolphinMCP.from_config("./config.json")
# Criar uma conversa
conversation = mcp_client.create_conversation()
# Adicionar uma mensagem do sistema
conversation.add_system_message("Você é um assistente de IA útil especializado em programação Python.")
# Enviar uma mensagem do usuário e obter uma resposta
response = conversation.add_user_message("Como implemento uma árvore de busca binária em Python?")
# Imprimir a resposta
print(response.content)
from dolphin_mcp import DolphinMCP
from dolphin_mcp.tools import WebSearchTool, CodeExecutionTool
# Inicializar cliente com ferramentas
mcp_client = DolphinMCP.from_config("./config.json")
# Registrar ferramentas
mcp_client.register_tool(WebSearchTool(api_key="sua-chave-api-de-busca-aqui"))
mcp_client.register_tool(CodeExecutionTool())
# Criar conversa com ferramentas habilitadas
conversation = mcp_client.create_conversation()
# Adicionar instruções do sistema para as ferramentas
conversation.add_system_message("""
Você é um assistente de IA com acesso às seguintes ferramentas:
- web_search: Pesquisar na internet por informações atuais
- code_execution: Executar código Python com segurança em um sandbox
Use essas ferramentas quando apropriado para fornecer respostas precisas e úteis.
""")
# Consulta do usuário que requer ferramentas
response = conversation.add_user_message(
"Qual é o clima atual em Nova York? Além disso, você pode me mostrar como calcular o fatorial de um número em Python?"
)
# A resposta incluirá o uso das ferramentas automaticamente
print(response.content)
print("\nExecuções de ferramentas:")
for tool_name, tool_result in response.tool_results.items():
print(f"{tool_name}: {tool_result}")
Se você deseja usar endpoints alternativos compatíveis com OpenAI (como Azure OpenAI ou modelos auto-hospedados), modifique sua configuração:
{
"provider": "openai",
"model_settings": {
"model": "sua-implantação-de-modelo-personalizado",
"temperature": 0.7,
"max_tokens": 2048
},
"api_config": {
"api_key": "sua-chave-api",
"base_url": "https://seu-endpoint-personalizado.com/v1",
"api_version": "2023-07-01-preview", // Para Azure
"api_type": "azure" // Para Azure
}
}
Dolphin-MCP permite que você crie ferramentas personalizadas para modelos OpenAI. Veja como implementar uma ferramenta de calculadora personalizada:
from dolphin_mcp.tools import BaseTool
import math
class CalculatorTool(BaseTool):
name = "calculadora"
description = "Realiza cálculos matemáticos"
async def execute(self, expression: str):
try:
# Cria um ambiente seguro com funções matemáticas limitadas
safe_env = {
"sqrt": math.sqrt,
"sin": math.sin,
"cos": math.cos,
"tan": math.tan,
"pi": math.pi,
"e": math.e
}
# Avalia a expressão no ambiente seguro
result = eval(expression, {"__builtins__": {}}, safe_env)
return str(result)
except Exception as e:
return f"Erro no cálculo: {str(e)}"
@property
def parameters(self):
return {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "A expressão matemática a ser avaliada"
}
},
"required": ["expression"]
}
# Exemplo de uso
mcp_client = DolphinMCP.from_config("./config.json")
mcp_client.register_tool(CalculatorTool())
Para aplicações que requerem respostas em tempo real:
async def stream_response():
mcp_client = DolphinMCP.from_config("./config.json")
conversation = mcp_client.create_conversation()
# Configurar a conversa
conversation.add_system_message("Você é um assistente de IA útil.")
# Transmitir a resposta
async for chunk in conversation.add_user_message_streaming(
"Explique a computação quântica em termos simples."
):
if chunk.type == "content":
print(chunk.content, end="", flush=True)
elif chunk.type == "tool_start":
print(f"\n[Iniciando uso da ferramenta: {chunk.tool_name}]")
elif chunk.type == "tool_result":
print(f"\n[Resultado da ferramenta de {chunk.tool_name}]: {chunk.result}")
elif chunk.type == "error":
print(f"\nErro: {chunk.error}")
print("\nResposta completa.")
# Executar a função assíncrona
import asyncio
asyncio.run(stream_response())
Implemente um tratamento robusto de erros para gerenciar problemas de API:
from dolphin_mcp.exceptions import MCPAPIError, MCPConfigError, MCPTimeoutError
try:
mcp_client = DolphinMCP.from_config("./config.json")
conversation = mcp_client.create_conversation()
response = conversation.add_user_message("Gere uma resposta complexa")
except MCPTimeoutError:
print("A solicitação excedeu o tempo limite. Verifique sua conexão de rede ou aumente o valor de tempo limite.")
except MCPAPIError as e:
print(f"Erro de API: {e.status_code} - {e.message}")
if e.status_code == 429:
print("Limite de taxa excedido. Implemente um retrocesso exponencial.")
except MCPConfigError as e:
print(f"Erro de Configuração: {e}")
except Exception as e:
print(f"Erro inesperado: {e}")
Para ambientes de produção, considere essas otimizações:
# Reuso de sessão para agrupamento de conexões
from dolphin_mcp import DolphinMCP
import aiohttp
async def optimized_mcp_usage():
# Criar uma sessão compartilhada para agrupamento de conexões
async with aiohttp.ClientSession() as session:
mcp_client = DolphinMCP.from_config(
"./config.json",
session=session,
request_timeout=60,
connection_pool_size=10
)
# Processar várias conversas de forma eficiente
tasks = []
for i in range(5):
conversation = mcp_client.create_conversation()
conversation.add_system_message("Você é um assistente útil.")
tasks.append(conversation.add_user_message_async(f"Pergunta {i}: O que é aprendizado de máquina?"))
# Reunir todas as respostas
responses = await asyncio.gather(*tasks)
for i, response in enumerate(responses):
print(f"Resposta {i}: {response.content[:100]}...")
Exemplo de integração com Flask:
from flask import Flask, request, jsonify
from dolphin_mcp import DolphinMCP
app = Flask(__name__)
mcp_client = DolphinMCP.from_config("./config.json")
@app.route("/chat", methods=["POST"])
def chat():
data = request.json
conversation_id = data.get("conversation_id")
message = data.get("message")
# Recuperar ou criar conversa
if conversation_id and conversation_id in active_conversations:
conversation = active_conversations[conversation_id]
else:
conversation = mcp_client.create_conversation()
conversation_id = conversation.id
active_conversations[conversation_id] = conversation
conversation.add_system_message("Você é um assistente de IA útil.")
# Processar a mensagem
response = conversation.add_user_message(message)
return jsonify({
"conversation_id": conversation_id,
"response": response.content,
"tool_results": response.tool_results
})
if __name__ == "__main__":
active_conversations = {}
app.run(debug=True)
| Problema | Solução |
|---|---|
| Erro de "Chave da API inválida" | Verifique se sua chave da API da OpenAI está correta e tem permissões suficientes |
| Limitação de taxa | Implemente um retrocesso exponencial e controle de solicitações |
| Erros de tempo limite | Aumente o tempo limite na configuração ou verifique a conexão com a rede |
| Modelo não encontrado | Verifique se o nome do modelo existe nos modelos disponíveis da OpenAI |
| Limite de tokens excedido | Divida as solicitações em partes menores ou use streaming |
Dolphin-MCP oferece uma maneira flexível e de código aberto de usar modelos da OpenAI com o protocolo MCP. Esta implementação libera os desenvolvedores do bloqueio de fornecedor, mantendo uma interface consistente entre diferentes provedores de LLM. Seguindo os passos deste guia, você pode aproveitar o poder dos modelos GPT através da arquitetura padronizada do MCP.
philschmid.de mostra integrações semelhantes com outros LLMs, e ferramentas como mcpadapt podem ajudar a estender ainda mais as capacidades do Dolphin-MCP.
