# MCP Server Básico

Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) de exemplo, escrito em TypeScript e Node.js, usando o SDK oficial `@modelcontextprotocol/sdk`.

> 📖 **Nunca usou MCP?** Siga o **[Guia de Uso passo a passo](GUIA-DE-USO.md)** — do zero até usar no Claude Desktop, sem precisar saber programar.

## Capacidades

| Tipo     | Nome        | Descrição                                                        |
|----------|-------------|------------------------------------------------------------------|
| Tool     | `hello`     | Recebe `name` e retorna `Olá, <name>!`                            |
| Resource | `info`      | `resource://info` — texto explicando o servidor                   |
| Prompt   | `assistant` | Recebe `topic` e gera um prompt de sistema sobre esse tema        |

## Estrutura do projeto

```
mermaid MCP/
├── src/
│   ├── index.ts              # Ponto de entrada: cria o servidor e conecta via stdio
│   ├── tools/
│   │   └── hello.ts          # Tool "hello"
│   ├── resources/
│   │   └── info.ts           # Resource "info" (resource://info)
│   └── prompts/
│       └── assistant.ts      # Prompt "assistant"
├── package.json
├── tsconfig.json
└── README.md
```

## Arquitetura

```mermaid
graph TD
    Claude["Cliente Claude<br/>(Claude Desktop)"]
    Server["MCP Server<br/>(index.ts — stdio / JSON-RPC 2.0)"]

    Tools["Tools<br/>(src/tools/)"]
    Resources["Resources<br/>(src/resources/)"]
    Prompts["Prompts<br/>(src/prompts/)"]

    Hello["hello<br/>name → 'Olá, name!'"]
    Info["info<br/>resource://info"]
    Assistant["assistant<br/>topic → prompt de sistema"]

    Claude -- "tools/call" --> Server
    Claude -- "resources/read" --> Server
    Claude -- "prompts/get" --> Server

    Server --> Tools
    Server --> Resources
    Server --> Prompts

    Tools --> Hello
    Resources --> Info
    Prompts --> Assistant

    Hello -. "resposta (content)" .-> Server
    Info -. "resposta (contents)" .-> Server
    Assistant -. "resposta (messages)" .-> Server
    Server -. "resultado JSON-RPC" .-> Claude
```

### Fluxo de uma chamada de Tool

```mermaid
sequenceDiagram
    participant Claude as Cliente Claude
    participant Server as MCP Server
    participant Tool as Tool "hello"

    Claude->>Server: initialize
    Server-->>Claude: capabilities (tools, resources, prompts)
    Claude->>Server: notifications/initialized

    Claude->>Server: tools/call { name: "hello", arguments: { name: "Maria" } }
    Server->>Tool: valida input (Zod) e executa handler
    Tool-->>Server: { content: [{ type: "text", text: "Olá, Maria!" }] }
    Server-->>Claude: resposta JSON-RPC com o resultado
```

## Requisitos

- Node.js 18 ou superior

## Instalação

```bash
npm install
```

## Desenvolvimento

Executa direto do TypeScript, sem compilar (via `tsx`):

```bash
npm run dev
```

## Build e execução

```bash
npm run build   # compila TypeScript para ./build
npm start       # executa node build/index.js
```

O servidor se comunica por **stdio** (stdin/stdout com JSON-RPC 2.0). Ele não abre porta HTTP — quem o inicia é o cliente MCP (ex.: Claude Desktop).

## Testando manualmente

Com o [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

## Conectando ao Claude Desktop

1. Compile o projeto: `npm run build`
2. Abra o arquivo de configuração do Claude Desktop:
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Adicione o servidor (ajuste o caminho absoluto):

```json
{
  "mcpServers": {
    "mcp-server-basico": {
      "command": "node",
      "args": [
        "C:\\CAMINHO\\ATE\\O\\PROJETO\\mermaid-mcp\\build\\index.js"
      ]
    }
  }
}
```

4. Reinicie o Claude Desktop. O servidor aparecerá no menu de ferramentas (ícone 🔌 / "Search and tools").

Depois disso você pode pedir, por exemplo: *"Use a tool hello com o nome Maria"*.

## Adicionando novas Tools

1. Crie um arquivo em `src/tools/`, exportando uma função `registerXxxTool(server)`.
2. Dentro dela, chame `server.registerTool(nome, config, handler)`.
3. Importe e chame a função em `src/index.ts`.
4. Rode `npm run build` e reinicie o cliente MCP.