# starc-mcp

Servidor **MCP** para leer y escribir proyectos de **Story Architect (STARC)**
desde cualquier agente LLM (Claude Code, Codex, Gemini/agy, Cursor, Hermes…).
El agente pide — `listar proyectos`, `leer el guion`, `escribir la escena 3`,
`estadísticas`, `fichas de personajes` — y el servidor hace el trabajo sobre tu
archivo `.starc`, sin que el agente conozca el formato interno.

> ⚠️ **No afiliado a Story Apps.** Proyecto independiente; STARC es marca de sus
> autores. Funciona sobre el formato de archivo `.starc` (SQLite + XML).

## Regla dura (por diseño)

**Este servidor NUNCA modifica la aplicación STARC.** Trabaja únicamente sobre
archivos de proyecto `.starc`. La app puede actualizarse con normalidad sin
conflicto. Probado contra **STARC 0.8.2 (macOS)**.

## Seguridad

- **Escrituras con doble confirmación**: `preview=true` informa sin tocar nada;
  escribir exige `preview=false, confirmar=true`.
- **Escritura atómica**: copia temporal → `PRAGMA integrity_check` → re-chequeo
  de lock → `os.replace`. Backup automático con microsegundos antes de cada escritura.
- **Nunca escribe con el proyecto abierto** (detecta `.lock` de STARC).
- **Sin herramientas de borrado**. Restaurar = `restaurar_snapshot` (con backup
  previo del estado actual).
- **Allowlist de rutas**: solo `.starc` dentro del directorio configurado;
  `/Applications`, `.app` y `.framework` prohibidos explícitamente.
- Logs a **stderr** (el stdio MCP se mantiene limpio).

## Herramientas

| Tool | Modo | Qué hace |
|---|---|---|
| `listar_proyectos` | lectura | `.starc` disponibles |
| `info_proyecto` | lectura | documentos y escenas |
| `leer_guion` | lectura | guion/serie a markdown, fountain o json |
| `estadisticas` | lectura | escenas, palabras, páginas, personajes, localizaciones |
| `escribir_guion` | escritura* | reemplaza el guion (fountain o json) |
| `editar_escena` | escritura* | reemplaza UNA escena por número |
| `snapshot` / `listar_snapshots` / `restaurar_snapshot` | escritura* | backups con fecha y restauración |
| `poblar_*` (personajes/localizaciones desde el guion) | escritura* | genera fichas automáticamente |

\* siempre con confirmación, backup y verificación post-escritura.

## Instalación

```bash
git clone https://github.com/Christianrhf/starc-mcp.git
cd starc-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```

Config: `STARC_PROJECTS_DIR` apunta a tu carpeta de proyectos
(por defecto `~/Documents/starc/projects`).

### Conectar un agente (ej. Claude Code)

```bash
claude mcp add --transport stdio starc \
  -- .venv/bin/python -m starc_mcp.server
```

Codex: `codex mcp add starc -- .venv/bin/python -m starc_mcp.server`
Gemini/agy y Cursor aceptan MCP por stdio con el mismo comando.

### Remoto (VPS → Mac)

El transporte MCP es stdio, no viaja por SSH solo; se enruta con pipes:

```bash
ssh usuario@mac "cd ~/starc-mcp && .venv/bin/python -m starc_mcp.server"
```

## Uso con un agente (ejemplo)

> "Lista mis proyectos. Sobre *El Inquilino*, dame las estadísticas y qué
> personajes hablan en la escena 12. Luego reescribe esa escena con más tensión
> (preview primero, y confirma antes de escribir)."

## Compatibilidad tras actualizaciones de STARC

Si STARC cambia el formato interno, el servidor fallará de forma segura
(no corrompe nada) y el test [`tests/`](tests/) alerta:
`escribir → leer → contar escenas → integrity_check` debe quedar verde.

## Fixtures

Los fixtures de `tests/fixtures/` son **sintéticos** (nunca guiones reales).
Los backups `.bak-*` están en `.gitignore`.

## Estado & roadmap

- ✅ guion y serie (texto), sinopsis/tratamiento/título (lectura), estadísticas,
  personajes/localizaciones (escribir + poblar), portada (mecanismo), backups.
- 🧪 validación visual de módulos pendiente: STARC 0.8.2 no expone los módulos
  de investigación (personajes/localizaciones/mundos) en su barra lateral;
  los datos cargan y se aceptan sin reparación.
- ⏳ fdx/PDF, diccionarios (10105), mapa mental (100003), paginación fina.