Workshop: Construa um Servidor MCP com 5 Ferramentas que Reduzem seu Uso de Tokens de IA em 95%

O Que Estamos Construindo

Deixe-me mostrar um padrão que uso em todos os projetos agora. Vamos construir um servidor MCP inicial com cinco ferramentas que substituem a cara exploração arquivo por arquivo que os LLMs fazem ao explorar seu código. Ao final deste tutorial, você terá um servidor funcionando que pode reduzir seu uso de tokens em 60-75% imediatamente — e você entenderá a arquitetura para levar isso a 95%.

A ideia central: pare de dar arquivos para os modelos, comece a dar respostas a eles.

Pré-requisitos

• Node.js 18+
• Um projeto TypeScript que você deseja usar como seu código de teste
• Familiaridade básica com como funciona a chamada de ferramentas do Claude ou GPT
• O MCP SDK: npm install @modelcontextprotocol/sdk

Passo 1: Entender o Problema

Aqui está o que acontece toda vez que um LLM explora seu repositório sem ferramentas estruturadas:

Você está 50K tokens profundo antes de uma única linha útil de saída. Isso é aproximadamente $0,75 por tarefa no Claude Opus. Faça isso 20 vezes por dia e você está queimando $15 — $450/mês.

Passo 2: Estruturar o Servidor MCP

Aqui está a configuração mínima para fazer isso funcionar:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "codebase-context",
  version: "1.0.0",
});

const transport = new StdioServerTransport();
await server.connect(transport);

Esse é o seu servidor em funcionamento. Agora adicionamos as ferramentas que importam.

Passo 3: Construir as Cinco Ferramentas Iniciais

Ferramenta 1 — Resumo do Projeto. Isso substitui 5-10 leituras de arquivos por uma única resposta de 200 tokens.

server.tool("get_project_summary", {}, async () => ({
  content: [{
    type: "text",
    text: JSON.stringify({
      stack: "TypeScript, Express, Prisma, PostgreSQL",
      entryPoint: "src/index.ts",
      keyDirs: ["src/services", "src/routes", "src/models"],
      buildCmd: "npm run build",
    }),
  }],
}));

Ferramenta 2 — Mapa de Dependências. Pré-calcule relacionamentos de módulos para que o modelo nunca rastreie imports.

server.tool("get_dependency_map", { module: z.string() }, async ({ module }) => {
  const graph = await buildDependencyGraph(); // sua análise estática
  return {
    content: [{ type: "text", text: JSON.stringify(graph[module]) }],
  };
});

Ferramenta 3 — Localizador de Arquivos Relevantes. Dada uma tarefa, retorna apenas os 3-5 arquivos que precisam de alterações.

Ferramenta 4 — Extrator de Convenções. Padrões de nomenclatura, estilo de tratamento de erros, estrutura de testes. Mantém o código gerado consistente com seu código.

Ferramenta 5 — Ferramenta de Esquema/Tipo. Retorna definições de tipo e contratos de API sem que o modelo leia o arquivo fonte completo.