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.

Related MCP server: exercicio-4.2-todo-mcp

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:

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:

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

Execução real do MCP — 65 pts

8. Troubleshooting

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.)