Imported from Yeferson-Valencia/MCP-tools (AGENTS.md). Install upstream with npx skills add Yeferson-Valencia/MCP-tools. Copyright stays with the author.

Reglas de proyecto para el agente (Copilot)

Este repo es un ** servidor MCP** (mcp-agent-tools) que expone 41 tools vía Streamable-HTTP en http://localhost:8000/mcp (verificar siempre con tools/list; el número cambia según qué módulos logren abrir su DB al arrancar). Cuando el usuario esté trabajando en este repo, prioriza usar las tools del propio MCP en vez de ejecutar comandos de shell/docker manualmente.

🎯 Directiva principal

Si una tarea puede hacerse con una tool del MCP (ejecutar, leer, escribir, buscar, razonar, web, memoria), usa la tool del MCP (prefijo mcp_mcp-agent-too_*) en vez de run_in_terminal. El usuario canceló explicitamente comandos de shell pidiendo "usa la tool directamente".

Memoria: para hechos persistentes del proyecto/usuario, guardar con memory_store y recuperar con memory_search antes de empezar tareas que tengan que ver con monitoreo, endpoints o decisiones previas. Ver la sección «Tres sistemas de memoria» para saber cuándo NO usarla (datos volátiles, búsquedas literales, secrets).

🧰 Tools disponibles (y cuándo usarlas)

Tool (MCP)	Uso típico
`mcp_mcp-agent-too_run_python`	Ejecutar Python con resultado estructurado (stdout, stderr, exit_code, duration). Para cálculos, scripts, pruebas de lógica. No usar `run_in_terminal` + `python3 ...`.
`mcp_mcp-agent-too_run_shell`	Ejecutar un comando en el sandbox del contenedor. Parámetro es `cmd`, no `command`. Para listar, grep, quick checks. Para docker/builds, sí usar `run_in_terminal`.
`mcp_mcp-agent-too_create_directory`	Crear directorios dentro de `/workspace`.
`mcp_mcp-agent-too_write_file`	Crear/overwritear archivos dentro de `/workspace`.
`mcp_mcp-agent-too_read_text_file`	Leer un archivo de texto (soporta `head`/`tail` por líneas).
`mcp_mcp-agent-too_read_multiple_files`	Leer varios archivos en un solo call.
`mcp_mcp-agent-too_edit_file`	Reemplazo preciso de texto con dry-run. Mejor que `replace_string_in_file` para varios edits.
`mcp_mcp-agent-too_move_file`	Mover/renombrar (equivale a `mv`).
`mcp_mcp-agent-too_get_file_info`	Metadata (size, type, mtime, mode).
`mcp_mcp-agent-too_list_directory`	Listar un directorio.
`mcp_mcp-agent-too_list_directory_with_sizes`	Listar con tamaños y total (equivale a `ls -la` + `du`).
`mcp_mcp-agent-too_directory_tree`	Árbol recursivo como JSON.
`mcp_mcp-agent-too_search_files`	Buscar por patrón glob (respetando allowed roots).
`mcp_mcp-agent-too_list_allowed_directories`	Ver roots permitidos (actualmente `/workspace`).
`mcp_mcp-agent-too_read_media_file`	Leer binarios (img/audio) como base64.
`mcp_mcp-agent-too_web_fetch`	Traer una URL y extraer texto (sin key).
`mcp_mcp-agent-too_fetch`	Versión equivalente con format/máx bytes/líneas.
`mcp_mcp-agent-too_web_search`	Buscar en la web. Requiere `TAVILY_API_KEY` o `BRAVE_API_KEY` — si no hay key, devolverá `isError` con el hint.
`mcp_mcp-agent-too_think`	Razonamiento multi-paso (n de pasos totales).
`mcp_mcp-agent-too_sequential_thinking`	Razonamiento secuencial, ramificable (branch_id, revises_thought).
`mcp_mcp-agent-too_docker_ps`	Listar contenedores (table). Con `all_containers=true` incluye parados.
`mcp_mcp-agent-too_docker_images`	Listar imágenes locales.
`mcp_mcp-agent-too_docker_logs`	Logs de un contenedor (tail, 0 = todos).
`mcp_mcp-agent-too_docker_exec`	`docker exec` en un contenedor en curso (workdir + command).
`mcp_mcp-agent-too_docker_build`	`docker build --tag <tag> <path>` (timeout largo, 900 s por defecto).
`mcp_mcp-agent-too_docker_pull`	`docker pull <image>`.
`mcp_mcp-agent-too_docker_compose_up`	`docker-compose -f <dir>/docker-compose.yml up -d [--build] [services...]`.
`mcp_mcp-agent-too_docker_compose_down`	`docker-compose ... down [--volumes]`.
`mcp_mcp-agent-too_docker_compose_logs`	Logs de un stack compose (service opcional, tail).
`mcp_mcp-agent-too_ocr_extract`	OCR de imágenes (RapidOCR, 100% CPU). `image` = ruta absoluta o data-URI base64. Opcionales: `min_confidence` (0-1, default 0.5), `output_format` (`text`/`lines`/`both`), `timeout` (s). Devuelve `text`, `lines` (con confidence + bbox), `duration_s`. 1ª llamada tarda extra (lazy init del motor).
`mcp_mcp-agent-too_memory_store`	Guardar un hecho/nota en memoria semántica vectorial persistente (SQLite + embeddings all-MiniLM). Parámetros: `text`, `tags` (comas). Devuelve `{id, status}`. 1ª llamada de la sesión tarda extra (carga del modelo de embeddings ~1-2 min).
`mcp_mcp-agent-too_memory_search`	Buscar por significado (embedding cosine) en la memoria vectorial. Parámetros: `query`, `k` (default 5). Devuelve top-k con `id`, `text`, `tags`, `score`.
`mcp_mcp-agent-too_memory_forget`	Borrar una memoria por `id` (el que devolvió `memory_store`). Devuelve `{status: deleted}`.
`mcp_mcp-agent-too_code_search`	Búsqueda semántica de código del workspace: `query` (en lenguaje natural), `k` (default 10). Devuelve chunks de ~40 líneas con `path`, líneas y score. Solo si el índice existe — si devuelve 0 resultados, correr `code_index` primero.
`mcp_mcp-agent-too_code_index`	Indexar el workspace en la BD RAG (chunks de 40 líneas + embeddings). Parámetros: `path` (subruta opcional), `force` (re-indexar todo sin cache por hash). Correr después de cambios en el código que se va a buscar. Tarda proporcional al # de archivos (1ª vez: minutos en repo grande).
`mcp_mcp-agent-too_memory_graph_entity`	Crear nodo en el grafo de conocimiento (entities): `name` (unique, case-insensitive), `entity_type` opcional (person/tech/place/concept). Idempotente (`ON CONFLICT`).
`mcp_mcp-agent-too_memory_graph_relation`	Añadir arista tipada: `from_entity`, `relation_type` (`uses`, `depends_on`, ...), `to_entity`, `fact` opcional (texto libre). Crea entidades ausentes automáticamente. Devuelve `stored`/`already_exists`.
`mcp_mcp-agent-too_memory_graph_query`	Consultar el grafo: filtra por `entity`, `relation_type`, `keyword` (LIKE sobre facts), `limit` (default 50). Exacto/estructurado, no semántico — a diferencia de `memory_search`.
`mcp_mcp-agent-too_memory_graph_list_entities`	Listar todos los nodos del grafo.
`mcp_mcp-agent-too_memory_graph_delete_relation`	Borrar arista por `from_entity`/`relation_type`/`to_entity` (+`fact` opcional).
`run_docker` (en `src/tools/exec.py`)	Ejecutar cualquier comando `docker ...` crudo (`cmd` debe empezar con `docker`). Úsalas para lo que no hay tool dedicada (`docker system prune`, `docker compose ps`, ...).

🧠 Tres sistemas de memoria: cuándo usar cuál

El server trae tres almacenes distintos (toda la BD vive en /app/db → db/ del host):

Sistema	Tool	BD	Naturaleza	Modelo
Memoria vectorial	`memory_store` / `memory_search` / `memory_forget`	`db/mcp.db` (tabla `memories` + FTS5)	Hechos/notas como texto libre + embedding cosine	`all-MiniLM-L6-v2` (lazy)
Grafo de conocimiento	`memory_graph_*`	`db/memory_graph.db`	Entidades (nodos) + relaciones tipadas (aristas)	Exacto (LIKE), sin embeddings
RAG de código	`code_index` / `code_search`	`db/mcp.db` (tabla `chunks`)	Chunks de 40 líneas de código del workspace + embedding	`all-MiniLM-L6-v2` (mismo que memoria)

✅ CUÁNDO SÍ usar

Case	Tool	Ejemplo
Recordar decisiones/contexto que debe sobrevivir a la sesión	`memory_store`	"EP clave del monitoreo es `/mille_buzon...`, endpoint en `10.72.186.33:10002`"
Recuperar por significado algo guardado antes (sin saber la frase exacta)	`memory_search`	buscar "monitoring del buzón" pese a que se guardó como "voice mailbox"
Borrar un dato desactualizado	`memory_forget(id)`	El endpoint cambió de IP
Modelar estructuras relacionales (quién usa qué, qué depende de qué)	`memory_graph_entity` + `memory_graph_relation`	`mcp-agent-tools --[depends_on]--> docker`, `millenium --[owns]--> repo-mcp`
Consultar relaciones exactas ("todo lo que depende de X")	`memory_graph_query(entity=...)`	Depuración de dependencias, auditoría
Buscar código por comportamiento/propósito en lenguaje natural	`code_search`	"qué función indexa el workspace" → devuelve el chunk de `rag.py`
Antes de `code_search` tras cambios en el workspace	`code_index`	Refactor acabó → reindexar (el hash evita re-embed lo que no cambió)

❌ CUÁNDO NO usar

Case	No uses	Usa en su lugar	Por qué
Buscar un string literal en código (nombres de funciones, imports, patrones exactos)	`code_search`	`search_files` / grep	El índice es semántico; para texto exacto es más lento y puede no estar indexado el archivo. Además los chunks son de 40 líneas, pierde el contexto del archivo completo.
Buscar código antes de indexar (BD de chunks vacía)	`code_search`	`code_index` primero	0 resultados ≠ código inexistente; puede ser índice vacío (necesita `all-MiniLM` + minutos).
Recordar algo volátil (estado in-progress, resultado de un build, token temporal)	`memory_store`	Estado de la conversación / notes de sesión	La memoria MCP es persistente y semántica: el ruido la contamina (los search top-k empiezan a devolver basura) y no tiene scoping de sesión.
Relación puntual que no forma parte de un modelo	`memory_graph_*`	`memory_store` con tags	Crear 2 entidades + 1 arista para un hecho suelto es overhead; el grafo brilla cuando se cruzan relaciones (query por entidad, por tipo).
Guardar secrets/credenciales	Cualquier `memory_*`	Variables de entorno / Key Vault	La BD está en un bind mount legible desde el host; no es cifrada.
Buscar archivo por nombre/patrón glob	`code_search`	`search_files`	RAG indexea contenido, no nombres de archivo (aunque devuelve el `path`).
Consultar código que no está bajo `/workspace` (p.ej. `src/` de este repo)	`code_index` / `code_search`	`read_text_file` / grep local	El workspace indexable es `/workspace`, no el repo del servidor.
Razonamiento largo de varias ramas	`sequential_thinking` a lo bruto en la BD	Solo usarlo para planear en turno	Es stateless entre llamadas; no es un almacén.

🧭 Regla práctica de decisión

¿Es un hecho persistente del proyecto/usuario? → memory_store (con tags) y memory_search para recuperar.
¿Es una relación estructural que vas a consultar por entidad o tipo? → grafo (memory_graph_*).
¿Es código que se va a buscar por comportamiento? → code_index (si cambió) + code_search. ¿Text exacto o nombre? → search_files.
¿Es volátil (esta tarea, este build)? → NO guardarlo en la memoria MCP.

⚠️ Límites y gotchas conocidos

Allowed roots: todas las tools de filesystem solo operan bajo /workspace. Si intentas usar /tmp/... te dirá path not allowed: resolved to ... which is outside the allowed roots.

run_shell toma cmd, no command. IMPORTANTE: cuando corre en el contenedor del MCP, run_shell está dentro del contenedor (no tiene acceso al host); usa las tools docker_* o run_docker para operaciones de docker.

web_search sin API key → isError con mensaje explícito (no es un bug del server).
web_fetch devuelve status 200 con cuerpo vacío en páginas casi vacías (parsing de readability).
run_python sandbox está en /tmp/mcp_sandbox dentro del contenedor — no tocar desde el host.
MCP_DB_PATH: el Dockerfile la fija a /app/mcp.db (no escribible: /app es de appuser uid 999, contenedor corre 1000:984). docker-compose.yml la sobrescribe a /app/db/mcp.db; sin ese override, memory y rag no se registran (fallan en el sqlite3.connect al arrancar). Igual pasa con MCP_MEMORY_GRAPH_DB=/app/db/memory_graph.db. Si añades otra tool con BD, ponla en /app/db.
1ª llamada a memory_search/code_search/memory_store en un contenedor recién arrancado tarda 1-2 min (carga lazy del modelo all-MiniLM-L6-v2). No confundir con hang: el HTTP sigue vivo, solo la respuesta tarda.
code_index hace hash MD5 por archivo: si el código no cambió, lo skipes (rápido). force=true re-embedda todo (lento).
Logs de auditoría en db/tools.log (host) = /app/db/tools.log (contenedor). Cada tool call queda registrado con → call y ✓ ok / × error + duración. Útil para verificar que una tool se invocó correctamente.

📂 Paths relevantes

src/server.py — app FastAPI + hook de logging en mcp._tool_manager.call_tool.
src/tools/__init__.py — registro de los 13 módulos (TOOLS list). Fallos aquí = tool ausiente; revisar docker logs.
src/tools/exec.py — run_python / run_shell con sandbox.
src/tools/memory.py — memoria vectorial (memory_store/search/forget) → db/mcp.db.
src/tools/rag.py — RAG de código (code_index/code_search, chunks de 40 líneas) → db/mcp.db (tabla chunks).
src/tools/memory_graph.py — grafo de conocimiento (memory_graph_*) → db/memory_graph.db.
db/mcp.db — SQLite compartida por memoria vectorial + RAG de código y admin (misma DB, tablas distintas).
db/memory_graph.db — BD del grafo (separada a propósito; override MCP_MEMORY_GRAPH_DB).
db/tools.json — DB de herramientas disponibles (runtime).
db/tools.log — log de auditoría.
workspace/ — mounted como /workspace en el contenedor.
docker-compose.yml / Dockerfile — stack.

⚠️ Nota: la BD del repo (módulos src/) NO está indexada en code_search porque code_index solo recorre /workspace. Para buscar en la fuente del propio servidor, usar grep/read_text_file sobre el host.

🐳 Docker desde el MCP

El contenedor del MCP monta /var/run/docker.sock (rw) y trae docker-cli + docker-compose (Debian v1) instalados → el MCP puede gestionar los contenedores del host. El gid 984 es el grupo docker del host, por eso funciona sin sudo.

⚠️ Quien tiene el socket tiene el host (docker.sock = root). Solo montar en redes/confianza reales; nunca en máquinas compartidas.

🔄 Regla de rebuild

Cambios en src/ o Dockerfile → docker compose up -d --build. No hacer docker exec + pip install a mano: el contenedor queda en desincronía con el código del repo.

MCP-tools

About