atlas-introspect-mcp

Un servidor MCP que permite que ATLAS se observe — y se edite — a sí mismo:

Por qué pasa por la API HTTP

El historial de chat, los espacios de trabajo y los prompts residen todos en un único archivo DuckDB (data/chat_history.db). DuckDB es de un solo escritor y el proceso de ATLAS mantiene ese bloqueo de escritura durante toda su vida útil; un segundo proceso que abra el archivo, incluso en modo solo lectura, falla con un conflicto de bloqueo. Así que este servidor le pregunta a ATLAS a través de HTTP en bucle local. Eso también significa que el alcance por usuario lo aplica ATLAS, no se reimplementa aquí.

Solo se tocan directamente mcp.json y prompts/*.md; ATLAS no tiene API para ninguno de los dos.

Ser un proceso separado es lo que hace seguro llamar de vuelta a ATLAS: ATLAS espera la respuesta stdio de este servidor mientras su propio bucle de eventos queda libre para atender la solicitud. Una herramienta en el mismo proceso que hiciera lo mismo provocaría un interbloqueo.

Related MCP server: Atlas MCP Server

Identidad

Cada consulta se limita a un usuario, enviada como X-User-Email. Con DEBUG_MODE=true, ATLAS respeta esa cabecera; con ella desactivada, la cabecera es la que habría proporcionado el proxy de autenticación, así que la misma bandera funciona en ambos casos. El valor predeterminado es test@test.com — el usuario de prueba al que ATLAS recurre en modo depuración y, por tanto, el propietario de las conversaciones creadas a través de la interfaz en este host.

Instalación

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

Comprobación independiente (con ATLAS en ejecución):

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

Registro con ATLAS

Añade a tu config/mcp.json de ATLAS (rutas absolutas — el comando se busca en el PATH del gestor de servicios, no en el de tu shell) y luego reinicia ATLAS:

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

Añade "--read-only" al comando para una versión solo de visualización; cada herramienta de mutación se negará en lugar de escribir.

Puertos: stdio no necesita ninguno. --transport http usa por defecto el 8101. Rechaza el puerto 8080 directamente — en un host con k3s, klipper-lb hace DNAT de 8080 a Traefik incluso en 127.0.0.1, así que un servidor enlazado allí no recibe nada y cada solicitud vuelve como un 500 vacío sin ninguna línea en tu registro.

Configuración

Cada bandera tiene un equivalente en variable de entorno.

Herramientas

Conversaciones (solo lectura) — list_conversations, search_conversations, get_conversation, list_conversation_tags

config/mcp.json — get_mcp_config, upsert_mcp_server, delete_mcp_server, replace_mcp_config

Espacios de trabajo — list_workspaces, create_workspace, update_workspace, delete_workspace

Prompts personalizados — list_custom_prompts, get_custom_prompt, create_custom_prompt, update_custom_prompt, delete_custom_prompt

Archivos de prompts en disco — list_prompt_files, read_prompt_file, write_prompt_file

Salud — atlas_status

Cosas que te morderán

• Las ediciones de mcp.json no son en vivo. ATLAS lanza los servidores stdio al arrancar. Cada herramienta de escritura lo indica en su resultado; aplica con systemctl --user restart atlas o ./redeploy.sh --no-pull.

• Editar tu propia entrada funciona, pero solo tiene efecto al reiniciar — momento en el que una entrada rota significa que este servidor ha desaparecido y no puedes arreglarlo desde dentro de ATLAS. Las copias de seguridad se guardan junto al archivo como mcp.json.bak-<stamp>.

• upsert_mcp_server reemplaza una entrada por completo, no la fusiona. Léela primero, cámbiala y envía el objeto completo de vuelta. Lo mismo para el config de un espacio de trabajo y el content de un prompt.

• Las herramientas de conversación son de solo lectura por diseño. Hay endpoints de eliminación en ATLAS; deliberadamente no se exponen aquí.

• write_prompt_file cambia todos los chats de la instancia. Hace una copia de seguridad primero y, como mcp.json, se aplica en el próximo reinicio.

Pruebas

.venv/bin/pytest

Cubren la lógica de edición y validación de archivos (escritura atómica, copia de seguridad, rechazo de recorrido, advertencias de lint, modo solo lectura) contra un directorio temporal — no se necesita ATLAS en ejecución.