mcp-server-demo by EngDiego - MCP Server

MCP Server Demo

Este projeto demonstra a implementação de um servidor e cliente MCP (Model Context Protocol) utilizando Python e a biblioteca mcp[cli].

📋 Sobre o Projeto

O Model Context Protocol (MCP) é um protocolo que permite a comunicação entre diferentes sistemas para compartilhamento de contexto e ferramentas. Este demo inclui:

Server: Um servidor MCP que expõe ferramentas de cálculo matemático
Client: Um cliente que se conecta ao servidor e utiliza as ferramentas disponíveis

Ferramentas Implementadas

O servidor expõe as seguintes ferramentas:

add(a, b): Soma dois números inteiros
sub(a, b): Subtrai dois números inteiros

🚀 Passo a Passo da Implementação

1. Configuração do Ambiente WSL

# Instalar WSL (Windows Subsystem for Linux)
wsl --install

# Acessar o ambiente WSL
wsl

2. Criação do Projeto

# Inicializar projeto com uv
uv init mcp-server-demo

# Navegar para o diretório
cd mcp-server-demo

# Criar ambiente virtual
uv venv

# Adicionar dependências MCP
uv add "mcp[cli]"

3. Criação dos Arquivos

# Criar arquivos do servidor e cliente
touch server.py && touch client.py

# Abrir projeto no VS Code
code .

4. Implementação do Servidor (server.py)

O servidor utiliza FastMCP para criar uma API simples:

from mcp.server.fastmcp import FastMCP

# Criar servidor MCP
mcp = FastMCP("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
def sub(a: int, b: int) -> int:
    """Sub two numbers"""
    return a - b

if __name__ == "__main__":
    # Iniciar servidor com transporte SSE
    mcp.run(transport='sse')

5. Implementação do Cliente (client.py)

O cliente se conecta ao servidor via SSE (Server-Sent Events):

from mcp import ClientSession
from mcp.client.sse import sse_client
import asyncio

async def mcpclient():
    async with sse_client(url="http://localhost:8000/sse") as streams:
        async with ClientSession(*streams) as session:
            await session.initialize()
            
            # Listar ferramentas disponíveis
            tools = await session.list_tools()
            print("Available tools:", tools)
            
            # Executar ferramenta
            result = await session.call_tool("sub", arguments={"a": 4, "b": 5})
            print("Result of sub(4, 5):", result.content[0].text)

if __name__ == "__main__":
    asyncio.run(mcpclient())

🧪 Executando os Testes

Executar o Servidor

# Terminal 1: Iniciar o servidor
uv run server.py

O servidor será iniciado em http://localhost:8000 com o endpoint SSE em /sse.

Executar o Cliente

# Terminal 2: Executar o cliente
uv run client.py

Resultado Esperado

O cliente deve conectar-se ao servidor e executar a operação de subtração:

Available tools: [lista das ferramentas disponíveis]
Result of sub(4, 5): -1

🔧 Testes Entre Server e Client

1. Teste de Conectividade

Objetivo: Verificar se o cliente consegue se conectar ao servidor
Método: O cliente estabelece conexão SSE com o servidor
Validação: Conexão bem-sucedida sem erros

2. Teste de Descoberta de Ferramentas

Objetivo: Verificar se o cliente consegue listar as ferramentas disponíveis
Método: Chamar session.list_tools()
Validação: Retorno da lista contendo add e sub

3. Teste de Execução de Ferramentas

Objetivo: Verificar se as ferramentas podem ser executadas corretamente
Método: Chamar session.call_tool() com diferentes argumentos
Validação: Resultado matemático correto

4. Casos de Teste

Ferramenta	Entrada	Resultado Esperado
`add`	a=5, b=3	8
`add`	a=-2, b=7	5
`sub`	a=10, b=4	6
`sub`	a=4, b=5	-1

📁 Estrutura do Projeto

mcp-server-demo/
├── client.py          # Cliente MCP
├── server.py          # Servidor MCP
├── pyproject.toml     # Configuração do projeto
├── README.md          # Documentação
└── uv.lock           # Lock file das dependências

🔍 Troubleshooting

Problemas Comuns

Erro de conexão: Verificar se o servidor está rodando na porta 8000
Módulo não encontrado: Executar uv add "mcp[cli]" novamente
Permissões WSL: Garantir que o ambiente virtual está ativado

Logs e Debug

Para debug mais detalhado, adicione logs nos pontos críticos:

import logging
logging.basicConfig(level=logging.DEBUG)

🛠️ Próximos Passos

Adicionar mais ferramentas matemáticas (multiplicação, divisão)
Implementar tratamento de erros
Adicionar testes unitários
Documentar API com OpenAPI/Swagger

📚 Referências

👨‍💻 Desenvolvido por

Diego Soprana Gomes

Desenvolvedor especializado em implementação de protocolos de comunicação e sistemas distribuídos.