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

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

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:

%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

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

Análisis estático opcional:

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.