# 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`.

```sh
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.

```sh
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:
```json
{ "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:
```json
{ "consulta": "markdown seguro" }
```

### `buscar_referencias`

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

Argumentos:
```json
{ "nombre": "useAuth" }
```

### `listar_exports`

Lista lo exportado directamente o reexportado por el fichero indicado.

Argumentos:
```json
{ "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:
```json
{ "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:
```json
{ "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:
```json
{ "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:

```sh
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`:

```sh
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:

```json
{
  "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

```sh
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.