⚔ token-savior

Deja de alimentar a tu IA con bases de código completas. Dale un bisturí en su lugar.

Python 3.11+ MCP

Un servidor MCP que indexa tu base de código estructuralmente y expone herramientas de consulta quirúrgicas, para que tu agente de IA lea 200 caracteres en lugar de 200 archivos.

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)
analyze_config()                      →  finds duplicates, secrets, orphan keys

Medido en 782 sesiones reales: 99% de reducción de tokens.

Por qué existe esto

Cada sesión de programación con IA comienza de la misma manera: el agente usa cat o grep, lee una docena de archivos para encontrar una función y luego infla su contexto tratando de entender qué más podría romperse. Al final, la mitad de tu presupuesto de tokens se ha ido antes de la primera edición.

token-savior reemplaza ese patrón por completo. Construye un índice estructural una vez, lo mantiene sincronizado con git automáticamente y responde "dónde está X", "qué llama a X" y "qué se rompe si cambio X" en tiempo de sub-milisegundos, con respuestas ajustadas a la respuesta, no a la base de código.

Números

Ahorro de tokens en sesiones reales

Proyecto	Sesiones	Consultas	Caracteres usados	Caracteres (ingenuos)	Ahorro
project-alpha	35	360	4,801,108	639,560,872	99%
project-beta	26	189	766,508	20,936,204	96%
project-gamma	30	232	410,816	3,679,868	89%
TOTAL	92	782	5,981,476	664,229,092	99%

"Caracteres (ingenuos)" = tamaño total de fuente de todos los archivos que el agente habría leído con cat/grep. Estos ahorros son agnósticos al modelo: el índice reduce la presión sobre la ventana de contexto independientemente del proveedor.

Tiempo de respuesta de consulta (sub-milisegundo en 1.1M de líneas)

Consulta	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0.01ms	0.01ms	0.03ms	0.08ms
`get_dependencies`	0.00ms	0.00ms	0.00ms	0.01ms
`get_change_impact`	0.02ms	0.00ms	2.81ms	0.45ms
`get_function_source`	0.01ms	0.02ms	0.03ms	0.10ms

Rendimiento de construcción del índice

Proyecto	Archivos	Líneas	Tiempo de índice	Memoria
Proyecto pequeño	36	7,762	0.9s	2.4 MB
FastAPI	2,556	332,160	5.7s	55 MB
Django	3,714	707,493	36.2s	126 MB
CPython	2,464	1,115,334	55.9s	197 MB

Con la caché persistente, los reinicios posteriores omiten la construcción completa. CPython pasa de 56s → menos de 1s con acierto de caché.

Qué cubre

Lenguaje / Formato	Archivos	Extractos
Python	`.py`, `.pyw`	Funciones, clases, métodos, importaciones, grafo de dependencias
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	Funciones, funciones flecha, clases, interfaces, alias de tipo
Go	`.go`	Funciones, métodos (receptor), structs, interfaces, alias de tipo
Rust	`.rs`	Funciones, structs, enums, traits, bloques impl, macro_rules
C#	`.cs`	Clases, interfaces, structs, enums, métodos, comentarios de documentación XML
Markdown / Texto	`.md`, `.txt`, `.rst`	Secciones mediante detección de encabezados
JSON	`.json`	Estructura de claves anidadas hasta profundidad 4, referencias cruzadas `$ref`
YAML	`.yaml`, `.yml`	Jerarquía de claves anidadas, marcadores de matriz, límite de profundidad 4
TOML	`.toml`	Tablas, pares clave-valor, estructura anidada
INI / Propiedades	`.ini`, `.cfg`, `.properties`	Secciones, pares clave-valor
Entorno	`.env`	Nombres de variables, valores (con enmascaramiento de secretos)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	Jerarquía de elementos, atributos
HCL / Terraform	`.hcl`, `.tf`	Bloques, recursos anidados, pares clave-valor
Conf	`.conf`	Pares clave-valor, estructura de bloques
Dockerfile	`Dockerfile`, `*.dockerfile`	Instrucciones, compilaciones multietapa, FROM/RUN/COPY/ENV
Todo lo demás	`*`	Recuento de líneas (reserva genérica)

51 herramientas

Navegación

Herramienta	Qué hace
`find_symbol`	Dónde se define un símbolo: archivo, línea, tipo, vista previa de 20 líneas
`get_function_source`	Fuente completa de una función o método
`get_class_source`	Fuente completa de una clase
`get_functions`	Todas las funciones en un archivo o proyecto
`get_classes`	Todas las clases con métodos y bases
`get_imports`	Todas las importaciones con módulo, nombres, línea
`get_structure_summary`	Resumen de la estructura del archivo o proyecto de un vistazo
`list_files`	Archivos indexados con filtro glob opcional
`get_project_summary`	Recuento de archivos, paquetes, clases/funciones principales
`search_codebase`	Búsqueda por expresión regular en todos los archivos indexados
`reindex`	Forzar reindexación completa (raramente necesaria)

Contexto y descubrimiento

Herramienta	Qué hace
`get_edit_context`	Todo en uno: fuente del símbolo + dependencias + llamadores en una sola llamada (ahorra 3 llamadas)
`get_feature_files`	Encuentra todos los archivos relacionados con una palabra clave de característica, luego rastrea las importaciones transitivamente
`get_routes`	Detecta rutas de API y páginas (Next.js App Router, Express, pages/api)
`get_components`	Detecta componentes de React (funciones que devuelven JSX) en archivos `.tsx`/`.jsx`
`get_env_usage`	Encuentra todas las referencias a una variable de entorno en toda la base de código

Análisis de impacto

Herramienta	Qué hace
`get_dependencies`	Qué llama/usa un símbolo
`get_dependents`	Qué llama/usa un símbolo
`get_change_impact`	Dependientes directos + transitivos en una sola llamada
`get_call_chain`	Ruta de dependencia más corta entre dos símbolos (BFS)
`get_file_dependencies`	Archivos importados por un archivo dado
`get_file_dependents`	Archivos que importan desde un archivo dado

Git y diffs

Herramienta	Qué hace
`get_git_status`	Rama, adelantado/atrasado, preparado, no preparado, no rastreado
`get_changed_symbols`	Archivos cambiados como resúmenes a nivel de símbolo, no diffs
`get_changed_symbols_since_ref`	Cambios a nivel de símbolo desde cualquier referencia de git
`summarize_patch_by_symbol`	Vista de revisión compacta: símbolos en lugar de diffs textuales
`build_commit_summary`	Resumen de commit compacto a partir de archivos cambiados

Edición segura

Herramienta	Qué hace
`replace_symbol_source`	Reemplaza la fuente de un símbolo sin tocar el resto del archivo
`insert_near_symbol`	Inserta contenido antes o después de un símbolo
`create_checkpoint`	Crea una instantánea de un conjunto de archivos antes de editar
`restore_checkpoint`	Restaura desde un punto de control
`compare_checkpoint_by_symbol`	Diff entre punto de control y actual a nivel de símbolo
`list_checkpoints`	Lista los puntos de control disponibles

Prueba y ejecución

Herramienta	Qué hace
`find_impacted_test_files`	Infiere archivos pytest probablemente afectados a partir de símbolos cambiados
`run_impacted_tests`	Ejecuta solo las pruebas afectadas: resumen compacto, no registros sin procesar
`apply_symbol_change_and_validate`	Edita + ejecuta pruebas afectadas en una sola llamada
`apply_symbol_change_validate_with_rollback`	Edita + valida + reversión automática en caso de fallo
`discover_project_actions`	Detecta comandos de prueba/lint/compilación/ejecución desde archivos del proyecto
`run_project_action`	Ejecuta una acción descubierta con salida limitada

Análisis de configuración

Herramienta	Qué hace
`analyze_config`	Escanea archivos de configuración en busca de duplicados, secretos, errores tipográficos y claves huérfanas

Ejecuta tres comprobaciones (activables individualmente mediante el parámetro checks):

Duplicados — Misma clave definida dos veces en el mismo archivo, además de detección de errores tipográficos basada en Levenshtein (ej. db_hsot vs db_host)
Secretos — Patrones de expresiones regulares para formatos de secretos conocidos (claves API, tokens, claves privadas) más análisis de entropía de Shannon para cadenas de alta entropía
Huérfanos — Referencias cruzadas de claves de configuración contra el uso real del código. Detecta claves que tu código nunca lee y variables de entorno que tu código espera pero que no están configuradas. Entiende os.environ, process.env, os.Getenv, std::env::var y más.

Formatos soportados: .yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

Calidad de código

Herramienta	Qué hace
`find_dead_code`	Encuentra funciones/clases con cero llamadores (excluye puntos de entrada, pruebas, rutas decoradas)
`find_hotspots`	Clasifica funciones por puntuación de complejidad (líneas, ramas, anidamiento, recuento de parámetros)
`detect_breaking_changes`	Compara firmas de funciones actuales contra una referencia de git: marca parámetros eliminados/renombrados, valores predeterminados cambiados

Docker

Herramienta	Qué hace
`analyze_docker`	Audita Dockerfiles: imágenes base, puertos expuestos, referencia cruzada ENV/ARG, advertencias de etiqueta `latest`

Multi-proyecto

Herramienta	Qué hace
`find_cross_project_deps`	Referencia cruzada de importaciones entre proyectos para encontrar dependencias compartidas

Estadísticas

Herramienta	Qué hace
`get_usage_stats`	Ahorro acumulado de tokens por proyecto a través de sesiones

vs LSP

LSP responde "¿dónde está definido esto?" — token-savior responde "¿qué se rompe si lo cambio?"

LSP son consultas puntuales: un símbolo, un archivo, una posición. Puede encontrar dónde está definido LLMClient y quién lo referencia directamente. Pregunta "¿qué se rompe transitivamente si refactorizo LLMClient?" y LSP no tiene nada: la IA tendría que encadenar docenas de llamadas de búsqueda de referencias de forma recursiva, leyendo archivos en cada paso.

get_change_impact("TestCase") en CPython encuentra 154 dependientes directos y 492 dependientes transitivos en 0.45ms, devolviendo 16K caracteres en lugar de leer 41M. Y a diferencia de LSP, no requiere servidores de lenguaje: un binario cubre Python + TS/JS + Go + Rust + C# + archivos de configuración + Dockerfiles de forma inmediata.

Instalación

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

Configuración

Claude Code / Cursor / Windsurf / Cline

Agrega a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

Agrega a ~/.hermes/config.yaml:

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT es opcional, pero permite que el panel en vivo atribuya los ahorros por cliente.

Haz que el agente realmente lo use

Los asistentes de IA usan grep y cat por defecto incluso cuando hay mejores herramientas disponibles. Las instrucciones suaves son racionalizadas. Agrega esto a tu CLAUDE.md o equivalente:

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

Espacios de trabajo multi-proyecto

Una instancia de servidor cubre cada proyecto en la máquina:

WORKSPACE_ROOTS=/root/myapp,/root/mybot,/root/docs token-savior

Cada raíz obtiene su propio índice aislado, cargado de forma perezosa en el primer uso. list_projects muestra todas las raíces registradas. switch_project establece la activa.

Cómo se mantiene sincronizado

El servidor verifica git diff y git status antes de cada consulta (~1-2ms). Los archivos cambiados se vuelven a analizar de forma incremental. No se requiere reindex manual después de ediciones, cambios de rama o pulls.

El índice se guarda en `.codebase-index-cache.json

token-savior