# workshop-27-08-26

![Licença: Unlicense](https://img.shields.io/badge/licen%C3%A7a-Unlicense-blue)
![Protocolo: MCP](https://img.shields.io/badge/protocolo-MCP-8A2BE2)
![Runtime: Node.js](https://img.shields.io/badge/runtime-Node.js-339933)
![Tema: Agentes de IA](https://img.shields.io/badge/tema-Agentes%20de%20IA-0A66C2)

Exemplo de servidor MCP para o workshop do bootcamp _AWS AI FDE for Commerce_ de 27/08/2026.

Aqui você encontra três servidores MCP de exemplo (_stdio_, _HTTP_ e _Express_), _tools_ customizadas para um cliente fictício e um agente **Mentor** que ajuda a entender tudo isso.

## 🚀 Começo Rápido

```bash
git clone https://github.com/leostacowskicompasso/workshop-27-08-26.git
cd workshop-27-08-26
npm install
npm i -g opencode-ai
opencode
```

O agente _Mentor_ já vem selecionado por padrão. A primeira execução do OpenCode baixa as dependências dele, então aguarde. O servidor _stdio_ é iniciado pelo próprio OpenCode; os servidores _HTTP_ e _Express_ você inicia na mão (veja [Rodando os Servidores](#rodando-os-servidores)).

## 🧩 O que é MCP?

O [MCP (Model Context Protocol)](https://modelcontextprotocol.io/specification/2026-07-28) é um protocolo _open-source_ de comunicação entre sistemas, que permite a troca de informações de dados/contexto entre diferentes aplicações (majoritariamente de IA).

Usando esse protocolo, é possível que um sistema de IA (como uma aplicação de agentes) consuma/disponibilize informações contextuais de/para outro sistema, permitindo que modelos operem com mais certeza e relevância.

Usando a [analogia do USB-C](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro):

> Pense no MCP como uma porta USB-C para aplicações de IA. Assim como o USB-C fornece uma maneira padronizada de conectar dispositivos eletrônicos, o MCP fornece uma maneira padrão de conectar aplicações de IA a outros sistemas.

```mermaid
flowchart LR
    A["Agente de IA<br/>(OpenCode)"] <-->|"MCP via stdio"| S1["Servidor stdio"]
    A <-->|"MCP via HTTP (8787)"| S2["Servidor HTTP"]
    A <-->|"MCP via HTTP (8788)"| S3["Servidor Express"]
    S1 --> T["tools/index.js<br/>nordesul-delivery · deploy · reference · status"]
    S2 --> T
    S3 --> T
```

## 🔌 SDK e Transportes

O protocolo suporta diferentes opções de SDKs (Software Development Kits), que podem ser usados para implementar MCP em diferentes linguagens/frameworks. Encontre a lista completa aqui: [Available SDKs](https://modelcontextprotocol.io/docs/2026-07-28/sdk#available-sdks).

Focando no contexto do workshop, exploramos as opções de transporte mais comuns/populares para Node.js:

| Transporte  | Como funciona                                                                  | Onde está          | Como inicia no workshop                    |
| ----------- | ------------------------------------------------------------------------------ | ------------------ | ------------------------------------------ |
| **stdio**   | O servidor roda como processo filho e troca mensagens via _stdin_ e _stdout_   | `servers/stdio`    | O OpenCode inicia sozinho (`stdio_mcp`)    |
| **HTTP**    | Um servidor que recebe e envia mensagens via requisições HTTP para vários clientes ao mesmo tempo, usando só o módulo nativo do Node.js | `servers/http` (porta 8787)    | `npm run start:http`, em um terminal       |
| **Express** | O mesmo HTTP, com o framework Express facilitando a implementação              | `servers/express` (porta 8788) | `npm run start:express`, em outro terminal |

Guias do SDK: [Serve over stdio](https://ts.sdk.modelcontextprotocol.io/v2/serving/stdio.html#serve-over-stdio) · [Serve over HTTP](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.html#serve-over-http).

Além do Express, o SDK tem guias para outros frameworks de Node.js: [Express](https://ts.sdk.modelcontextprotocol.io/v2/serving/express.html) · [Fastify](https://ts.sdk.modelcontextprotocol.io/v2/serving/fastify.html) · [Hono](https://ts.sdk.modelcontextprotocol.io/v2/serving/hono.html).

## 🏢 Cenário do Workshop

Cliente **Nordesul**:

1.  Considere um projeto de e-commerce em um grande cliente, com uma equipe de 20 desenvolvedores alocados para fazer a migração de sua loja virtual legada (_V0_) para um framework mais moderno (_V1_). O objetivo é que a loja virtual _V1_ seja idêntica a _V0_, mas use melhorias de performance do _V1_.

2.  Como diversos desenvolvedores atuarão na mesma base de código, é primordial que as entregas possuam a melhor padronização e qualidade possíveis, seguindo as normas e identidade da nossa companhia.

3.  O cliente possui uma base de dados com documentações de todas as suas APIs, que estão em um endpoint compartilhado com a equipe de desenvolvimento para consulta.

## 📦 Este Repositório

Este repositório contém um template de servidor MCP, que pode ser usado para:

- Entender a implementação dos transportes _stdio_ e _HTTP_ com `@modelcontextprotocol/server`;
- Simular a comunicação entre sistemas de IA e qualquer serviço externo;
- Servir como inspiração para a implementação de um servidor MCP real;
- Ser a porta de entrada para o uso de Agentes de IA com _tools_ customizadas.

## 🗂️ Estrutura do Repositório

```text
workshop-27-08-26/
├── servers/
│   ├── stdio/               # MCP via stdin/stdout (processo filho)
│   ├── http/                # MCP via HTTP nativo do Node.js (porta 8787)
│   └── express/             # MCP via HTTP com Express (porta 8788)
├── tools/
│   ├── index.js             # exporta todas as tools
│   ├── nordesul-deploy/
│   ├── nordesul-delivery/
│   ├── nordesul-reference/
│   └── nordesul-status/
├── utils/                   # funções utilitárias compartilhadas
├── material-adicional/      # leituras complementares
├── .opencode/               # agente Mentor, skill mentor-agent e config do OpenCode
├── package.json
└── LICENSE
```

### **/servers**

Servidores MCP de exemplo, usando diferentes transportes e frameworks (_stdio_, _HTTP_ nativo e _Express_), como descrito na tabela de transportes acima.

### **/tools**

Exemplos de _tools_ customizadas, que podem ser usadas por Agentes de IA para interagir com outros sistemas. O `tools/index.js` centraliza e exporta todas elas, para que os servidores MCP possam registrá-las de forma unificada.

| Tool                 | O que faz                                                                    |
| -------------------- | ---------------------------------------------------------------------------- |
| `nordesul-deploy`    | Retorna cuidados e boas práticas essenciais para um deploy seguro no cliente Nordesul. |
| `nordesul-delivery`  | Simula padrões e contratos de implementação para o projeto.                  |
| `nordesul-reference` | Simula a consulta de uma documentação de API no cliente Nordesul.            |
| `nordesul-status`    | Simula a consulta do status de uma aplicação no cliente Nordesul.            |

### **/utils**

Centraliza funções utilitárias/compartilhadas do projeto.

### **/.opencode**

Diretório de configuração do OpenCode:

- o agente custom `mentor`, que dá orientação socrática e suporte técnico para os participantes entenderem o repositório e suas funcionalidades;
- a skill `mentor-agent`, com o passo a passo para rodar, testar, comparar transportes e resolver problemas dos servidores;
- o `opencode.jsonc`, que já conecta os três servidores MCP (`stdio_mcp`, `http_mcp` e `express_mcp`).

## ⚙️ Rodando o Projeto

### Pré-requisitos

- [Git](https://git-scm.com/install/);
- Clonar o repositório do workshop;
- [OpenCode](https://opencode.ai/download) (ou qualquer outro agente de IA que suporte MCP) instalado e configurado;
- [Node.js](https://nodejs.org/en/download) (>= LTS preferido);
- Gerenciador de pacotes (npm ou [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#windows-stable)).

### Instalando as Dependências

Na raiz do projeto, rode o comando:

```bash
npm install

# ou:

yarn install
```

### Instalando o OpenCode

Em qualquer diretório, rode o comando:

```bash
npm i -g opencode-ai
```

### Rodando os Servidores

#### Servidor MCP via _stdio_

Você **não precisa rodar na mão**: o OpenCode inicia e gerencia esse processo sozinho, a partir do `opencode.jsonc` (`stdio_mcp`).

#### Servidor MCP via _HTTP_ (porta 8787)

```bash
npm run start:http

# ou:

yarn start:http
```

#### Servidor MCP via integração com _Express_ (porta 8788)

```bash
npm run start:express

# ou:

yarn start:express
```

> Os servidores _HTTP_ e _Express_ rodam com `--watch`: o terminal fica ocupado e o servidor reinicia quando você salva um arquivo. Use **um terminal por servidor**. As tools desses servidores só aparecem no agente depois que o servidor está de pé.

### Rodando o Agente Mentor (Exemplo com OpenCode)

Com o OpenCode instalado, abra um terminal de sua preferência no diretório do repositório e rode o comando:

```bash
opencode
```

A primeira execução irá baixar todas as dependências do OpenCode, então aguarde a conclusão do processo. O agente _Mentor_ já estará selecionado por padrão.

### Integração de servidores MCP com Agentes de IA

Já usa outro agente? Veja como conectar um servidor MCP a ele:

- OpenCode: [MCP servers](https://opencode.ai/docs/en/mcp-servers/);
- Claude: [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp);
- Codex: [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp);
- Cursor: [Model Context Protocol (MCP)](https://cursor.com/en-US/docs/mcp);
- Antigravity: [Model Context Protocol (MCP)](https://antigravity.google/docs/cli/mcp/).

## 💬 Prompts de Exemplo

Alguns exemplos para interagir com as _tools_ do repositório, usando o seu agente:

| Tool                 | Prompt de exemplo                                                            |
| -------------------- | ---------------------------------------------------------------------------- |
| `nordesul-delivery`  | _Quais são os padrões de implementação para a área de checkout do Nordesul?_ |
| `nordesul-deploy`    | _Antes de eu publicar essa mudança no Nordesul, quais cuidados devo tomar?_  |
| `nordesul-reference` | _Me mostra a documentação da API de pedidos (orders) do Nordesul._           |
| `nordesul-status`    | _Qual o status atual da aplicação checkout-service no Nordesul?_             |

## 📚 Material de Apoio

A pasta `material-adicional/` contém documentação complementar para o workshop.

### Leitura Recomendada (Antes ou Durante)

| Arquivo               | Conteúdo                                      | Quando Ler         |
| --------------------- | --------------------------------------------- | ------------------ |
| `agentes.md`          | O que são agentes de IA, glossário, analogias | Antes do workshop  |
| `conexao-opencode.md` | Como configurar o OpenCode + troubleshooting  | Durante o hands-on |
| `exemplos.md`         | Prompts de exemplo para tools e APIs públicas | Durante o hands-on |

### Leitura Opcional (Aprofundamento)

| Arquivo         | Conteúdo                                                | Nível         |
| --------------- | ------------------------------------------------------- | ------------- |
| `diferenca.md`  | Servidor Web vs MCP, transportes                        | Intermediário |
| `protocolo.md`  | Métodos MCP (tools/list, tools/call)                    | Intermediário |
| `jsonrpc.md`    | JSON-RPC 2.0 em profundidade                            | Avançado      |
| `openai-api.md` | Como requests REST (OpenAI) funcionam, comparado ao MCP | Avançado      |

### Catálogo de APIs Públicas

Para o hands-on, escolha uma API do [catálogo de APIs públicas](https://www.freepublicapis.com/tags/popular).

APIs sugeridas (sem autenticação):

- **Open Meteo**: clima;
- **Free Meal API**: receitas;
- **HackerNews**: notícias de tech;
- **World Bank**: dados econômicos.

## ➡️ Veja Também

- [workshop-22-10-26](https://github.com/leostacowskicompasso/workshop-22-10-26): outro workshop do bootcamp, com uma _skill_ de estudo sobre IAM, S3, CloudFront e VPC (hospedagem estática na AWS).

## 📄 Licença

Este projeto é de domínio público, sob a licença [Unlicense](./LICENSE).