MCP Server Básico

Servidor Model Context Protocol (MCP) 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 — 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

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

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

npm install

Desenvolvimento

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

npm run dev

Build e execução

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:

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

{
  "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.