MCPForge | Sakaguchi IA

O que é este projeto

MCPForge é um framework de padrões de arquitetura para o Model Context Protocol (MCP). Em vez de começar cada servidor MCP do zero, você parte de templates testados, com estrutura de pastas, tipagem completa e configurações de produção já incluídas.

O projeto oferece templates em TypeScript, Python, Go e Rust, além de uma CLI que gera a estrutura do projeto com um único comando. Cada template segue os mesmos padrões de qualidade: validação de entrada, tratamento de erros, logging estruturado e testes automatizados.

O que é MCP

O Model Context Protocol (MCP) é um protocolo aberto que padroniza a forma como modelos de linguagem se conectam a ferramentas externas. Pense nele como uma interface universal: em vez de cada LLM ter sua própria forma de chamar APIs, bancos de dados ou serviços, o MCP define um contrato único.

Isso importa porque desacopla a inteligência da ação. O modelo decide o que fazer; o servidor MCP executa. Qualquer ferramenta que implemente o protocolo funciona com qualquer modelo compatível, sem adaptadores ou código custom.

Tools — funções que o modelo pode invocar (queries, cálculos, chamadas de API)
Resources — dados que o modelo pode ler (arquivos, schemas, documentação)
Prompts — templates reutilizáveis que guiam o comportamento do modelo
Transport — camada de comunicação (stdio, HTTP/SSE, WebSocket)

Em 2026, o MCP se consolidou como o padrão dominante para integração de ferramentas com IA. Claude, GPT, Gemini e modelos open-source adotaram o protocolo. Construir servidores MCP hoje é investir em compatibilidade de longo prazo.

Padrões de arquitetura

MCPForge organiza os padrões em três categorias: transport, tools e resources. Cada padrão inclui código funcional, testes e documentação de trade-offs.

Transport patterns

Stdio transport — comunicação via stdin/stdout, ideal para CLIs e integrações locais
HTTP/SSE transport — server-sent events para conexões remotas com streaming
Multiplexed transport — múltiplos clientes simultâneos com isolamento de sessão

Tool patterns

Schema-first tools — definição via JSON Schema com validação automática de parâmetros
Composable tools — ferramentas que se combinam em pipelines de execução
Guarded tools — rate limiting e permissões por ferramenta

Resource patterns

Dynamic resources — conteúdo gerado sob demanda (queries, agregações)
Cached resources — dados com TTL e invalidação inteligente
Subscribed resources — notificações push quando o recurso muda

Exemplo: Servidor MCP em TypeScript

// Servidor MCP com tool e resource
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: 'mcpforge-example',
  version: '1.0.0',
});

// Registrar uma tool
server.tool(
  'search_docs',
  'Busca na documentação do projeto',
  { query: z.string(), limit: z.number().optional().default(10) },
  async ({ query, limit }) => {
    const results = await searchIndex(query, limit);
    return {
      content: [{ type: 'text', text: JSON.stringify(results) }],
    };
  }
);

// Registrar um resource
server.resource(
  'schema',
  'schema://database/main',
  async () => ({
    contents: [{
      uri: 'schema://database/main',
      text: await getDatabaseSchema(),
    }],
  })
);

// Iniciar servidor via stdio
const transport = new StdioServerTransport();
await server.connect(transport);
                

CLI e scaffolding

A CLI do MCPForge gera a estrutura completa do projeto com um comando. Você escolhe a linguagem, o tipo de transport e quais padrões quer incluir. O resultado é um projeto funcional com testes, linting e CI configurados.

Geração interativa — wizard que guia a configuração passo a passo
Templates composáveis — combine tools, resources e prompts conforme a necessidade
Config automática — gera tsconfig, eslint, vitest, Dockerfile e CI/CD
Claude Desktop integration — arquivo de configuração pronto para testar no Claude

# Criar um novo servidor MCP
$ npx mcpforge create meu-servidor

# Wizard interativo
? Linguagem: TypeScript
? Transport: stdio
? Incluir tools de exemplo? Sim
? Incluir resources? Sim
? Configurar CI/CD? GitHub Actions

# Estrutura gerada
meu-servidor/
  src/
    index.ts          # Entry point
    tools/            # Ferramentas MCP
    resources/        # Recursos MCP
    prompts/          # Templates de prompt
  tests/
  .github/workflows/
  tsconfig.json
  package.json
                

Multi-linguagem

Nem todo time usa TypeScript. O MCPForge oferece templates equivalentes em quatro linguagens, cada um seguindo as convenções e ferramentas idiomáticas do ecossistema.

TypeScript — SDK oficial da Anthropic, Zod para validação, Vitest para testes
Python — SDK oficial, Pydantic para schemas, pytest e asyncio
Go — implementação leve com goroutines, sem dependências externas pesadas
Rust — performance máxima, tipagem em tempo de compilação, tokio async runtime

Arquitetura MCPForge: templates multi-linguagem com padrões compartilhados

Produção

Código de exemplo funciona na demo. Em produção, você precisa de mais. Os templates do MCPForge incluem configurações que normalmente só aparecem depois do primeiro incidente:

Rate limiting — limitação por ferramenta e por sessão, com backpressure configurável
Logging estruturado — JSON logs com correlation ID, latência e metadata de cada chamada
Health checks — endpoint /health com verificação de dependências (DB, cache, APIs externas)
Error handling — erros tipados com códigos MCP, retry automático e circuit breaker
Métricas — OpenTelemetry integrado com contadores de chamadas, latência P99 e error rate
Graceful shutdown — finalização limpa de conexões e jobs em andamento

// Rate limiting por tool
import { withRateLimit } from 'mcpforge/middleware';

server.tool(
  'expensive_query',
  'Query que consome muitos recursos',
  { sql: z.string() },
  withRateLimit(
    { maxRequests: 10, windowMs: 60_000 },
    async ({ sql }) => {
      const result = await db.query(sql);
      return {
        content: [{ type: 'text', text: JSON.stringify(result) }],
      };
    }
  )
);

// Health check com dependências
server.resource(
  'health',
  'health://status',
  async () => {
    const checks = await Promise.all([
      checkDatabase(),
      checkRedis(),
      checkExternalApi(),
    ]);
    return {
      contents: [{ uri: 'health://status', text: JSON.stringify(checks) }],
    };
  }
);
                

Cada template é testável localmente. O comando mcpforge dev inicia um inspetor visual que mostra em tempo real as chamadas do modelo, parâmetros recebidos e respostas enviadas.

Como usar

Três comandos para sair do zero e ter um servidor MCP funcionando. A CLI cuida da estrutura; você foca na lógica das ferramentas.

# 1. Criar o projeto
$ npx mcpforge create meu-servidor --lang typescript --transport stdio

# 2. Implementar suas tools
$ cd meu-servidor
$ npm install
# Edite src/tools/ com sua lógica

# 3. Testar localmente com Claude Desktop
$ npx mcpforge dev
# Abre inspetor MCP em http://localhost:5173

# 4. Build e deploy
$ npm run build
$ npx mcpforge deploy --target docker
                

Framework de padrões para Model Context Protocol

O que é este projeto

O que é MCP

Padrões de arquitetura

Transport patterns

Tool patterns

Resource patterns

Exemplo: Servidor MCP em TypeScript

CLI e scaffolding

Multi-linguagem

Produção

Como usar

Tecnologias

Detalhes

Índice

Quer algo parecido?

Quer implementar algo parecido?