convez.ai
MCP ServerIntegração & APIsIntermediário
primodeckers

MCP Server TODO List

primodeckers/exercicio-4.2-mcp-server

MCP server que adapta API REST de TODO list para agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Exercício prático que implementa um MCP server (Model Context Protocol) em Python, expondo as operações de uma API REST de TODO list como tools que agentes de IA podem chamar. O server funciona via stdio e se comunica com a API 4.1 em localhost:8000.

Instalação

$npx convez-ai primodeckers/exercicio-4.2-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Aprender a construir MCP servers em Python com FastMCP
  • Integrar APIs REST existentes com protocolos de IA (MCP/Claude)
  • Entender o padrão stdio para comunicação entre agentes e servidores

Veredito

Exercício educacional bem estruturado que ensina integração prática entre FastMCP e APIs REST via stdio. Útil para quem quer entender como adaptar backends existentes ao ecossistema Claude, mas é um projeto acadêmico com escopo limitado (duas tools).

README

A tradução para o português deste README ainda está na fila.

Exercício 4.2 — MCP server local que consome a sua API (4.1)

Módulo 3 — Construindo interfaces (Aula 6: MCP). Você vai pôr um MCP server na frente da API que construiu no 4.1, expondo tools que um agente de IA pode chamar. O autograder executa o seu MCP server de verdade: ele sobe o server, lista as tools, chama uma delas e confere que o resultado veio da sua API.

Total: 100 pontos — 35 de estrutura no GitHub + 65 de execução real do MCP.


1. Objetivo

No 4.1 você construiu a API REST de uma aplicação de TODO list. Mas um LLM não fala HTTP — ele fala MCP (Model Context Protocol). Neste exercício você cria a camada do meio: um MCP server que expõe duas tools da TODO list e as implementa chamando a sua API REST.

  Agente / LLM   ──MCP──▶   seu MCP server   ──HTTP──▶   sua API 4.1 (localhost:8000)

É o conceito da Aula 6: o MCP padroniza como o agente pede coisas; a sua API continua sendo a fonte do dado. O MCP é o adaptador entre os dois mundos.


2. Pré-requisitos

  • Ter o Exercício 4.1 concluído (a API roda em http://localhost:8000).
  • Python ≥ 3.10 e pip.
  • SDK oficial de MCP para Python: mcp (inclui FastMCP e o cliente stdio).
  • autograde instalado e logado.

Durante a validação do 4.2, a API do 4.1 precisa estar no ar em localhost:8000, porque as tools do MCP chamam ela.


3. O que construir

4.1 servidor_mcp.py — o MCP server

Um server MCP (stdio) que expõe duas tools, ambas chamando a sua API:

ToolAssinaturaO que faz
criar_tarefacriar_tarefa(titulo: str) -> dictfaz POST /tarefas e devolve a tarefa criada
listar_tarefaslistar_tarefas() -> listfaz GET /tarefas e devolve a lista

Esqueleto com FastMCP (você completa a listar_tarefas):

# servidor_mcp.py
import httpx
from mcp.server.fastmcp import FastMCP

API = "http://localhost:8000"
mcp = FastMCP("tarefas-mcp")


@mcp.tool()
def criar_tarefa(titulo: str) -> dict:
    """Cria uma tarefa na API e devolve o objeto criado."""
    resp = httpx.post(f"{API}/tarefas", json={"titulo": titulo}, timeout=10)
    resp.raise_for_status()
    return resp.json()


# TODO: implemente a tool listar_tarefas() -> list que faz GET /tarefas


if __name__ == "__main__":
    mcp.run()  # transporte stdio por padrão

4.2 cliente_teste.py — o teste que o autograder roda

Um script que sobe o servidor_mcp.py via stdio, exercita as tools e imprime no stdout um único envelope JSON (e nada mais):

{
  "tools": ["criar_tarefa", "listar_tarefas"],
  "criar_resultado": {"id": 1, "titulo": "tarefa via mcp", "concluida": false},
  "listar_resultado": [ {"id": 1, "titulo": "tarefa via mcp", "concluida": false} ]
}

Esqueleto com o cliente stdio do SDK:

# cliente_teste.py
import asyncio
import json

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def main() -> dict:
    params = StdioServerParameters(command="python", args=["servidor_mcp.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            nomes = [t.name for t in tools.tools]

            criar = await session.call_tool("criar_tarefa", {"titulo": "tarefa via mcp"})
            listar = await session.call_tool("listar_tarefas", {})

            return {
                "tools": nomes,
                "criar_resultado": json.loads(criar.content[0].text),
                "listar_resultado": json.loads(listar.content[0].text),
            }


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

O formato exato do call_tool(...).content pode variar com a versão do SDK — ajuste o parsing para que o envelope final tenha criar_resultado como um objeto com id/titulo/concluida, e listar_resultado como uma lista. É isso que o autograder confere.


4. Estrutura do repositório

seu-repo/
├── servidor_mcp.py        # MCP server (tools que chamam a API 4.1)
├── cliente_teste.py       # imprime o envelope JSON que o autograder lê
├── requirements.txt       # mcp, httpx
├── README.md
└── .autograde-exercise    # conteúdo: 4.2

requirements.txt:

mcp
httpx

5. Como rodar localmente

  1. Terminal A — suba a API do 4.1 (reinicie para o store ficar limpo):
    uvicorn app.main:app --port 8000     # no repo do 4.1
    
  2. Terminal B — no repo do 4.2:
    pip install -r requirements.txt
    python cliente_teste.py
    
    Deve imprimir o envelope JSON com tools, criar_resultado e listar_resultado.

6. Como o autograder avalia (execução real)

Com a API do 4.1 no ar, no repo do 4.2:

autograde validar 4.2

O CLI roda python cliente_teste.py (rótulo extract: mcp_test), captura o envelope JSON e o backend confere:

CritérioO que verifica
tools_expostostools inclui criar_tarefa e listar_tarefas
tool_criar_chama_apicriar_resultado.titulo == "tarefa via mcp", concluida == false, e existe criar_resultado.id
tool_listar_chama_apilistar_resultado é lista com ≥ 1 item

Como o id/concluida só poderiam vir da sua API REST, passar nesses critérios prova que a tool realmente chamou a API — não devolveu um valor fixo.


7. Rubrica (100 pts)

Estrutura no GitHub — 35 pts

CritérioPtsComo passa
repo_publico5repositório existe e é público
tem_servidor_mcp8servidor_mcp.py existe e não está vazio
tem_cliente_teste7cliente_teste.py existe e não está vazio
tem_requirements5requirements.txt existe e não está vazio
tem_readme2README.md presente
commits_min4≥ 3 commits
pr_descritivo4≥ 1 PR com título descritivo

Execução real do MCP — 65 pts

CritérioPtsComo passa
tools_expostos20server expõe criar_tarefa e listar_tarefas
tool_criar_chama_api30criar_tarefa cria via API e devolve {id, titulo, concluida}
tool_listar_chama_api15listar_tarefas devolve a lista (≥ 1) da API

8. Troubleshooting

SintomaCausa provávelCorreção
tool_criar_chama_api zeradoAPI 4.1 não está no arsuba uvicorn app.main:app --port 8000 no repo do 4.1
cliente_teste.py imprime texto extralogs/prints antes do JSONimprima só json.dumps(...) no stdout (mande logs pro stderr)
tools_expostos falhanome de tool diferenteas tools precisam se chamar exatamente criar_tarefa e listar_tarefas
criar_resultado sem idtool não chamou a API (devolveu stub)a tool tem que fazer o POST de verdade e devolver o JSON da API
timeout na validaçãoserver demora a subirmantenha o cliente_teste.py enxuto; evite trabalho pesado no import

9. Reflexão (para o seu README)

No 4.1 o cliente precisava falar HTTP. No 4.2, o agente só precisa saber que existe uma tool criar_tarefa(titulo). O que o MCP escondeu? Em uma frase: qual detalhe da sua API o MCP tornou irrelevante para quem chama? (Esse é o ganho de abstração da Aula 6.)

Ver o original no GitHub

Bom para

Relacionados