Faro
by MC-Sinclair
README.md
# Faro
> Servidor MCP de **documentación viva**: le da al asistente de IA una ventana para
> leer la documentación real y vigente de una librería en el momento, en vez de citarla
> de memoria desde su fecha de corte.
*(Un faro no navega por ti: te deja ver dónde está la costa en la niebla. Este servidor
no reentrena al modelo: le da luz sobre la documentación real para que no navegue de
memoria.)*
---
## El problema que resuelve
Un modelo de lenguaje tiene una **fecha de corte**. Todo lo que "sabe" de SQLAlchemy o
FastAPI es una foto congelada, mezclada de miles de ejemplos de versiones distintas. El
peligro no es solo estar desactualizado: el modelo **no distingue con fiabilidad qué
recuerda bien y qué está rellenando**. Puede darte la API de una versión vieja con la
misma seguridad que la actual.
Faro no reentrena ni "actualiza" al modelo; eso es imposible desde fuera. Le da una
**herramienta** para consultar la documentación real cuando la respuesta lo necesita. La
diferencia es la que hay entre citar un libro de memoria y tenerlo abierto en la mano.
## Así responde
**Detecta API obsoleta** que el modelo daría por buena:
```text
sqlalchemy 2.0.36 :: sqlalchemy.orm.Query.get
definido en: sqlalchemy 2.0.36
⚠ DEPRECADO desde 2.0 — usar Session.get
get(ident: '_PKIdentityArgument') -> 'Optional[Any]'
Return an instance based on the given primary key identifier,
or ``None`` if not found.
...
```
**Se niega a servir la versión equivocada.** Si el asistente da por hecho que usas la 1.4
y tienes instalada la 2.0.36:
```text
NO ENCONTRADO. Pediste 'sqlalchemy' 1.4, pero el entorno tiene 2.0.36. No sirvo doc de una versión que no es la tuya.
```
**Verifica afirmaciones** sobre la API, vengan de donde vengan:
```text
Query.get: existe (sqlalchemy.orm.Query.get) — ⚠ DEPRECADO desde 2.0, usar Session.get — get(ident: '_PKIdentityArgument') -> 'Optional[Any]'
URL.create: existe (sqlalchemy.engine.URL.create) — create(drivername: 'str', username: 'Optional[str]' = None, ...) -> 'URL'
Session.query_magic: NO EXISTE en esta versión.
```
## Principio rector: verificabilidad, no confianza ciega
> Un MCP de documentación no vuelve infalible al asistente. Le da algo a lo que agarrarse.
Un buen servidor cita la versión y el origen, para que el humano pueda verificar. Uno malo
—o uno que trae la documentación de otra versión— hace que el asistente **se equivoque con
más confianza todavía**. Por eso Faro:
1. **Exige la versión siempre.** Nunca devuelve "la última" de forma implícita. La versión
que pides se trata como una *afirmación* y se contrasta con la que hay instalada.
2. **Cita la fuente en cada respuesta**: la versión exacta del paquete que se leyó.
3. **Falla con honestidad.** Si no tiene la versión pedida, dice "no la tengo"; nunca la
sustituye en silencio por otra. Un "no encontrado" honesto vale más que un fragmento
plausible de otra versión.
## Cómo funciona
Faro lee los docstrings del **paquete realmente instalado en el entorno de tu proyecto**.
No busca en la web y no tiene caché: el paquete instalado es la fuente de verdad. Eso da
la versión exacta (`2.0.36`, no "2.0"), los avisos de obsolescencia que la propia librería
declara con `.. deprecated::` y la firma real de cada función.
Funciona con **cualquier librería de Python instalada**. SQLAlchemy tiene una lista curada
de módulos (para no traer ruido de dialectos internos o utilidades de testing); cualquier
otra librería descubre sus submódulos automáticamente.
### Arquitectura
```
Claude Code ──MCP (stdio)──► servidor.py ──► núcleo: resolver · dominio · parseo · catalogo
│
▼ puerto FuenteDeDocs
FuenteLocal ──subproceso──► extractor.py
(en el venv de tu proyecto)
```
- **El núcleo no importa `subprocess`, `httpx` ni `mcp`** (*Dependency Rule*). Habla con un
puerto, `FuenteDeDocs`, y por eso se testea entero sin red ni subprocesos.
- **El extractor corre en un subproceso** con el intérprete de tu proyecto y solo usa la
librería estándar. Importar un paquete ejecuta su código, y eso no debe pasar dentro
del proceso de Faro.
## Instalación y uso
Requisitos: Python 3.12+ y [`uv`](https://docs.astral.sh/uv/).
```bash
git clone https://github.com/MC-Sinclair/faro.git
cd faro
uv sync
```
El repo incluye un `.mcp.json`, así que Claude Code detecta el servidor al abrir esta
carpeta. Para usarlo desde otro proyecto, añade una entrada equivalente en el `.mcp.json`
de ese proyecto, con `--directory` apuntando a donde clonaste Faro.
Indica a Faro qué entorno debe leer con `FARO_PYTHON`:
```bash
# Windows
set FARO_PYTHON=C:\ruta\a\tu-proyecto\.venv\Scripts\python.exe
# macOS / Linux
export FARO_PYTHON=/ruta/a/tu-proyecto/.venv/bin/python
```
Si no la configuras, Faro lee su propio entorno y **te avisa en cada respuesta**.
### Herramientas
- `listar_versiones(libreria)`: qué versión hay instalada de verdad.
- `buscar_doc(libreria, version, consulta)`: documentación y firma de un símbolo.
`version` es obligatoria y **se verifica**: si indicas una versión que no es la
instalada, Faro te lo dice y no devuelve nada.
- `verificar_simbolos(libreria, version, simbolos)`: contrasta afirmaciones sobre la API
(incluidas las de la memoria del modelo) con el paquete instalado.
## Tests
```bash
uv run pytest -m "not contrato" # 99 tests: núcleo, sin red ni SQLAlchemy
uv run pytest -m contrato # 13 tests contra SQLAlchemy 2.0.36 real
```
Los tests del núcleo usan `FuenteFake`, con datos reales de SQLAlchemy 2.0.36 congelados
como fixtures. Los de contrato lanzan el extractor de verdad, e incluyen pasar Faro por
encima de su propio código.
## Cómo se construyó
Faro nació de un error real. Durante el diseño se afirmó **de memoria y con total
seguridad** que `Query.get` no existía en SQLAlchemy 2.0. Al comprobarlo contra el paquete
instalado, sí existe: está marcado como obsoleto. Es justo el fallo que Faro quiere
evitar, cometido mientras se diseñaba. Ese caso es hoy el test de contrato central del
proyecto.
El proceso:
- **Diseño antes que código.** Una fase de *brainstorming* cerró las decisiones clave:
construir en vez de usar un MCP de terceros, Python en lugar de TypeScript, y el paquete
instalado en lugar de la web como fuente. Cada decisión está razonada y documentada.
- **Spec y plan escritos** para la v1 y para cada mejora posterior, en
[`docs/superpowers/`](docs/superpowers/).
- **TDD tarea a tarea**: la v1 se construyó en 11 tareas, cada una con sus tests primero y
su commit.
- **Dogfooding.** Usar Faro contra sí mismo y contra casos reales destapó varios defectos
que los tests no veían, casi todos de la misma familia: Faro afirmaba algo falso con
seguridad en lugar de mostrar el dato real que tenía. Por ejemplo, métodos heredados o
`classmethod` que daban "no existe", o una obsolescencia que se perdía en las respuestas
ambiguas. Cada uno se corrigió con su spec y sus tests.
- **Desarrollo asistido por IA** con [Claude Code](https://claude.com/claude-code) como
pareja de programación. Yo dirijo el problema, las decisiones de diseño y la revisión;
el asistente ejecuta sobre un plan aprobado, y cada cambio pasa por tests y revisión
antes de entrar. El `CLAUDE.md` del repo es el contexto que le doy: arquitectura,
reglas y el porqué de cada decisión.
- **Commits pequeños** con formato *Conventional Commits* (`feat:`, `fix:`, `docs:`...).
## Límites conocidos
- Solo referencia de API. **No busca en tutoriales ni guías de migración.**
- Solo conoce versiones **instaladas**. No se inventa las que no están.
- Solo paquetes de Python.
- Solo avisa de obsolescencia si la librería la **declara** con `.. deprecated::`.
- No infiere tipos. Es una decisión consciente: sería otro sitio donde Faro podría
deducir mal y afirmar algo falso con seguridad.
## Licencia
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues