Vestuário MCP

Servidor MCP em memória que simula o backend de um e-commerce de roupas: catálogo, carrinho com reserva de estoque e pedidos. Feito com o MCP Python SDK v2 (mcp==2.3.0), em que o antigo FastMCP agora se chama MCPServer.

⚠️ Segurança: o modo HTTP não tem autenticação. Qualquer pessoa com a URL do ngrok pode chamar as tools. Encerre o túnel ao terminar.

💻 Pré-requisitos

Antes de começar, verifique se você tem:

• Python >= 3.11.

• pip >= 25.1 (necessário para a opção --group).

• Opcional: Node.js (para o MCP Inspector), ngrok e uv.

Related MCP server: Commerce MCP Server

🚀 Instalando

Clone o repositório e entre na pasta:

git clone https://github.com/nilsond/guilda-inovacao-criando-mcp.git
cd guilda-inovacao-criando-mcp

Com venv + pip (é o que a configuração do Kiro abaixo usa):

python3 -m venv .venv && .venv/bin/pip install -e . --group dev

Ou, como alternativa, com uv:

uv sync

Com uv, troque .venv/bin/python por uv run nos comandos abaixo.

☕ Usando

O servidor expõe:

Estoque por tamanho: disponível = estoque físico − reservado.

Erros de negócio (produto inexistente, tamanho inválido, estoque insuficiente etc.) voltam como resultado com is_error=true e uma mensagem em PT-BR, para o LLM conseguir se corrigir.

MCP Inspector via STDIO

npx @modelcontextprotocol/inspector .venv/bin/python server_mcp.py   # com uv: uv run mcp dev server_mcp.py

O Inspector abre no navegador. Explore as abas Tools, Resources e Prompts. O mcp dev do SDK chama o uv por baixo, então sem uv use o npx direto.

HTTP local

.venv/bin/python server_mcp.py --transport http           # http://127.0.0.1:8000/mcp
npx @modelcontextprotocol/inspector                       # em outro terminal

No Inspector, escolha Streamable HTTP e use a URL http://127.0.0.1:8000/mcp.

Remoto via ngrok

ngrok http 8000                                            # anote o host, ex.: abc123.ngrok-free.app
.venv/bin/python server_mcp.py --transport http --public-host abc123.ngrok-free.app

No Inspector, conecte em https://abc123.ngrok-free.app/mcp.

O --public-host (ou a variável PUBLIC_HOST) é obrigatório nesse cenário. O SDK ativa uma proteção contra DNS rebinding que responde 421 Invalid Host header para qualquer host fora da allowlist, e o ngrok repassa o host público.

Kiro

Local (STDIO): crie o arquivo .kiro/settings/mcp.json no workspace com o conteúdo abaixo, trocando /caminho/para/guilda-inovacao-criando-mcp pelo caminho onde você clonou o repositório. O servidor aparece no painel MCP do Kiro; se precisar, reconecte por esse painel. autoApprove está vazio, então cada chamada de tool pede confirmação.

{
  "mcpServers": {
    "vestuario-mcp": {
      "command": "/caminho/para/guilda-inovacao-criando-mcp/.venv/bin/python",
      "args": ["/caminho/para/guilda-inovacao-criando-mcp/server_mcp.py"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Com uv, a entrada fica assim:

"vestuario-mcp": {
  "command": "uv",
  "args": ["--directory", "/caminho/para/guilda-inovacao-criando-mcp", "run", "server_mcp.py"]
}

Remoto (ngrok): o Kiro aceita servidores remotos pelo campo url (documentação de configuração, anúncio de remote MCP). Com o túnel e o servidor HTTP no ar, adicione:

"vestuario-mcp-remoto": {
  "url": "https://abc123.ngrok-free.app/mcp"
}

Se o cliente não conectar, use a ponte mcp-remote:

"vestuario-mcp-remoto": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://abc123.ngrok-free.app/mcp"]
}

Exemplos de uso

Com o servidor conectado ao Kiro (ou a outro cliente MCP), experimente:

1. "Quais casacos vocês têm e quanto custam?"

2. "Monte um look casual para um happy hour" (ou use o prompt recomendar_look)

3. "Adicione o look ao carrinho da sessão demo, tamanho M"

4. "Mostre o estoque da jaqueta no tamanho M" (a reserva aparece)

5. "Qual é a política de trocas?" (resource)

6. "Finalize o pedido para Av. Paulista, 1000 - Bela Vista, São Paulo/SP"

O estado vive na memória e é zerado sempre que o servidor reinicia.

Exemplo mínimo

examples/hello.py é um servidor MCP com uma única tool (somar), comentado linha a linha. Bom ponto de partida para entender o MCPServer antes de olhar o projeto completo:

npx @modelcontextprotocol/inspector .venv/bin/python examples/hello.py

Guias

• docs/01-criando-o-servidor.md: criar o projeto do zero, passo a passo

• docs/02-expondo-com-ngrok.md: expor o servidor com ngrok

• docs/03-conectando-clientes.md: usar o servidor no Kiro e no MCP Inspector

🧪 Testes

.venv/bin/python -m pytest        # ou: uv run pytest
.venv/bin/python -m pytest -q     # saída resumida

Os testes cobrem as regras de negócio (inclusive concorrência pela última unidade), as tools, o resource e o prompt via cliente MCP em memória, o servidor HTTP real com o bloqueio/liberação do host do ngrok, a CLI e o exemplo examples/hello.py.

📁 Estrutura do projeto

.
├── server_mcp.py              # CLI: --transport stdio|http, --host, --port, --public-host
├── src/vestuario_mcp/
│   ├── __init__.py            # exporta build_server e Loja
│   ├── models.py              # tipos e modelos Pydantic (viram structured output)
│   ├── data.py                # catálogo mock (11 produtos) e política de trocas
│   ├── services.py            # regras de negócio (classe Loja, com lock)
│   └── server.py              # build_server(): tools, resource e prompt
├── tests/                     # pytest: serviços, MCP em memória, CLI/HTTP e exemplos
├── examples/
│   └── hello.py               # servidor MCP mínimo
├── docs/
│   ├── 01-criando-o-servidor.md
│   ├── 02-expondo-com-ngrok.md
│   └── 03-conectando-clientes.md
├── pyproject.toml
├── LICENSE
└── README.md

📫 Contribuindo

Para contribuir com o projeto, siga estas etapas:

1. Bifurque este repositório.

2. Crie um branch: git checkout -b <nome_branch>.

3. Faça suas alterações e confirme-as: git commit -m '<mensagem_commit>'

4. Envie para o branch original: git push origin <nome_branch>

5. Crie a solicitação de pull.

Como alternativa, consulte a documentação do GitHub em como criar uma solicitação pull.

🤝 Colaboradores

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.