# Tachikoma Game Design MCP

Servidor MCP local y de solo lectura para que Claude consulte una biblioteca Chroma sobre narrativa y diseño de videojuegos. Este repositorio contiene únicamente el runtime público; la extracción, los chunks y la generación de embeddings viven en `tachikoma-rag-infra`.

## Características

- Búsqueda semántica multilingüe con `BAAI/bge-m3`.
- Resultados con libro, página, texto y similitud.
- Transporte MCP por `stdio`, sin puertos abiertos.
- Funcionamiento offline con un modelo previamente descargado.
- Herramientas de solo lectura y protección frente a instrucciones embebidas.
- Ruta del índice configurable, sin acoplamiento a la infraestructura.

## Contenido

```text
mcp_server.py                         Servidor MCP.
claude_desktop_config.example.json    Configuración de Claude Desktop.
requirements.txt                      Dependencias de ejecución.
pyrightconfig.json                    Configuración del análisis estático.
tests/test_mcp_server.py               Pruebas del runtime.
```

Los PDF, textos, chunks, embeddings y bases Chroma no forman parte de este repositorio público.

## Instalación

```powershell
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

## Proporcionar un índice

Tachikoma necesita una colección Chroma creada con el mismo modelo de embeddings. Puedes generarla mediante el repositorio privado `tachikoma-rag-infra` o recibirla por un canal autorizado.

Variables disponibles:

| Variable | Valor predeterminado |
| --- | --- |
| `TACHIKOMA_DATABASE_PATH` | `./chroma_page_aware` |
| `TACHIKOMA_COLLECTION` | `narrative_books_bge_m3` |
| `TACHIKOMA_MODEL` | `BAAI/bge-m3` |
| `TACHIKOMA_LOG_PATH` | `./logs/tachikoma-mcp.log` |

El modelo debe estar descargado en la caché local antes de iniciar el MCP. El servidor usa `local_files_only=True` y no descargará archivos durante una conversación.

El log es rotativo, no guarda el texto de las consultas y registra tiempos de carga del modelo, conexión a Chroma, embedding, búsqueda vectorial y ejecución total.

## Configurar Claude Desktop

1. Copia la entrada de `claude_desktop_config.example.json` dentro de `mcpServers`.
2. Sustituye las rutas del repositorio, Python y Chroma.
3. Cierra completamente Claude Desktop y vuelve a abrirlo.

En Windows, la configuración suele estar en:

```text
%APPDATA%\Claude\claude_desktop_config.json
```

## Herramientas

- `search_narrative_library`: búsqueda semántica con filtro opcional por libro.
- `read_book_page`: recupera en orden los chunks de una página.
- `list_library_books`: enumera los libros indexados.
- `library_status`: comprueba modelo, colección y número de chunks.

## Pruebas

```powershell
python -m unittest discover -s tests -p "test_*.py"
```

Análisis estático opcional:

```powershell
uv tool install basedpyright
basedpyright --pythonpath ".venv\Scripts\python.exe" -p pyrightconfig.json
```

## Privacidad

El índice puede contener fragmentos de documentos. No publiques Chroma ni distribuyas índices creados a partir de material con copyright sin autorización.