Synapse

Servidor de contexto de código estrutural para agentes de IA — zero banco de dados vetorial, zero API de embedding, totalmente local.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Synapse MCP

Synapse MCP

CI License: MIT Node ≥ 18 Tests: 301

Um servidor de contexto estrutural de código que conecta seu repositório local a assistentes de IA por meio do Model Context Protocol.

Em vez de copiar e colar arquivos em um prompt, o Synapse permite que seu assistente de IA explore dinamicamente sua base de código — buscando apenas o código necessário, quando necessário. O resultado: menos desperdício de contexto, respostas mais inteligentes e um fluxo de trabalho que escala para projetos grandes — sem necessidade de configurar banco de dados vetorial ou API de embeddings.

AI Assistant  ──MCP──►  Synapse MCP  ──fs/git──►  Your Repository
   (pulls)               (server)                   (local)

Status: Estágio inicial, em desenvolvimento ativo. Contribuições e relatórios de bugs são bem-vindos — veja Contribuindo.

Por que o Synapse?

A maioria das ferramentas de codificação com IA já indexa arquivos. O Synapse resolve um problema diferente: qualidade de contexto em escala.

ProblemaSolução do Synapse
Ler um arquivo inteiro quando você só precisa da superfície da APIget_semantic_context com outline_only — apenas assinaturas, ≤ 50% do conteúdo completo
A IA não sabe quais arquivos existem em um projeto desconhecidoget_project_index — mapa de símbolos completo com ≤ 40% do tamanho bruto do código-fonte, em uma única chamada
"Revise minhas alterações" exige colar o diff manualmenteget_changed_files — diff git estruturado, ciente do git por padrão
Labirintos de dependências preenchendo a janela de contextoLimite configurável de depth na travessia de imports

As taxas de compressão acima são aplicadas como orçamentos de testes automatizados — não estimativas de marketing.

Por que não embeddings vetoriais?

A maioria dos servidores MCP de contexto de código usa busca semântica apoiada por um banco de dados vetorial (ex.: Milvus, Qdrant) e uma API de embeddings (OpenAI, VoyageAI). Isso lhes dá uma capacidade real que o Synapse não possui: encontrar código por significado conceitual ("encontre a lógica de autenticação") em vez de por estrutura ou texto.

O Synapse troca essa capacidade por um conjunto diferente de propriedades:

  • Zero dependências externas — sem chaves de API, sem banco de dados vetorial, sem provedor de embeddings para configurar
  • Custo recorrente zero — sem cobranças por token de embedding, sem fatura de banco de dados hospedado
  • Totalmente local e determinístico — a mesma entrada sempre produz a mesma saída, nada sai da sua máquina, nada para indexar antecipadamente
  • Instantâneo em qualquer repositório — sem etapa de indexação antes do primeiro uso (veja Desempenho: 120–257 ms em repositórios reais)

Se você precisa de busca semântica em linguagem natural em milhões de linhas em vários idiomas, um servidor com suporte vetorial é a ferramenta mais adequada. Se você quer contexto estrutural (assinaturas, grafos de dependência, diffs) sem montar infraestrutura, o Synapse foi feito para isso.

Ferramentas

get_project_index

Retorna um mapa semântico compactado de todo o projeto: todas as funções exportadas, classes, interfaces, tipos, enums e constantes de nível superior com suas assinaturas — sem corpos. É a primeira chamada certa ao explorar uma base de código desconhecida.

# Project Index: my-app (47 files, 312 symbols)

## src/services/user-service.ts
  UserService (class) [export]
    constructor(db: Database)
    findById(id: string): Promise<User | null>
    create(data: CreateUserDto): Promise<User>

## src/models/user.ts
  User (interface) [export]
    id: string
    email: string
    createdAt: Date
  createUser(data: Partial<User>): User [export]

Parâmetros: file_pattern (glob para restringir o escopo), include_non_exported, output_format (padrão "markdown" · "json" para saída estruturada)

Use output_format: "json" para obter os dados brutos de símbolos como um objeto estruturado, que é mais fácil de pós-processar programaticamente:

{
  "root": "/path/to/project",
  "totalFiles": 47,
  "totalSymbols": 312,
  "files": [
    {
      "relativePath": "src/services/user-service.ts",
      "language": "typescript",
      "symbols": [...]
    }
  ]
}

Projetos grandes: a saída cresce linearmente com o número de símbolos exportados. Para monorepos ou projetos com 500+ arquivos, use file_pattern para restringir o índice a uma área por vez — ex.: "src/services/**/*.ts".

get_semantic_context

Retorna o conteúdo de um arquivo junto com seu grafo de dependências local — tudo o que a IA precisa para entender o código em contexto.

Adicione outline_only: true para obter assinaturas sem corpos de implementação. A saída é garantida pelo conjunto de benchmarks a ser ≤ 50% do comprimento total do conteúdo, preservando a compreensão estrutural completa.

Parâmetros: file_path (obrigatório), depth (saltos de import, padrão: 2), outline_only, output_format (padrão "markdown" · "json" para saída estruturada)

get_changed_files

Lista arquivos alterados desde uma referência git, agrupados por status (Adicionado / Modificado / Excluído / Renomeado), com contagens de linhas opcionais e diff unificado completo.

Changed files since `main` (8 files):

**Added (2):**
  src/services/payment.ts (+120 −0)
  tests/unit/payment.test.ts (+89 −0)

**Modified (5):**
  src/models/order.ts (+14 −3)
  ...

**Summary:** +245 −18 lines

Parâmetros: base_ref (padrão: HEAD~1), include_diff, file_pattern

get_project_tree

Visão estruturada do repositório, respeitando as regras de .gitignore.

Parâmetros: path, max_depth, show_hidden

search_codebase

Busca rápida de texto ou regex em todo o projeto, retornando correspondências com caminhos de arquivo e números de linha. Usa ripgrep quando disponível; caso contrário, usa um scanner puro em Node.js.

Parâmetros: query (obrigatório), file_pattern, is_regex, max_results

Suporte a linguagens

O Synapse usa ts-morph (API do compilador TypeScript) para análise profunda de TypeScript e JavaScript. Para outras linguagens, aplica extração baseada em regex de nomes de funções e classes.

RecursoTypeScript / JSPython · Go · RustOutras
get_project_tree✓✓✓
search_codebase✓✓✓
get_semantic_context — código-fonte completo✓✓✓
get_semantic_context — grafo de dependências✓——
get_semantic_context outline_only✓ assinaturas completas✓ apenas nomes—
get_project_index✓ assinaturas completas✓ apenas nomes—

A travessia do grafo de dependências (seguindo cadeias de import/require) é exclusiva para TypeScript/JavaScript. Para todas as outras linguagens, o Synapse ainda lê e pesquisa arquivos normalmente — apenas não percorre o grafo de imports.

Nota: a travessia do grafo de dependências segue tanto imports relativos (./foo, ../bar) quanto aliases de caminho configurados via tsconfig.json compilerOptions.paths (ex.: @/components/Foo), desde que um tsconfig.json esteja presente na raiz do projeto. Projetos sem tsconfig.json usam apenas resolução relativa.

Instalação

Instalação global (recomendada):

npm install -g synapse-code-mcp

Executar sem instalar:

npx synapse-code-mcp --root /path/to/your/project

Configuração

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["synapse-code-mcp", "--root", "/absolute/path/to/your/project"]
    }
  }
}

Claude Code (CLI)

claude mcp add synapse -- npx synapse-code-mcp --root /path/to/your/project

Ou adicione diretamente em ~/.claude/settings.json:

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
    }
  }
}

Cursor

Adicione em .cursor/mcp.json no seu diretório inicial ou na raiz do projeto:

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
    }
  }
}

Windsurf

Adicione em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
    }
  }
}

Dica: Substitua /path/to/your/project pelo caminho absoluto do repositório que você deseja servir. Você pode executar várias instâncias do Synapse — uma por projeto — cada uma com uma chave diferente em mcpServers.

Configuração

Flags de CLI

Options:
  --root <path>                  Project root directory (default: cwd)
  --max-file-size <bytes>        Skip files larger than this (default: 524288 = 512 KB)
  --max-search-results <n>       Cap on search results returned (default: 50)
  --max-tree-depth <n>           Maximum directory depth for tree view (default: 5)
  --max-dependency-depth <n>     Import hops for semantic context (default: 2)
  --log-level <level>            debug | info | warn | error (default: info)

Arquivo de configuração por projeto

Coloque um synapse.config.json na raiz do seu projeto para substituir os padrões daquele projeto:

{
  "maxFileSize": 1048576,
  "maxDependencyDepth": 3,
  "extraIgnorePatterns": ["*.generated.ts", "**/__mocks__/**"],
  "cacheEnabled": true
}

cacheEnabled (padrão true) controla o cache de índice incremental em disco (.synapse-cache/index.json) usado por get_project_index e get_semantic_context para evitar reanalisar arquivos inalterados. Defina como false para desativá-lo.

Todos os campos são opcionais. As flags de CLI têm precedência sobre synapse.config.json.

Desempenho

Medido em repositórios TypeScript de código aberto reais (execução única, clone --depth 1, sem cache aquecido):

RepositórioArquivos indexadosTempoCrescimento de heap
zod55120 ms3 MB
Compilador TypeScript src/247257 ms24 MB

O conjunto de benchmarks automatizados impõe limites superiores em um fixture sintético (3 000 arquivos mínimos de .ts) para detectar regressões em condições de pior caso:

OperaçãoOrçamento de CI (fixture sintético)
get_project_tree — 3 000 arquivos5 s
get_semantic_context — profundidade 310 s
get_changed_files2 s
get_project_index — 60 arquivos30 s
get_project_index — 600 arquivos120 s

Os orçamentos de CI são deliberadamente margens de segurança generosas, não estimativas de desempenho — eles existem para detectar regressões catastróficas (ex.: um bug acidental de O(n²)), não para prever tempos do mundo real. Os números de repositórios reais acima são a referência significativa para o desempenho esperado. Para monorepos grandes (1 000+ arquivos), use file_pattern para restringir o índice a uma área por vez.

Segurança

O Synapse é um servidor somente leitura. Ele nunca grava no sistema de arquivos nem modifica o repositório git.

  • Proteção contra travessia de caminho — cada leitura de arquivo passa por resolveAndValidate(root, path), que lança um erro de PATH_ESCAPE se o caminho resolvido escapar da raiz do projeto. O cliente de IA recebe o código de erro, nunca o conteúdo do arquivo.
  • Escopo da raiz — apenas a árvore de diretórios sob --root é acessível. Caminhos apontando para fora (ex.: ../../etc/passwd) são rejeitados na camada de validação.
  • Limite de tamanho de arquivo — arquivos maiores que maxFileSize (padrão 512 KB) são rejeitados antes da leitura.
  • Detecção de binários — artefatos compilados e arquivos binários são detectados e ignorados automaticamente.
  • Sem chamadas de rede de saída — o Synapse se comunica apenas pelo pipe stdio local com o cliente MCP. Ele não faz requisições HTTP.

Fluxos de trabalho sugeridos

Explorar uma nova base de código:

1. get_project_index()
   → Understand the full shape of the project in one call

2. get_semantic_context("src/core/engine.ts", outline_only: true)
   → Inspect a module's API surface without reading implementation

3. get_semantic_context("src/core/engine.ts")
   → Read full source + dependency graph for the relevant file

Revisão de código antes de um PR:

1. get_changed_files(base_ref: "main")
   → See what changed, grouped and summarised

2. get_changed_files(base_ref: "main", include_diff: true)
   → Full unified diff in context

3. get_semantic_context("src/changed-file.ts")
   → Understand the context around a changed file

Depurar um recurso:

1. search_codebase("handlePayment")
   → Find where the symbol is defined and used

2. get_semantic_context("src/services/payment.ts", depth: 3)
   → Pull the file + all its local dependencies

Requisitos

  • Node.js ≥ 18
  • Git — necessário apenas para get_changed_files
  • ripgrep (opcional) — busca significativamente mais rápida; o Synapse usa um scanner puro em Node.js se rg não estiver em $PATH

Desenvolvimento

git clone https://github.com/Juanmidev1/synapse-code-mcp.git
cd synapse-code-mcp
npm install

npm run dev          # watch mode (tsx, no compile step)
npm test             # run all tests (Vitest)
npm run typecheck    # type-check without emitting
npm run lint         # ESLint
npm run build        # compile to dist/

Testar com o MCP Inspector

npm run build
npx @modelcontextprotocol/inspector dist/index.js --root .

Isso abre uma interface de navegador onde você pode invocar todas as ferramentas interativamente e inspecionar suas entradas/saídas.

Estrutura do projeto

src/
  index.ts              CLI entry point, argument parsing
  server.ts             MCP server, tool registration
  tools/                Thin tool handlers (validation + formatting only)
  core/
    fs/                 File tree building, file reading, ignore resolution
    search/             ripgrep adapter + pure-Node fallback
    analysis/           Dependency graph (ts-morph), outline extractor, project indexer, index cache
    git/                Git adapter (diff, changed files)
  config/               Config loading and Zod validation
  types/                Shared TypeScript interfaces
  utils/                Logger (pino), path helpers, typed errors
tests/
  unit/                 Per-module unit tests
  integration/          Tool handler integration tests
  protocol/             End-to-end MCP protocol tests (InMemoryTransport)
  performance/          Benchmark suite with time and heap budgets
  build/                Tests against the compiled dist/ output (catches source-vs-build divergence)

Roadmap

Veja ROADMAP.md para o que está planejado e quais ideias estão abertas para contribuições da comunidade.

Contribuindo

Este projeto está em desenvolvimento inicial ativo. Relatórios de bugs, solicitações de recursos e pull requests são todos bem-vindos — a base de código é intencionalmente pequena e fácil de navegar.

  • CONTRIBUTING.md — como configurar o ambiente, executar testes, convenções de commit e regras arquiteturais
  • CODE_OF_CONDUCT.md — padrões da comunidade (Contributor Covenant 2.1)
  • ROADMAP.md — o que está planejado e o que está aberto para PRs da comunidade

Novo no projeto? Navegue pelas issues marcadas com good first issue para os melhores pontos de entrada.

Licença

MIT