MCP API Server com Ollama Chat

Este projeto implementa um MCP (Model Context Protocol) Server em .NET que consulta dados de uma API externa, integrado com Ollama para chat com IA local.

Arquitetura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Chat Client   │────▶│     Ollama      │     │   API Externa   │
│    (.NET 8)     │     │  (llama3.2 ou   │     │ (JSONPlaceholder)│
│                 │     │   phi3:mini)    │     │                 │
└────────┬────────┘     └─────────────────┘     └────────▲────────┘
         │                                               │
         │ MCP Protocol (JSON-RPC)                       │
         ▼                                               │
┌─────────────────┐                                      │
│   MCP Server    │──────────────────────────────────────┘
│    (.NET 8)     │
└─────────────────┘

Ferramentas MCP Disponíveis

| Ferramenta | Descrição | |------------|-----------| | get_users | Obtém lista de todos os usuários | | get_user_by_id | Obtém usuário por ID | | get_posts | Obtém lista de todos os posts | | get_post_by_id | Obtém post por ID | | get_posts_by_user | Obtém posts de um usuário | | get_comments | Obtém comentários de um post |

Pré-requisitos

Docker e Docker Compose
GPU NVIDIA (opcional, para melhor performance)
Mínimo para versão CPU: 4GB RAM, 2 CPUs, 10GB disco

Execução

Com GPU NVIDIA

docker-compose -f docker-compose.gpu.yml up --build

Apenas CPU (Otimizado para Recursos Mínimos)

Usa llama3.2:3b (2GB, com suporte a tool calling) e imagens Alpine Linux:

docker-compose -f docker-compose.cpu.yml up --build

Recursos utilizados:

Ollama: 2-4GB RAM, 2 CPUs
MCP Server: 128-256MB RAM, 0.5 CPU
Chat Client: 128-256MB RAM, 0.5 CPU

Interagir com o Chat

Após iniciar os containers, conecte-se ao chat client:

docker attach chat-client

Exemplos de Uso

Você: Poderia pegar o usuário id 1 e fazer uma frase de apreesentacao com os dados?
Assistente: [Chamando ferramenta: get_user_by_id]
Assistente: "Olá, meu nome é Leanne Graham. Sou um usuário com o ID 1. Sinto-me feliz em conhecê-lo! Minha rua é a Kulas Light, apartamento 556, na cidade de Gwenborough. Você pode me encontrar no site hildegard.org ou ligar para mim no número 1-770-736-8031 x56442."

Configuração

Variáveis de Ambiente

| Variável | Descrição | Padrão | |----------|-----------|--------| | OLLAMA_URL | URL do servidor Ollama | http://localhost:11434 | | OLLAMA_MODEL | Modelo do Ollama | llama3.2 (GPU) / llama3.2:3b (CPU) | | API_BASE_URL | URL base da API | https://jsonplaceholder.typicode.com | | MCP_SERVER_HOST | Host do MCP Server | mcp-server (Docker) / localhost | | MCP_SERVER_PORT | Porta do MCP Server | 5000 | | USE_TCP | Habilitar modo TCP no MCP Server | true (Docker) |

Modelos Ollama Disponíveis

| Modelo | Tamanho | Tool Calling | Uso Recomendado | |--------|---------|--------------|----------------| | llama3.2:3b | ~2GB | ✅ Sim | CPU com recursos limitados (recomendado) | | llama3.2 | ~2GB | ✅ Sim | CPU/GPU balanceado | | mistral | ~4GB | ✅ Sim | CPU/GPU com mais recursos | | phi3:mini | ~3.8GB | ⚠️ Limitado | Não recomendado para MCP | | llama3.2:1b | ~1.3GB | ❌ Não | Não suporta tool calling | | tinyllama | ~637MB | ❌ Não | Não suporta tool calling |

Importante: Para usar MCP tools, escolha um modelo com suporte a tool calling (function calling).

Arquitetura de Comunicação

O projeto usa comunicação TCP entre os containers:

MCP Server: Escuta na porta 5000 usando TCP sockets
Chat Client: Conecta-se ao MCP Server via TCP
Protocolo: JSON-RPC 2.0 sobre TCP

Esta abordagem é mais eficiente e confiável que docker exec ou pipes.

Estrutura do Projeto

mcp/
├── docker-compose.yml          # Compose com GPU
├── docker-compose.cpu.yml      # Compose CPU otimizado
├── McpServer/                  # MCP Server em .NET
│   ├── Dockerfile              # Imagem padrão
│   ├── Dockerfile.alpine       # Imagem Alpine (menor)
│   ├── McpServer.csproj
│   ├── Program.cs
│   ├── McpHostedService.cs
│   ├── Models/
│   │   └── McpModels.cs
│   └── Services/
│       ├── ApiService.cs
│       └── McpToolsHandler.cs
└── ChatClient/                 # Cliente de Chat
    ├── Dockerfile              # Imagem padrão
    ├── Dockerfile.alpine       # Imagem Alpine (menor)
    ├── ChatClient.csproj
    ├── Program.cs
    ├── Models/
    │   ├── McpClientModels.cs
    │   └── OllamaModels.cs
    └── Services/
        ├── ChatService.cs
        ├── McpClientService.cs
        └── OllamaService.cs

Desenvolvimento Local

MCP Server

cd McpServer
dotnet run

Chat Client

cd ChatClient
export MCP_SERVER_PATH="../McpServer"
export OLLAMA_URL="http://localhost:11434"
dotnet run

Customização da API

Para usar sua própria API, modifique:

McpServer/Services/ApiService.cs - Adicione métodos para sua API
McpServer/Services/McpToolsHandler.cs - Registre as novas ferramentas
Configure API_BASE_URL no docker-compose

Licença

MIT

MCP Servers