Synapse

Servidor de contexto de código estructural para agentes de IA — sin base de datos vectorial, sin API de embeddings, completamente local.

GitHub

Prueba este MCPPatrocinado

Documentación

Synapse MCP

Un servidor de contexto estructural de código que conecta tu repositorio local con asistentes de IA mediante el Model Context Protocol.

En lugar de copiar y pegar archivos en un prompt, Synapse permite que tu asistente de IA explore dinámicamente tu base de código — extrayendo solo el código que necesita, cuando lo necesita. El resultado: menos desperdicio de contexto, respuestas más inteligentes y un flujo de trabajo que escala a proyectos grandes — sin necesidad de configurar una base de datos vectorial ni una API de embeddings.

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

Estado: En etapa temprana, en desarrollo activo. Las contribuciones y los informes de errores son bienvenidos — consulta Contribuir.

¿Por qué Synapse?

La mayoría de las herramientas de codificación con IA ya indexan archivos. Synapse resuelve un problema diferente: calidad de contexto a escala.

Problema	Solución de Synapse
Leer un archivo completo cuando solo necesitas su superficie de API	`get_semantic_context` con `outline_only` — solo firmas, ≤ 50 % del contenido completo
La IA no sabe qué archivos existen en un proyecto desconocido	`get_project_index` — mapa de símbolos completo con ≤ 40 % del tamaño del código fuente, en una sola llamada
"Revisa mis cambios" requiere pegar el diff manualmente	`get_changed_files` — diff de git estructurado, consciente de git por defecto
Los callejones sin salida de dependencias llenan la ventana de contexto	Límite configurable de `depth` en el recorrido de importaciones

Las proporciones de compresión anteriores se aplican como presupuestos de pruebas automatizadas, no como estimaciones de marketing.

¿Por qué no embeddings vectoriales?

La mayoría de los servidores MCP de contexto de código usan búsqueda semántica respaldada por una base de datos vectorial (p. ej., Milvus, Qdrant) y una API de embeddings (OpenAI, VoyageAI). Eso les da una capacidad real que Synapse no tiene: encontrar código por significado conceptual ("encuentra la lógica de autenticación") en lugar de por estructura o texto.

Synapse intercambia esa capacidad por un conjunto diferente de propiedades:

Cero dependencias externas — sin claves de API, sin base de datos vectorial, sin proveedor de embeddings que configurar
Cero costo recurrente — sin cargos por tokens de embeddings, sin factura de base de datos alojada
Totalmente local y determinista — la misma entrada siempre produce la misma salida, nada sale de tu máquina, nada que indexar de antemano
Instantáneo en cualquier repositorio — sin paso de indexación antes del primer uso (consulta Rendimiento: 120–257 ms en repositorios reales)

Si necesitas búsqueda semántica en lenguaje natural en millones de líneas en muchos idiomas, un servidor con respaldo vectorial es la mejor herramienta. Si quieres contexto estructural (firmas, grafos de dependencias, diffs) sin levantar infraestructura, Synapse está diseñado para eso.

Herramientas

`get_project_index`

Devuelve un mapa semántico comprimido de todo el proyecto: todas las funciones exportadas, clases, interfaces, tipos, enums y constantes de nivel superior con sus firmas — sin cuerpos. Es la primera llamada correcta al explorar una base de código desconocida.

# 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 acotar el alcance), include_non_exported, output_format ("markdown" por defecto · "json" para salida estructurada)

Usa output_format: "json" para obtener los datos de símbolos sin procesar como un objeto estructurado, que es más fácil de posprocesar programáticamente:

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

Proyectos grandes: la salida crece linealmente con el número de símbolos exportados. Para monorepos o proyectos con 500+ archivos, usa file_pattern para acotar el índice a un área a la vez — p. ej., "src/services/**/*.ts".

`get_semantic_context`

Devuelve el contenido de un archivo junto con su grafo de dependencias local — todo lo que la IA necesita para entender el código en contexto.

Agrega outline_only: true para obtener firmas sin cuerpos de implementación. La salida está limitada por el conjunto de pruebas para ser ≤ 50 % de la longitud del contenido completo, preservando la comprensión estructural completa.

Parámetros: file_path (obligatorio), depth (saltos de importación, por defecto: 2), outline_only, output_format ("markdown" por defecto · "json" para salida estructurada)

`get_changed_files`

Lista los archivos modificados desde una referencia de git, agrupados por estado (Agregado / Modificado / Eliminado / Renombrado), con recuentos de líneas opcionales y 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 (por defecto: HEAD~1), include_diff, file_pattern

`get_project_tree`

Vista estructurada del repositorio, respetando las reglas de .gitignore.

Parámetros: path, max_depth, show_hidden

`search_codebase`

Búsqueda rápida de texto o regex en todo el proyecto, devolviendo coincidencias con rutas de archivo y números de línea. Usa ripgrep cuando esté disponible; de lo contrario, recurre a un escáner puro de Node.js.

Parámetros: query (obligatorio), file_pattern, is_regex, max_results

Soporte de lenguajes

Synapse usa ts-morph (API del compilador de TypeScript) para el análisis profundo de TypeScript y JavaScript. Para otros lenguajes, aplica extracción basada en regex de nombres de funciones y clases.

Característica	TypeScript / JS	Python · Go · Rust	Otros
`get_project_tree`	✓	✓	✓
`search_codebase`	✓	✓	✓
`get_semantic_context` — código fuente completo	✓	✓	✓
`get_semantic_context` — grafo de dependencias	✓	—	—
`get_semantic_context outline_only`	✓ firmas completas	✓ solo nombres	—
`get_project_index`	✓ firmas completas	✓ solo nombres	—

El recorrido del grafo de dependencias (siguiendo cadenas de import/require) es solo para TypeScript/JavaScript. Para todos los demás lenguajes, Synapse aún lee y busca archivos normalmente — simplemente no recorre el grafo de importaciones.

Nota: el recorrido del grafo de dependencias sigue tanto importaciones relativas (./foo, ../bar) como alias de ruta configurados mediante tsconfig.json compilerOptions.paths (p. ej., @/components/Foo), siempre que haya un tsconfig.json presente en la raíz del proyecto. Los proyectos sin un tsconfig.json recurren a la resolución solo relativa.

Instalación

Instalación global (recomendada):

npm install -g synapse-code-mcp

Ejecutar sin instalar:

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

Configuración

Claude Desktop

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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

O agrega directamente a ~/.claude/settings.json:

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

Cursor

Agrega a .cursor/mcp.json en tu directorio de inicio o raíz del proyecto:

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

Windsurf

Agrega a ~/.codeium/windsurf/mcp_config.json:

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

Consejo: Reemplaza /path/to/your/project con la ruta absoluta al repositorio que quieres servir. Puedes ejecutar múltiples instancias de Synapse — una por proyecto — cada una con una clave diferente bajo mcpServers.

Configuración

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

Archivo de configuración por proyecto

Coloca un synapse.config.json en la raíz de tu proyecto para anular los valores predeterminados de ese proyecto:

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

cacheEnabled (por defecto true) controla la caché de índice incremental en disco (.synapse-cache/index.json) usada por get_project_index y get_semantic_context para omitir el reanálisis de archivos sin cambios. Establécelo en false para deshabilitarlo.

Todos los campos son opcionales. Las banderas de CLI tienen prioridad sobre synapse.config.json.

Rendimiento

Medido en repositorios reales de TypeScript de código abierto (ejecución única, clon de --depth 1, sin caché caliente):

Repositorio	Archivos indexados	Tiempo	Crecimiento de heap
zod	55	120 ms	3 MB
Compilador de TypeScript `src/`	247	257 ms	24 MB

El conjunto de pruebas automatizadas impone límites superiores en un fixture sintético (3 000 archivos mínimos de .ts) para detectar regresiones en condiciones de peor caso:

Operación	Presupuesto de CI (fixture sintético)
`get_project_tree` — 3 000 archivos	5 s
`get_semantic_context` — profundidad 3	10 s
`get_changed_files`	2 s
`get_project_index` — 60 archivos	30 s
`get_project_index` — 600 archivos	120 s

Los presupuestos de CI son márgenes de seguridad deliberadamente generosos, no estimaciones de rendimiento — existen para detectar regresiones catastróficas (p. ej., un error accidental de O(n²)), no para predecir tiempos del mundo real. Los números de repositorios reales anteriores son la referencia significativa para el rendimiento esperado. Para monorepos grandes (1 000+ archivos), usa file_pattern para acotar el índice a un área a la vez.

Seguridad

Synapse es un servidor de solo lectura. Nunca escribe en el sistema de archivos ni modifica el repositorio de git.

Protección contra recorrido de rutas — cada lectura de archivo pasa por resolveAndValidate(root, path), que lanza un error de PATH_ESCAPE si la ruta resuelta escapa de la raíz del proyecto. El cliente de IA recibe el código de error, nunca el contenido del archivo.
Alcance de raíz — solo el árbol de directorios bajo --root es accesible. Las rutas que apuntan fuera (p. ej., ../../etc/passwd) se rechazan en la capa de validación.
Límite de tamaño de archivo — los archivos más grandes que maxFileSize (por defecto 512 KB) se rechazan antes de la lectura.
Detección de binarios — los artefactos compilados y los archivos binarios se detectan y omiten automáticamente.
Sin llamadas de red salientes — Synapse se comunica solo a través de la tubería stdio local con el cliente MCP. No realiza solicitudes HTTP.

Flujos de trabajo sugeridos

Explorar una nueva 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

Revisión de código antes de un 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 una característica:

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 — requerido solo para get_changed_files
ripgrep (opcional) — búsqueda significativamente más rápida; Synapse recurre a un escáner puro de Node.js si rg no está en $PATH

Desarrollo

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/

Probar con MCP Inspector

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

Esto abre una interfaz de navegador donde puedes invocar todas las herramientas de forma interactiva e inspeccionar sus entradas/salidas.

Estructura del proyecto

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)

Hoja de ruta

Consulta ROADMAP.md para ver lo que está planificado y qué ideas están abiertas para contribuciones de la comunidad.

Contribuir

Este proyecto está en desarrollo temprano activo. Los informes de errores, las solicitudes de características y las solicitudes de extracción son bienvenidos — la base de código es intencionalmente pequeña y fácil de navegar.

CONTRIBUTING.md — cómo configurar el entorno, ejecutar pruebas, convenciones de commits y reglas arquitectónicas
CODE_OF_CONDUCT.md — estándares de la comunidad (Contributor Covenant 2.1)
ROADMAP.md — lo que está planificado y lo que está abierto para PRs de la comunidad

¿Nuevo en el proyecto? Explora los problemas etiquetados como good first issue para los mejores puntos de entrada.

Licencia

MIT