MCP Fundamentos: tools, resources e prompts do protocolo

# O fluxo completo de uma chamada MCP:

# 1. Host inicializa o servidor MCP (como subprocesso ou via SSE)
# 2. Claude recebe a lista de tools/resources disponíveis no contexto
# 3. Durante a conversa, Claude decide usar uma tool

# Mensagem do host para o servidor MCP (JSON-RPC 2.0):
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_github_issues",
    "arguments": {
      "repo": "anthropics/claude-code",
      "query": "MCP timeout",
      "state": "open"
    }
  }
}

# Resposta do servidor MCP para o host:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{"number": 142, "title": "MCP server timeout after 30s..."}]"
      }
    ]
  }
}

# MCP tem 3 primitivos que servidores podem expor:

# ─── 1. TOOLS ────────────────────────────────────────────
# Funções que Claude chama — dinâmicas, podem ter side effects
# Claude decide quando chamar baseado na description

{
  "name": "criar_issue_github",
  "description": "Cria uma nova issue no repositório GitHub especificado.
                  Use quando o usuário pedir para criar, abrir ou registrar
                  um bug, feature request ou tarefa no GitHub.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "repo": {
        "type": "string",
        "description": "Repositório no formato owner/repo (ex: anthropics/claude)"
      },
      "title": {"type": "string", "description": "Título da issue"},
      "body": {"type": "string", "description": "Descrição detalhada em Markdown"},
      "labels": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Labels para aplicar (ex: ['bug', 'priority:high'])"
      }
    },
    "required": ["repo", "title", "body"]
  }
}

# ─── 2. RESOURCES ─────────────────────────────────────────
# Dados que Claude pode ler como contexto — URI addressable
# Não têm argumentos — Claude faz "get" pelo URI

{
  "uri": "github://anthropics/claude/readme",
  "name": "README do repositório Claude",
  "description": "Conteúdo atual do README.md do repositório principal",
  "mimeType": "text/markdown"
}

# Resource com template (URI dinâmico):
{
  "uriTemplate": "github://{owner}/{repo}/issues/{issue_number}",
  "name": "Detalhes de issue do GitHub",
  "description": "Lê o conteúdo completo de uma issue específica incluindo comentários"
}

# ─── 3. PROMPTS ───────────────────────────────────────────
# Templates de prompt reutilizáveis — Claude os invoca como comandos
# Aparecem como slash commands no Claude Desktop e similares

{
  "name": "code_review",
  "description": "Inicia um code review estruturado do diff atual",
  "arguments": [
    {"name": "focus", "description": "Área de foco: security|performance|style|all", "required": false}
  ]
}

# Servidor MCP mínimo com Python (usando mcp library):
# pip install mcp

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
import asyncio, json

app = Server("meu-servidor-mcp")

# ─── Definir as tools disponíveis ────────────────────────
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="buscar_produto",
            description="""Busca um produto pelo ID ou nome parcial no catálogo.
                          Use quando o usuário mencionar um produto específico,
                          pedir preço, verificar estoque ou obter detalhes de item.""",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "ID do produto (ex: PROD-123) ou nome parcial"
                    },
                    "tipo": {
                        "type": "string",
                        "enum": ["id", "nome"],
                        "description": "Tipo de busca: 'id' para código exato, 'nome' para busca textual"
                    }
                },
                "required": ["query", "tipo"]
            }
        )
    ]

# ─── Implementar a lógica da tool ─────────────────────────
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "buscar_produto":
        query = arguments["query"]
        tipo = arguments["tipo"]

        # Sua lógica de negócio aqui:
        resultado = buscar_no_banco(query, tipo)  # função sua

        if not resultado:
            return [types.TextContent(
                type="text",
                text=json.dumps({"erro": f"Produto '{query}' não encontrado"})
            )]

        return [types.TextContent(
            type="text",
            text=json.dumps(resultado)
        )]

    raise ValueError(f"Tool desconhecida: {name}")

# ─── Iniciar o servidor via stdio ─────────────────────────
async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

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

# .claude/mcp.json — configuração dos servidores MCP do projeto

{
  "mcpServers": {
    "meu-servidor": {
      "command": "python",
      "args": ["mcp_server/main.py"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}",
        "API_KEY": "${MINHA_API_KEY}"
      }
    },

    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },

    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${DATABASE_URL}"
      }
    }
  }
}

# Variáveis de ambiente: nunca commite segredos no mcp.json.
# Use ${VAR_NAME} — o host substitui pelo valor do ambiente.
# Adicione mcp.json ao .gitignore se contiver caminhos sensíveis.

# Verificar conexão no Claude Code:
claude
> "Liste as tools disponíveis"
# Claude vai listar todas as tools dos servidores conectados

# Verificar recursos:
> "Quais resources estão disponíveis neste servidor?"

# Depurar problemas de conexão:
# Claude Code mostra erros de inicialização de MCP no início da sessão