agent-context-mcp

Постоянная память проекта для ИИ-агентов, пишущих код, не зависящая от харнесса.

MCP-сервер без состояния, который даёт любому агенту — Claude Code, Codex, Kilo Code, OpenCode, Cursor — структурированный доступ на чтение и запись к папке ai_context/ с обычным markdown, отдельной для каждого проекта. Решения, планы, ограничения и заметки живут в репозитории, синхронизируются через git и остаются читаемыми для агентов, у которых сервер не установлен.

Агент решает, когда и что записывать. Сервер решает, формат и расположение. Суть именно в этой намеренной определённости: дайте агенту свободу записи — и папка превратится в свалку.

Чем это не является

Никакого извлечения кода, семантического поиска, эмбеддингов, базы данных, состояния демона. Чистый файловый ввод-вывод. Он сочетается с инструментом поиска по коду, а не конкурирует с ним.

Related MCP server: Jarvis Markdown MCP

Установка

Требуется Node ≥ 18. Глобально устанавливать ничего не нужно — каждый из харнессов ниже запускает его через npx.

npx agent-context-mcp init

init создаёт каркас ai_context/, заготовки project.md и constraints.md, добавляет сниппет активации в AGENTS.md и выводит блок регистрации для вашего харнесса. Он никогда не перезаписывает существующий файл.

Регистрация в вашем харнессе

Claude Code, из корня проекта:

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

Или закоммитьте .mcp.json, чтобы он был у всей команды:

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

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

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

Kilo Code, OpenCode, Cursor, Windsurf и другие MCP-клиенты используют тот же JSON-блок mcpServers в своём файле настроек.

Завершающая . заставляет сервер считать рабочую директорию харнесса корнем проекта. Если ваш харнесс запускается из другого места, передайте вместо неё абсолютный путь. Транспорт — только stdio.

Сниппет AGENTS.md

init добавляет его сам; если вы предпочитаете не запускать init, добавьте его вручную. Именно он заставляет агентов пользоваться инструментами:

## 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.

Папка

<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/ создаётся лениво — при первой записи, либо заранее, командой init.

• INDEX.md пересоздаётся после каждой записи и каждый раз заново сканируется с диска. Никогда не редактируйте его вручную.

• Решения — только добавление (append-only). Чтобы заменить одно из них, нужно записать новое, ссылающееся на него; единственная правка, которая когда-либо вносится в существующий ADR, — это строка метаданных - Superseded-by: NNNN.

• Планы — изменяемые — update_plan перезаписывает их.

• project.md и constraints.md — человеческий источник истины. Сервер читает их и никогда не пишет в них.

Инструменты

Ограничения длины — это намеренная дисциплина против захламления, а не лимиты хранилища: заголовок — 80 символов, разделы ADR — по 1200, заметки — 500, планы — 8000. При превышении лимита возвращается сообщение, в котором указаны фактическая длина и лимит, чтобы агент мог сократить текст и повторить попытку.

Инструмента search_context нет. Grep по небольшой папке с markdown вполне достаточно, и он у агентов уже есть.

Безопасность

• Каждый путь проходит через единый защитный механизм; ничего за пределами ai_context/ никогда не читается и не записывается, а попытка обхода каталогов (traversal) через slug или topic отклоняется, а не молча подменяется чем-то другим.

• Запись выполняется во временный файл, который затем переименовывается в целевой, поэтому сбой не может оставить наполовину записанный файл.

• Никакого состояния между вызовами, никаких кешей. Изменения, сделанные человеком, git pull или другим агентом, подхватываются при следующем вызове.

Разработка

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

Лицензия

MIT