mcpcodeserver MCP Server

oficial

Em vez de chamar diretamente as ferramentas MCP, o servidor mcpcodeserver transforma chamadas de ferramentas MCP em programas TypeScript, permitindo uma orquestração mais inteligente e de menor latência por LLMs.

GitHub
13

Documentação

mcpcodeserver

NPM Version MIT licensed Install MCP Server Install in VS Code (npx)

Um servidor proxy do Model Context Protocol (MCP) que traduz chamadas de ferramentas em geração de código TypeScript. Em vez de fazer várias chamadas de ferramentas de ida e volta, os LLMs podem escrever código TypeScript que chama várias ferramentas naturalmente, reduzindo a sobrecarga de tokens e aproveitando as capacidades superiores de geração de código do LLM.

❌ Sem o mcpcodeserver

Os LLMs fazem várias chamadas sequenciais de ferramentas, queimando tokens e enfrentando dificuldades com fluxos de trabalho complexos:

  • ❌ Múltiplas idas e vindas entre o LLM e as ferramentas
  • ❌ Sequências complexas de chamadas de ferramentas são propensas a erros
  • ❌ Dados não podem ser facilmente passados entre ferramentas
  • ❌ Tratamento de erros e fluxo de controle limitados

✅ Com o mcpcodeserver

Os LLMs escrevem código TypeScript que chama várias ferramentas naturalmente:

  • ✅ Escreva código para chamar várias ferramentas em sequência
  • ✅ Use variáveis, loops e condicionais naturalmente
  • ✅ Melhor tratamento de erros com try/catch
  • ✅ Reduza o uso de tokens combinando operações
  • ✅ Aproveite as fortes capacidades de geração de código do LLM

Início Rápido

  1. Instale o mcpcodeserver no seu cliente MCP (veja a seção de instalação abaixo)
  2. Crie um arquivo de configuração mcp.json com seus servidores MCP filhos
  3. Comece a usar - seu LLM agora pode gerar e executar código TypeScript que chama suas ferramentas
// Instead of multiple tool calls, write code like this:
const files = await filesystem.list_directory({ path: "/tmp" });
const results = await Promise.all(
  files.map(file => filesystem.read_file({ path: file.path }))
);
return results.filter(content => content.includes("important"));

Visão Geral

mcpcodeserver é um servidor MCP único que:

  • Atua como um cliente MCP para conectar-se a um ou mais servidores MCP filhos
  • Descobre todas as ferramentas dos servidores filhos
  • Expõe três ferramentas poderosas para clientes LLM pais:
    1. list_servers - Lista todos os subservidores disponíveis conectados a este servidor MCP
    2. get_tool_definitions - Retorna definições de tipo TypeScript para ferramentas descobertas (opcionalmente filtradas por servidor)
    3. generate_and_execute_code - Gera e executa código TypeScript que chama essas ferramentas em um sandbox

Esta arquitetura permite que os LLMs orquestrem fluxos de trabalho complexos com múltiplas ferramentas escrevendo código em vez de fazer chamadas sequenciais de ferramentas, o que geralmente é mais eficiente e natural para modelos de linguagem modernos.

Trabalhos Relacionados e Pesquisa

Esta abordagem é inspirada por pesquisas recentes que mostram que os LLMs têm melhor desempenho ao gerar código executável em vez de fazer chamadas diretas de ferramentas:

  • CodeAct: Your LLM Agent Acts Better when Generating Code (Apple, ICML 2024) - Demonstra que agentes LLM alcançam taxas de sucesso até 20% maiores ao usar código Python executável como um espaço de ação unificado em vez de formatos predefinidos de chamada de ferramentas.

  • Cloudflare Code Mode - Uma implementação similar que converte ferramentas MCP em APIs TypeScript, mostrando que "LLMs são melhores em escrever código para chamar MCP do que em chamar MCP diretamente."

A principal percepção desta pesquisa é que os LLMs têm treinamento extensivo em código do mundo real, mas exposição limitada a formatos sintéticos de chamada de ferramentas, tornando a geração de código uma abordagem mais natural e eficaz para fluxos de trabalho de agentes complexos.

Por Que Usar?

Problemas Tradicionais de Chamada de Ferramentas

  • Múltiplas idas e vindas entre o LLM e as ferramentas queimam tokens
  • LLMs frequentemente enfrentam dificuldades com sequências complexas de chamadas de ferramentas
  • Cada chamada de ferramenta requer compreensão e formatação de esquema JSON
  • Dados não podem ser facilmente passados entre ferramentas sem passar pelo LLM

Solução de Geração de Código

  • Escreva código TypeScript para chamar várias ferramentas em sequência
  • Use variáveis, loops e condicionais naturalmente
  • Melhor tratamento de erros com try/catch
  • Reduza o uso de tokens combinando operações
  • Aproveite as fortes capacidades de geração de código do LLM

Descoberta Dinâmica de Ferramentas

O mcpcodeserver monitora automaticamente os servidores MCP filhos em busca de mudanças nas ferramentas e notifica os clientes pais quando ferramentas são adicionadas, removidas ou modificadas:

  • Atualização Automática: Verifica mudanças nas ferramentas a cada 30 segundos
  • Notificações em Tempo Real: Envia notifications/tools/list_changed para clientes pais
  • Atualizações Dinâmicas: Definições de ferramentas e resumos são atualizados automaticamente
  • Sem Atualização Manual: LLMs pais recebem notificações para atualizar seu conhecimento sobre ferramentas

Isso garante que os LLMs pais sempre tenham as definições de ferramentas mais atuais sem exigir intervenção manual.

Filtragem de Servidor

Para reduzir o uso da janela de contexto e melhorar o foco, o mcpcodeserver suporta a filtragem de definições de ferramentas por servidores específicos:

  • Listar Servidores Disponíveis: Use list_servers para ver todos os subservidores conectados
  • Definições de Ferramentas Filtradas: Use get_tool_definitions com o parâmetro server_names para obter ferramentas apenas de servidores específicos
  • Verbosidade Reduzida: Obtenha definições TypeScript focadas sem sobrecarregar a janela de contexto do LLM
  • Namespacing de Métodos: Todas as funções geradas são prefixadas com nomes de servidor (ex., pizzashop_create_pizza, filesystem_read_file)

Exemplo de uso:

// List available servers
const servers = await list_servers({});
// Returns: ["pizzashop", "filesystem", "memory"]

// Get all tool definitions
const allTools = await get_tool_definitions({});

// Get only pizzashop tools
const pizzashopTools = await get_tool_definitions({
  server_names: ["pizzashop"]
});

Recursos Avançados do MCP

O mcpcodeserver suporta a passagem de recursos avançados do protocolo MCP quando tanto os servidores pais quanto os filhos os suportam:

  • Elicitação: Servidores filhos podem solicitar entrada do usuário durante a execução da ferramenta, que é repassada aos clientes pais
  • Raízes: Lista e agrega raízes de todos os servidores filhos, fornecendo uma visão unificada dos recursos disponíveis
  • Amostragem: Permite que solicitações de amostragem do LLM sejam repassadas aos servidores filhos para capacidades avançadas de IA

Esses recursos são automaticamente anunciados aos clientes pais e funcionam perfeitamente quando suportados pelos servidores MCP filhos subjacentes.

Início Rápido

Experimente imediatamente com npx (sem necessidade de instalação):

# From GitHub
npx github:zbowling/mcpcodeserver --help

# Or when published to npm
npx mcpcodeserver --help

🛠️ Instalação

Requisitos

  • Node.js >= v18.0.0
  • Cursor, Claude Code, VSCode, Windsurf ou outro Cliente MCP

Instalando via Smithery

Para instalar o mcpcodeserver para qualquer cliente automaticamente via Smithery:

npx -y @smithery/cli@latest install mcpcodeserver --client <client-name> --key <smithery-key>

Instalar no Cursor

Vá para: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Colar a seguinte configuração no seu arquivo ~/.cursor/mcp.json do Cursor é a abordagem recomendada. Você também pode instalar em um projeto específico criando .cursor/mcp.json na pasta do seu projeto.

Instalação com Um Clique no Cursor

Install MCP Server

Conexão com Servidor Local no Cursor

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Conexão com Servidor Remoto no Cursor (se você configurou o transporte HTTP)

{
  "mcpServers": {
    "mcpcodeserver": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Instalar no Claude Code

Execute este comando. Veja a documentação do Claude Code MCP para mais informações.

Conexão com Servidor Local no Claude Code

claude mcp add mcpcodeserver -- npx -y mcpcodeserver --config /path/to/your/mcp.json

Conexão com Servidor Remoto no Claude Code

claude mcp add --transport http mcpcodeserver http://localhost:3000/mcp

Instalar no VSCode

Instalação com Um Clique no VSCode

Install in VS Code (npx)

Configuração Manual no VSCode

Adicione às suas configurações MCP do VSCode:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar no Windsurf

Instalação com Um Clique no Windsurf

Install in Windsurf

Instalar em Assistentes de Codificação com IA

Para Continue, Cline e RooCode, adicione à sua configuração:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar no Amp

Execute este comando no seu terminal. Veja a documentação do Amp MCP para mais informações.

amp mcp add mcpcodeserver -- npx -y mcpcodeserver --config /path/to/your/mcp.json

Instalar em Editores de Texto

Para Aider, Codium, Zed, Nova e Sublime Text, adicione à sua configuração:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar no Neovim

Adicione à sua configuração MCP do Neovim:

{
  mcpServers = {
    mcpcodeserver = {
      command = "npx",
      args = {"-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"}
    }
  }
}

Instalar no Emacs

Adicione à sua configuração MCP do Emacs:

(setq mcp-servers
      '((mcpcodeserver
         :command "npx"
         :args ("-y" "mcpcodeserver" "--config" "/path/to/your/mcp.json"))))

Instalar em IDEs JetBrains

Para IntelliJ IDEA, WebStorm, PyCharm e Android Studio, adicione às suas configurações MCP:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar em Ferramentas de IA

Para Codeium, Tabnine, GitHub Copilot e Amazon CodeWhisperer, adicione às suas configurações MCP:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar em IDEs na Nuvem

Para Replit, CodeSandbox, StackBlitz, GitPod, GitHub Codespaces, GitLab Web IDE e Bitbucket Cloud, adicione às suas configurações MCP:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar em Outras Ferramentas

Para Xcode, Fleet, Sourcegraph e JetBrains Gateway, adicione à sua configuração MCP:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Instalar em Desenvolvimento Remoto

Para ambientes de desenvolvimento remoto, você também pode usar o transporte HTTP:

{
  "mcpServers": {
    "mcpcodeserver": {
      "url": "http://your-server:3000/mcp"
    }
  }
}

Arquivo de Configuração

Crie um arquivo de configuração mcp.json para definir seus servidores MCP filhos:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": { "DEBUG": "false" }
    },
    "memory": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-api-key" }
    }
  }
}

Instalação para Desenvolvimento

# Install dependencies (using Bun for faster performance)
bun install

# Or with npm
npm install

# Build the project
bun run build

# Test the built server
bun dist/index.js --help

Nota: Este projeto usa Bun para melhor desempenho, mas npm/node também funcionam bem.

🚨 Solução de Problemas

Erros de Módulo Não Encontrado

Se você encontrar ERR_MODULE_NOT_FOUND, tente usar bunx em vez de npx:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "bunx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Problemas de Resolução ESM

Para erros como Error: Cannot find module, tente a flag --experimental-vm-modules:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "--node-options=--experimental-vm-modules", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Problemas de TLS/Certificado

Use a flag --experimental-fetch para contornar problemas relacionados a TLS:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "--node-options=--experimental-fetch", "mcpcodeserver", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Erros Gerais do Cliente MCP

  1. Tente adicionar @latest ao nome do pacote
  2. Use bunx como uma alternativa ao npx
  3. Considere usar deno como outra alternativa
  4. Certifique-se de estar usando Node.js v18 ou superior para suporte nativo a fetch

Problemas de Configuração

  • Certifique-se de que seu arquivo mcp.json seja JSON válido
  • Verifique se todos os comandos do servidor filho estão disponíveis no seu PATH
  • Verifique se os servidores filhos podem iniciar independentemente
  • Verifique as permissões de arquivo para o caminho do arquivo de configuração

Testando com o MCP Inspector

npx -y @modelcontextprotocol/inspector npx mcpcodeserver --config /path/to/your/mcp.json

💻 Desenvolvimento

Argumentos CLI

mcpcodeserver aceita as seguintes flags CLI:

  • --config <path> – Caminho para o arquivo de configuração MCP (padrão: ./mcp.json)
  • --transport <stdio|http> – Transporte a ser usado (stdio por padrão). Note que o transporte HTTP fornece automaticamente ambos os endpoints HTTP e SSE
  • --port <number> – Porta para escutar ao usar o transporte http (padrão 3000)
  • --help – Mostrar mensagem de ajuda

Exemplo com transporte HTTP e porta 8080:

npx mcpcodeserver --config /path/to/mcp.json --transport http --port 8080

Exemplo com transporte stdio:

npx mcpcodeserver --config /path/to/mcp.json --transport stdio

Variáveis de Ambiente

Você pode usar variáveis de ambiente para configuração:

  • MCP_CONFIG_PATH – Caminho para o arquivo de configuração MCP (alternativa ao --config)
  • MCP_TRANSPORT – Tipo de transporte (alternativa ao --transport)
  • MCP_PORT – Número da porta para transporte HTTP (alternativa ao --port)

Exemplo com variáveis de ambiente:

# .env
MCP_CONFIG_PATH=/path/to/your/mcp.json
MCP_TRANSPORT=stdio

Exemplo de configuração MCP usando variáveis de ambiente:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/mcp.json"
      }
    }
  }
}

Nota: Flags CLI têm precedência sobre variáveis de ambiente quando ambos são fornecidos.

Configuração de Desenvolvimento Local

Para desenvolvimento local, você pode executar o código-fonte TypeScript diretamente:

{
  "mcpServers": {
    "mcpcodeserver": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcpcodeserver/src/index.ts", "--config", "/path/to/your/mcp.json"]
    }
  }
}

Modos de Execução

Modo Stdio (Padrão)

O servidor é executado no modo stdio por padrão, o que é perfeito para integração com clientes MCP como o Claude Desktop:

# Run in stdio mode
npx mcpcodeserver --config mcp.json

# Or with custom config path
npx mcpcodeserver --config /path/to/your/mcp.json

Modo HTTP

Para depuração, teste ou integração com clientes MCP baseados na web, você pode executar o servidor no modo HTTP:

# Run in HTTP mode on default port 3000
npx mcpcodeserver --http --config mcp.json

# Run on custom port and host
npx mcpcodeserver --http --port 8080 --host 0.0.0.0 --config mcp.json

Ao executar no modo HTTP, o servidor estará disponível em:

  • URL do Servidor: http://localhost:3000/mcp (ou seu host:porta personalizado)
  • MCP Inspector: Use npx @modelcontextprotocol/inspector http://localhost:3000/mcp para depurar e testar

Integração com o MCP Inspector

O MCP Inspector é uma ferramenta poderosa para depurar e testar servidores MCP. Ao executar no modo HTTP, você pode usá-lo para:

  • Inspecionar ferramentas disponíveis e seus esquemas
  • Testar chamadas de ferramentas interativamente
  • Depurar acesso a recursos e prompts
  • Monitorar notificações em tempo real
# Start the server in HTTP mode
npx mcpcodeserver --http --config mcp.json

# In another terminal, start the MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

# Or use the shorthand script (includes all example servers)
npm run inspector

O inspetor abrirá no seu navegador e fornecerá uma interface completa para explorar e testar seu servidor MCP.

Nota: O comando npm run inspector usa mcp-test.json que inclui 8 servidores MCP (67 ferramentas no total) dos exemplos oficiais, incluindo servidores baseados em TypeScript (npx) e Python (uvx).

Configuração

Crie um arquivo mcp.json que define a quais servidores MCP filhos se conectar. Ele segue o formato padrão de configuração de cliente MCP:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "DEBUG": "false"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    },
    "weather": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}

Opções de Configuração

Cada entrada de servidor suporta:

Para transporte stdio:

  • command (obrigatório) - O comando a executar (ex.: "node", "python", "npx")
  • args (opcional) - Array de argumentos a passar para o comando
  • env (opcional) - Variáveis de ambiente para o processo filho

Para transporte HTTP/SSE:

  • url (obrigatório) - A URL do endpoint HTTP
  • transport - Defina como "sse" para Server-Sent Events

Uso

Iniciando o Servidor

# Use default config (./mcp.json)
mcpcodeserver

# Use custom config location
mcpcodeserver --config /path/to/custom-mcp.json

# Show help
mcpcodeserver --help

Usando como um Servidor MCP

Configure o mcpcodeserver no seu cliente MCP (como Claude Desktop, Claude Code, Cline, etc.):

Com npx (recomendado - sem necessidade de instalação):

{
  "mcpServers": {
    "codeserver": {
      "command": "npx",
      "args": ["-y", "mcpcodeserver", "--config", "/path/to/mcp.json"]
    }
  }
}

Do GitHub (funciona imediatamente):

{
  "mcpServers": {
    "codeserver": {
      "command": "npx",
      "args": ["-y", "github:zbowling/mcpcodeserver", "--config", "/path/to/mcp.json"]
    }
  }
}

Com outros gerenciadores de pacotes:

// yarn
{ "command": "yarn", "args": ["dlx", "mcpcodeserver", "--config", "/path/to/mcp.json"] }

// pnpm
{ "command": "pnpm", "args": ["dlx", "mcpcodeserver", "--config", "/path/to/mcp.json"] }

// bun
{ "command": "bunx", "args": ["mcpcodeserver", "--config", "/path/to/mcp.json"] }

Veja examples/ para mais exemplos de configuração e setups específicos de clientes MCP.

Ferramenta 1: get_tool_definitions

Esta ferramenta retorna definições de tipo TypeScript para todas as ferramentas descobertas dos servidores filhos.

Entrada:

  • include_examples (booleano opcional) - Se deve incluir exemplos de uso

Exemplo:

// Call the tool (in your MCP client)
get_tool_definitions({ include_examples: true })

Saída: Retorna código TypeScript com interfaces e declarações de função:

/**
 * Auto-generated TypeScript definitions for MCP tools
 */

interface ToolResult {
  content: Array<{
    type: string;
    text?: string;
    // ...
  }>;
  isError?: boolean;
}

/**
 * Read contents of a file
 * Server: filesystem
 * Tool: read_file
 */
interface ReadFileParams {
  path: string;
}

declare function filesystem_read_file(params: ReadFileParams): Promise<ToolResult>;

// ... more tool definitions

Ferramenta 2: generate_and_execute_code

Esta ferramenta executa código TypeScript em um sandbox com acesso a todas as funções de ferramenta descobertas.

Entrada:

  • code (string obrigatória) - Código TypeScript/JavaScript a executar
  • timeout (número opcional) - Tempo máximo de execução em milissegundos (padrão: 30000, máximo: 300000)

Exemplo:

// Call the tool with TypeScript code
generate_and_execute_code({
  code: `
    // Read multiple files and combine them
    const file1 = await filesystem_read_file({ path: "/tmp/file1.txt" });
    const file2 = await filesystem_read_file({ path: "/tmp/file2.txt" });

    const text1 = file1.content[0].text;
    const text2 = file2.content[0].text;

    console.log("File 1 length:", text1.length);
    console.log("File 2 length:", text2.length);

    return {
      combined: text1 + text2,
      totalLength: text1.length + text2.length
    };
  `
})

Saída:

=== Console Output ===
File 1 length: 42
File 2 length: 38

=== Result ===
{
  "combined": "...",
  "totalLength": 80
}

Ambiente Sandbox

O sandbox de execução TypeScript fornece:

Disponível:

  • Todas as funções de ferramenta descobertas (como funções assíncronas)
  • Métodos de console: console.log(), console.error(), console.warn(), console.info()
  • Globais básicos do JavaScript: Math, JSON, Date, Array, Object, String, Number, Boolean
  • Suporte a Promise e async/await
  • Tratamento de erros com try/catch
  • Temporizadores: setTimeout, setInterval, clearTimeout, clearInterval

Não Disponível:

  • Módulos Node.js (fs, http, child_process, etc.)
  • Acesso ao sistema de arquivos (exceto via ferramentas MCP)
  • Acesso à rede (exceto via ferramentas MCP)
  • Informações de processo

Nota de Segurança: Este não é um sandbox totalmente seguro. O contexto da VM fornece isolamento, mas não é à prova de balas. Execute apenas código confiável.

Tratamento de Erros

Erros no sandbox são capturados e retornados com stack traces:

generate_and_execute_code({
  code: `
    try {
      const result = await filesystem_read_file({ path: "/nonexistent" });
      return result;
    } catch (error) {
      console.error("Failed to read file:", error.message);
      throw error; // Re-throw to surface to parent
    }
  `
})

Testando com Claude Code

Quer experimentar o mcpcodeserver com o Claude Code? Use a configuração de um comando:

./setup-claude-code-test.sh

Isso irá construir o projeto, instalar dependências de teste e mostrar exatamente o que adicionar à sua configuração do Claude Code. Veja TESTING_WITH_CLAUDE.md para instruções detalhadas.

Desenvolvimento

# Install dependencies
bun install

# Build the project
bun run build

# Watch mode for development
bun run dev

# Run the server
bun start

# Run tests
bun test                # All tests
bun run test:unit       # Unit tests only
bun run test:integration # Integration tests (requires Python)

# Code quality
bun run lint            # Check linting
bun run format          # Format code
bun run typecheck       # Type checking

Estrutura do Projeto

Veja AGENTS.md para estrutura detalhada do projeto e documentação dos componentes.

Casos de Uso

Operações Multi-Arquivo

Em vez de fazer múltiplas chamadas de ferramenta através do LLM, escreva código:

const files = ["/tmp/a.txt", "/tmp/b.txt", "/tmp/c.txt"];
const contents = await Promise.all(
  files.map(path => filesystem_read_file({ path }))
);
return contents.map(r => r.content[0].text);

Transformação de Dados

Processe dados entre chamadas de ferramenta sem intervenção do LLM:

const data = await api_fetch({ url: "https://api.example.com/data" });
const json = JSON.parse(data.content[0].text);
const filtered = json.items.filter(item => item.active);
return filtered.length;

Lógica Condicional

Tome decisões baseadas nos resultados das ferramentas:

const exists = await filesystem_read_file({ path: "/tmp/config.json" });
if (exists.isError) {
  console.log("Config doesn't exist, using defaults");
  return { source: "defaults" };
} else {
  return { source: "file", config: JSON.parse(exists.content[0].text) };
}

Recuperação de Erros

Trate erros graciosamente sem abortar todo o fluxo de trabalho:

const results = [];
for (const path of ["/tmp/a.txt", "/tmp/b.txt", "/tmp/c.txt"]) {
  try {
    const content = await filesystem_read_file({ path });
    results.push({ path, success: true, data: content });
  } catch (error) {
    results.push({ path, success: false, error: error.message });
  }
}
return results;

Integração com Servidores MCP Upstream

O mcpcodeserver pode integrar-se com servidores MCP upstream oficiais do repositório de servidores Model Context Protocol. Isso permite usar servidores MCP reais e prontos para produção junto com suas ferramentas personalizadas.

Servidores Upstream Suportados

  • filesystem: Operações de sistema de arquivos (ler, escrever, listar diretórios)
  • memory: Armazenamento chave-valor em memória
  • sqlite: Operações de banco de dados SQLite
  • github: Integração com a API do GitHub
  • brave-search: Capacidades de busca na web
  • fetch: Capacidades de requisição HTTP

Exemplo de Configuração

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/tmp/test.db"]
    }
  }
}

Testando a Integração Upstream

O projeto inclui testes abrangentes para integração com servidores upstream:

# Run upstream servers integration tests
bun tests/integration/run-upstream-tests.ts

# Or manually test with upstream config
npx mcpcodeserver --config tests/integration/upstream-test-config.json

Fluxos de Trabalho Entre Servidores

Com servidores upstream, você pode criar fluxos de trabalho poderosos entre servidores:

// Store database query results in memory and write to file
const queryResult = await sqlite_execute_sql({
  sql: "SELECT COUNT(*) as count FROM users"
});
const count = queryResult.content[0].text;

await memory_create({
  key: "user-count",
  value: count
});

await filesystem_write_file({
  path: "/tmp/user-count.txt",
  content: `Total users: ${count}`
});

Limitações

  • Tempo limite de execução: Máximo de 5 minutos (configurável, padrão 30 segundos)
  • Memória: Limitada pelo contexto da VM Node.js
  • Sem estado persistente entre execuções
  • Não é possível require/import módulos externos
  • Não é um sandbox de segurança - não execute código não confiável

Contribuindo

Contribuições são bem-vindas! Este projeto é construído com:

  • TypeScript 5.7+
  • Node.js 18+
  • MCP TypeScript SDK 1.20+
  • Zod para validação

Veja CONTRIBUTING.md para diretrizes detalhadas de contribuição.

Suporte

Se você achar este projeto útil, considere me pagar um café!

Buy Me A Coffee

Licença

MIT

Recursos