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 GitHubExercí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-server1 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
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(incluiFastMCPe o cliente stdio). autogradeinstalado 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:
| Tool | Assinatura | O que faz |
|---|---|---|
criar_tarefa | criar_tarefa(titulo: str) -> dict | faz POST /tarefas e devolve a tarefa criada |
listar_tarefas | listar_tarefas() -> list | faz 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(...).contentpode variar com a versão do SDK — ajuste o parsing para que o envelope final tenhacriar_resultadocomo um objeto comid/titulo/concluida, elistar_resultadocomo 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
- 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 - Terminal B — no repo do 4.2:
Deve imprimir o envelope JSON compip install -r requirements.txt python cliente_teste.pytools,criar_resultadoelistar_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ério | O que verifica |
|---|---|
tools_expostos | tools inclui criar_tarefa e listar_tarefas |
tool_criar_chama_api | criar_resultado.titulo == "tarefa via mcp", concluida == false, e existe criar_resultado.id |
tool_listar_chama_api | listar_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ério | Pts | Como passa |
|---|---|---|
repo_publico | 5 | repositório existe e é público |
tem_servidor_mcp | 8 | servidor_mcp.py existe e não está vazio |
tem_cliente_teste | 7 | cliente_teste.py existe e não está vazio |
tem_requirements | 5 | requirements.txt existe e não está vazio |
tem_readme | 2 | README.md presente |
commits_min | 4 | ≥ 3 commits |
pr_descritivo | 4 | ≥ 1 PR com título descritivo |
Execução real do MCP — 65 pts
| Critério | Pts | Como passa |
|---|---|---|
tools_expostos | 20 | server expõe criar_tarefa e listar_tarefas |
tool_criar_chama_api | 30 | criar_tarefa cria via API e devolve {id, titulo, concluida} |
tool_listar_chama_api | 15 | listar_tarefas devolve a lista (≥ 1) da API |
8. Troubleshooting
| Sintoma | Causa provável | Correção |
|---|---|---|
tool_criar_chama_api zerado | API 4.1 não está no ar | suba uvicorn app.main:app --port 8000 no repo do 4.1 |
cliente_teste.py imprime texto extra | logs/prints antes do JSON | imprima só json.dumps(...) no stdout (mande logs pro stderr) |
tools_expostos falha | nome de tool diferente | as tools precisam se chamar exatamente criar_tarefa e listar_tarefas |
criar_resultado sem id | tool 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ção | server demora a subir | mantenha 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.)