Memoria de código local

<img width="3024" height="1720" alt="image" src="https://github.com/user-attachments/assets/62691eef-a610-4bf2-8d9c-2f09d4345ec9" />

Servidor MCP mínimo para indexar, solo en memoria, los símbolos exportados de un proyecto TypeScript/React. Permite a un agente localizar definiciones, referencias, relaciones y estructura sin abrir ni recorrer repetidamente todo el repositorio. Incluye también un panel visual local y opcional.

Este proyecto existe como alternativa auditable a un MCP de terceros que motivó preocupación por incluir comportamiento de descarga, red y procesos hijo no acorde con sus garantías documentadas. Aquí no hay llamadas de red salientes, telemetría, actualizador, binarios, base de datos, scripts de instalación ni procesos hijo: se instala con npm install y se ejecuta con node.

Ventajas reales

No todas las herramientas ahorran lo mismo, y el ahorro depende del tamaño del proyecto indexado. Esto es lo que se ha comprobado de verdad, no una promesa genérica:

• buscar_referencias es más preciso que grep. Al basarse en el árbol de sintaxis (ts-morph), no en texto, no devuelve como resultado un comentario que menciona el nombre o una variable distinta que se llama igual por coincidencia. Evita la ronda de "espera, eso no es un uso real" que sí aparece buscando por texto.
• trazar_camino resuelve en una llamada lo que a mano son varias rondas de búsqueda encadenada. Rastrear "qué depende de qué depende de qué" a través de varios saltos, buscando y leyendo cada eslabón, es exactamente el tipo de tarea que se vuelve lenta y cara a mano y barata con el grafo ya construido.
• resumen_arquitectura da una orientación inicial rápida en un proyecto que no se conoce, en vez de varias exploraciones de carpetas y ficheros para hacerse una idea de la estructura.
• El ahorro crece con el tamaño del proyecto y con cuántas veces se repite este tipo de búsqueda en una sesión, no es un número fijo. En un proyecto pequeño la diferencia frente a buscar a mano es modesta; en un árbol grande, o reutilizando este mismo índice entre varios proyectos, el coste de haberlo construido una vez se amortiza mucho mejor.

Requisitos y uso

• Node.js 20 o posterior.
• Una ruta local que contenga ficheros .ts o .tsx.

npm install
npm run build
node dist/servidor.js /ruta/al/proyecto-o-src

También se puede indicar la raíz con la variable RAIZ_PROYECTO. El servidor escribe exclusivamente el protocolo MCP en stdout; los errores de arranque van a stderr.

El índice se reconstruye al arrancar. Usa el tsconfig.json y .gitignore más cercanos hacia arriba para comprender aliases y exclusiones, pero solo indexa declaraciones ubicadas bajo la raíz indicada. Además excluye siempre .git, node_modules, dist, build y coverage.

Cómo se usa en la práctica

Estas herramientas no se invocan escribiendo JSON a mano. MCP es un protocolo entre un agente (Claude Code, u otro cliente MCP) y este servidor: tú hablas en lenguaje normal con el agente, y es el agente quien decide llamar a una herramienta y con qué argumentos, sin que tú veas ese paso intermedio. Por ejemplo, si le preguntas a Claude Code "¿dónde está definido SafeMarkdown?" estando este servidor registrado, el agente llama por su cuenta a buscar_simbolo con { "nombre": "SafeMarkdown" } y te devuelve la respuesta ya traducida a una frase. El bloque JSON de cada herramienta de abajo es la forma de esos argumentos, documentada para quien programe o audite el servidor — no algo que tengas que teclear tú.

Si quieres probar una herramienta directamente, sin ningún agente de por medio, existe el Inspector oficial de MCP: abre un panel web con un formulario por cada herramienta, para llamarla a mano y ver la respuesta real. Se descarga por npx la primera vez que se ejecuta — es la única vez que este proyecto toca la red, y es una acción tuya explícita, no algo que el servidor haga solo.

npm run build
npx @modelcontextprotocol/inspector node dist/servidor.js /ruta/al/proyecto

Verificado tal cual (con Node 22.12): imprime en la terminal una URL del tipo http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=... y abre esa página en el navegador automáticamente. Ese token en la URL es normal — es la autenticación local del propio Inspector contra su servidor proxy, no una fuga de nada. Elige una herramienta de la lista de la izquierda, rellena sus campos (o déjalos vacíos si no tiene, como reindexar) y pulsa "Run" — verás la respuesta JSON tal cual la generaría este servidor. Es la forma más rápida de entender qué hace cada una antes de registrarlo en Claude Code.

Existe una v2 del Inspector (npx @modelcontextprotocol/inspector@latest) con más funciones, pero pide Node ≥ 22.19; con versiones de Node anteriores arranca igualmente con un aviso de compatibilidad. Si tu Node es más antiguo, usa el comando sin @latest — resuelve a la v1, que solo recibe parches de seguridad pero funciona sin avisos.

Herramientas MCP

Referencia de las diez herramientas: qué hace cada una y la forma exacta de sus argumentos. Las respuestas son JSON dentro del contenido textual MCP. Las rutas siempre son relativas a la raíz indexada.

buscar_simbolo

Encuentra todas las definiciones exportadas con el nombre exacto. Los nombres duplicados producen varios resultados.

Argumentos:

{ "nombre": "SafeMarkdown" }

buscar_texto

Busca palabras en el nombre del símbolo —separando camelCase y PascalCase— y en la primera línea de su JSDoc. Tolera erratas pequeñas mediante distancia de Levenshtein, pero no entiende sinónimos ni relaciones entre conceptos.

Argumentos:

{ "consulta": "markdown seguro" }

buscar_referencias

Devuelve cada línea donde el símbolo se importa o usa, ordenada por fichero y línea.

Argumentos:

{ "nombre": "useAuth" }

listar_exports

Lista lo exportado directamente o reexportado por el fichero indicado.

Argumentos:

{ "ruta_relativa": "src/components/content/SafeMarkdown.tsx" }

reindexar

Fuerza una reconstrucción completa tras cambiar el código, sin reiniciar el servidor. No necesita argumentos — en el Inspector, se llama con el formulario vacío.

resumen_arquitectura

Devuelve el árbol de carpetas que contienen ficheros indexados. Cada carpeta incluye el total de símbolos exportados de su subárbol y su agrupación por tipo. No necesita argumentos.

obtener_fragmento

Devuelve literalmente un intervalo de líneas de un fichero indexado. Solo acepta rutas relativas, no permite salir de la raíz y limita cada respuesta a 200 líneas.

Argumentos:

{ "ruta_relativa": "src/indexador.ts", "linea_inicio": 1, "linea_fin": 40 }

cobertura_indexado

Cuenta todos los ficheros .ts y .tsx bajo la raíz, indica cuántos entraron en el índice y enumera cada exclusión con su motivo: .gitignore, directorio excluido, fichero .d.ts u otra causa explícita. No necesita argumentos.

trazar_camino

Busca en anchura un camino de referencias de hasta 6 saltos. Una arista A → B significa que el símbolo exportado B referencia a A; por tanto, el camino avanza desde un símbolo hacia los símbolos que dependen de él. Si no existe un camino, la respuesta lo dice expresamente y devuelve encontrado: false.

Argumentos:

{ "desde": "useAuth", "hasta": "App" }

buscar_por_tipo

Lista todos los símbolos de uno de estos tipos: función, componente React, clase, interfaz, tipo, constante o enum.

Argumentos:

{ "tipo": "componente React" }

Un símbolo o fichero inexistente devuelve un error MCP legible, no una excepción sin controlar. Un símbolo existente sin referencias devuelve correctamente una lista vacía.

Panel visual

El panel es un proceso separado del servidor MCP. Tras compilar, se puede lanzar explícitamente sobre la raíz completa de un proyecto:

npm run dashboard -- /ruta/al/proyecto

Reindexa al arrancar, sirve la página en http://127.0.0.1:8420 y publica los datos en GET /grafo con la forma { "nodos": [...], "aristas": [...] }. El puerto se puede cambiar con un segundo argumento o con PUERTO_DASHBOARD:

npm run dashboard -- /ruta/al/proyecto 9123
PUERTO_DASHBOARD=9123 RAIZ_PROYECTO=/ruta/al/proyecto npm run dashboard

El servidor usa node:http y escucha exclusivamente en 127.0.0.1, nunca en 0.0.0.0. La página, el CSS y el JavaScript son locales y no cargan fuentes, scripts, imágenes ni bibliotecas desde CDN o desde Internet. Escuchar en localhost para que el navegador del propio usuario abra un panel solicitado explícitamente no contradice la regla de cero llamadas salientes: escuchar localmente y llamar hacia fuera son categorías distintas, y el panel nunca envía datos a otro servidor.

La visualización está escrita con Canvas y JavaScript vainilla. La disposición aplica en las tres dimensiones repulsión entre nodos, atracción en cada referencia, gravedad suave hacia el centro y amortiguación. Una cámara orbital y una proyección en perspectiva convierten ese espacio 3D en la imagen 2D; el tamaño de los nodos representa su número de conexiones y la profundidad modifica tamaño, brillo y aristas.

Arrastrar con el botón izquierdo sobre el fondo rota la cámara; la rueda hace zoom hacia el punto bajo el cursor; el botón derecho, o Mayús más arrastre, desplaza la vista. El botón Restablecer vista recupera la orientación, el zoom y el desplazamiento iniciales. Al pasar el ratón o hacer clic en un nodo se muestran nombre, tipo, fichero, línea y métricas de conexiones contra su posición proyectada actual.

Claude Code

Añade este bloque a la configuración MCP de Claude Code. Las dos rutas son absolutas porque Claude Code puede iniciar el servidor desde cualquier directorio:

{
  "mcpServers": {
    "memoria-codigo-local": {
      "command": "node",
      "args": [
        "/Users/pedroleridanieto/Desktop/Proyectos IA/codebase-memory-local/dist/servidor.js",
        "/Users/pedroleridanieto/Desktop/Proyectos IA/tech-study-tracker"
      ]
    }
  }
}

Si solo interesa el código fuente, el segundo argumento puede terminar en /src; las rutas devueltas serán entonces relativas a src.

Diseño auditable

• src/indexador.ts: recorrido local, análisis con ts-morph e índice en memoria.
• src/servidor.ts: adaptación del índice a diez herramientas MCP por stdio.
• src/dashboard.ts: servidor HTTP local separado y visualización Canvas autocontenida.
• src/indexador.test.ts: proyecto sintético y aserciones exactas con node:test.
• Las funciones o constantes exportadas cuyo nombre comienza en mayúscula y están en .tsx se clasifican como componentes React. Es una heurística pequeña y explícita; no intenta inferir el tipo de retorno.
• Las referencias que caen en la misma línea se deduplican para que una línea de importación con varias apariciones no consuma resultados repetidos.
• El grafo solo enlaza símbolos cuando la referencia está dentro de la declaración de otro símbolo exportado. Un import a nivel de fichero continúa apareciendo en buscar_referencias, pero no se inventa un nodo de fichero para representarlo.

Verificación

npm run build
npm test

Los tests fabrican proyectos temporales con exports e imports conocidos y comprueban valores completos de definiciones, referencias, arquitectura, fragmentos, cobertura, caminos y filtros por tipo.