agent-context-mcp

Memoria de proyecto persistente e independiente del entorno para agentes de codificación de IA.

Un servidor MCP sin estado que da a cualquier agente — Claude Code, Codex, Kilo Code, OpenCode, Cursor — acceso estructurado de lectura/escritura a una carpeta ai_context/ de markdown plano en cada proyecto. Las decisiones, los planes, las restricciones y las notas viven en el repositorio, se sincronizan con git y siguen siendo legibles para agentes que no tienen el servidor instalado.

El agente decide cuándo y qué registrar. El servidor decide el formato y la ubicación. Ese posicionamiento deliberado es el punto: dale a un agente espacio para escribir en formato libre y la carpeta se acaba convirtiendo en un vertedero.

Lo que no es

No recuperación de código, no búsqueda semántica, no embeddings, no base de datos, no estado de demonio. E/S de archivos pura. Se complementa con una herramienta de búsqueda de código en lugar de competir con ella.

Related MCP server: Jarvis Markdown MCP

Instalación

Necesita Node ≥ 18. No hay que instalar nada globalmente — todos los entornos siguientes lo ejecutan a través de npx.

npx agent-context-mcp init

init crea el esqueleto de ai_context/, crea los archivos iniciales project.md y constraints.md, añade el fragmento de activación a AGENTS.md e imprime el bloque de registro para tu entorno. Nunca sobrescribe un archivo existente.

Registro con tu entorno

Claude Code, desde la raíz del proyecto:

claude mcp add agent-context -- npx -y agent-context-mcp .

O haz commit de un .mcp.json para que todo el equipo lo tenga:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "agent-context-mcp", "."]
    }
  }
}

Codex, en ~/.codex/config.toml:

[mcp_servers.agent-context]
command = "npx"
args = ["-y", "agent-context-mcp", "."]

Kilo Code, OpenCode, Cursor, Windsurf y otros clientes MCP usan el mismo bloque JSON mcpServers en su propio archivo de configuración.

El . final hace que el servidor trate el directorio de trabajo del entorno como la raíz del proyecto. Pasa una ruta absoluta si tu entorno arranca desde otro sitio. El transporte es solo stdio.

Fragmento de AGENTS.md

init añade esto; puedes añadirlo a mano si prefieres no ejecutar init. Es lo que en realidad hace que los agentes usen las herramientas:

## Persistent project context

This project uses the agent-context MCP server. At session start, call
`get_context` (no arguments) to orient yourself. When you make or the user
confirms a significant architectural/technical decision, call
`record_decision`. Persist gotchas and conventions with `record_note`.
Human-curated ground truth lives in ai_context/project.md and
ai_context/constraints.md — read them, never contradict them.

La carpeta

<project-root>/
  AGENTS.md                 entry point — yours, never written except by `init`
  ai_context/
    INDEX.md                auto-maintained table of contents (server-owned)
    project.md              what this project is (yours; server reads, never writes)
    constraints.md          hard rules and good practices (yours; read-only to the server)
    memory.md               notes, written via record_note
    decisions/
      0001-use-postgres.md  ADRs, written via record_decision
    plans/
      auth-refactor.md      mutable plans, written via update_plan

• ai_context/ se crea de forma diferida en la primera escritura, o directamente con init.

• INDEX.md se regenera después de cada escritura y se vuelve a escanear del disco en cada momento. Nunca lo edites a mano.

• Las decisiones son solo añadir. Sustituir una consiste en registrar una nueva que la referencia; la única edición que se hace a un ADR existente es una línea de metadatos - Superseded-by: NNNN.

• Los planes son mutables — update_plan los sobrescribe.

• project.md y constraints.md son la fuente de verdad humana. El servidor los lee y nunca los escribe.

Herramientas

Los límites de longitud son una disciplina deliberada contra la basura, no límites de almacenamiento: sistema iterador, título 80 caracteres, secciones de ADR 1200 cada una, notas 500, planes 8000. Superar uno devuelve un mensaje con la longitud real y el límite para que el agente pueda resumir y reintentar.

No existe search_context. Grep en una carpeta pequeña de markdown es suficiente, y los agentes ya lo tienen.

Seguridad

• Cada ruta se resuelve mediante un único guardián; nunca se lee ni escribe nada fuera de ai_context/, y la travesía en un slug o topic se rechaza en lugar de sanearse silenciosamente en otra cosa.

• Las escrituras van a un archivo temporal y se renombran a su emplazamiento final, de modo que un fallo no puede dejar un archivo a medias.

• No hay estado entre llamadas, no hay cachés. Los cambios de un humano, de un git pull o de otro agente se recogen en la siguiente llamada.

Desarrollo

npm install
npm test          # unit + stdio integration tests
npm run typecheck # sources and tests
npm run build

Licencia

MIT