agent-context-mcp

AIコーディングエージェント向けの、ハーネスに依存しない永続的なプロジェクトメモリ。

ステートレスなMCPサーバーで、Claude Code、Codex、Kilo Code、OpenCode、Cursorなど、あらゆるエージェントに、プロジェクトごとのai_context/フォルダ内のプレーンマークダウンへの構造化された読み書きアクセスを提供します。決定事項、計画、制約、メモはリポジトリ内に保存され、gitで同期され、サーバーがインストールされていないエージェントでも読み取れる状態を保ちます。

エージェントがいつ・何を記録するかを決定します。サーバーは形式と場所を決定します。この意見の押し付けこそが要点です。エージェントに自由形式の書き込みを許可すると、フォルダーはすぐに役に立たないものに劣化します。

これは何ではないか

コード検索、セマンティック検索、埋め込み、データベース、デーモン状態は一切ありません。純粋なファイルI/Oです。コード検索ツールと競合するのではなく、組み合わせて使います。

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クライアントは、それぞれの設定ファイルで同じ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