agent-context-mcp

AI 코딩 에이전트를 위한 영구적이고 하네스에 구애받지 않는 프로젝트 메모리.

상태를 저장하지 않는 MCP 서버로, 모든 에이전트(Claude Code, Kilo Code, OpenCode, Cursor)에 프로젝트별 ai_context/ 폴더의 일반 마크다운에 대한 구조화된 읽기/쓰기 접근을 제공합니다. 결정 사항, 계획, 제약 조건 및 메모는 저장소에 저장되고, git을 통해 동기화되며, 서버가 설치되지 않은 에이전트도 읽을 수 있습니다.

에이전트는 언제, 무엇을 기록할지 결정합니다. 서버는 형식과 위치를 결정합니다. 이러한 의견 제시가 핵심입니다: 에이전트에게 자유 형식 쓰기를 허용하면 폴더는 쓰레기로 변질됩니다.

##它不是

코드 검색, 의미론적 검색, 임베딩, 데이터베이스, 데몬 상태가 없습니다. 순수 파일 I/O입니다. 코드 검색 도구와 경쟁하지 않고 함께 구성됩니다.

설치

Node.js 18 이상이 필요합니다. 전역 설치가 필요 없습니다 — 모든 하네스는 npx를 통해 실행합니다.

npx agent-context-mcp init

init은 ai_context/ 스켈레톤을 생성하고, project.md와 constraints.md를 스텁으로 만들며, AGENTS.md에 활성화 스니펫을 추가하고, 하네스용 등록 블록을 출력합니다. 기존 파일을 덮어쓰지 않습니다.

Related MCP server: Jarvis Markdown MCP

하네스에 등록

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 클라이언트는 자체 설정 파일에서 동일한 mcpServers JSON 블록을 사용합니다.

마지막 .은 서버가 하네스의 작업 디렉터리를 프로젝트 루트로 처리하게 합니다. 하네스가 다른 위치에서 시작하는 경우 대신 절대 경로를 전달하세요. 전송은 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는 모든 쓰기 후에 재생성되고 매번 디스크에서 다시 스캔됩니다. 직접 편집하지 마세요.

• 결정 사항은 추가 전용입니다. 기존 결정을 대체하려면 이를 참조하는 새 결정을 기록합니다. 기존 ADR에 대한 유일한 편집은 - Superseded-by: NNNN 메타데이터 줄입니다.

• 계획은 변경 가능합니다 — update_plan이 덮어씁니다.

• project.md와 constraints.md는 인간의 근거 진실입니다. 서버는 이를 읽기만 하고 절대 쓰지 않습니다.

도구

길이 제한은 저장 제한이 아닌 의도적인 안티슬러지 규율입니다: 제목 80자, ADR 섹션 각 1200자, 메모 500자, 계획 8000자. 초과 시 실제 길이와 제한을 명시하는 메시지를 반환하여 에이전트가 요약하고 재시도할 수 있습니다.

search_context는 없습니다. 작은 마크다운 폴더에 대한 grep으로 충분하며, 에이전트는 이미 이를 사용합니다.

안전

• 모든 경로는 단일 가드로 확인됩니다. ai_context/ 외부는 절대 읽거나 쓰지 않으며, 슬러그나 주제의 경로 탐색은 조용히 정리되는 대신 거부됩니다.

• 쓰기는 임시 파일에 수행된 후 제자리로 이름이 변경되므로, 충돌 시 반쯤 쓰인 파일이 남지 않습니다.

• 호출 간 상태 없음, 캐시 없음. 인간, git pull 또는 다른 에이전트의 편집은 다음 호출에서 반영됩니다.

개발

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

라이선스

MIT