Skip to content

README.ja.md

Latest commit

 

History

History
269 lines (192 loc) · 9.19 KB

README.ja.md

File metadata and controls

269 lines (192 loc) · 9.19 KB

ccontext-mcp — AI エージェントの実行コンテキスト

English | 中文 | 日本語

ccontext はローカルファーストの MCP サーバーです。AI エージェントがセッションを跨いでも迷子にならないよう、**実行可能な「プロジェクトの共通コンテキスト」**を維持します： Vision（北極星） · Sketch（静的ブループリント） · Milestones（フェーズ） · Tasks（成果物） · Notes/Refs（知識） · Presence（いま何をしているか）

🧠 永続的なエージェント記憶 • 📋 エージェント向けタスク設計 • 🧹 衛生機構（診断 + ライフサイクル） • ⚡ 1 回でまとめて更新 • 🔒 ローカル YAML、インフラ不要

PyPI Python License

🖼️ ccontext を一目で

ディスク上のファイル（移植性が高く Git と相性が良い）

your-project/
└── context/
    ├── context.yaml           # vision, sketch, milestones, notes, references（contract を内蔵）
    ├── tasks/
    │   ├── T001.yaml          # 成果物タスク（steps 付き）
    │   └── T002.yaml
    ├── presence.yaml          # ランタイム状態（gitignore 推奨）
    ├── .ccontext.lock         # ロックファイル（gitignore 推奨）
    └── archive/               # 自動アーカイブ（notes/refs/tasks、任意で gitignore）

1 回の呼び出しで「脳をロード」

get_context() は version + now + diagnostics を返し、エージェントが素早く状況把握できます：

{
  "version": "abc123def456",
  "now": {
    "active_milestone": { "id": "M2", "name": "Phase 2", "description": "...", "status": "active" },
    "active_tasks": [{ "id": "T001", "name": "Implement auth", "milestone": "M2" }]
  },
  "diagnostics": {
    "debt_score": 2,
    "top_issues": [{ "id": "NO_ACTIVE_MILESTONE", "severity": "info", "message": "No active milestone." }]
  },
  "context": { "...": "vision/sketch/milestones/notes/references/tasks_summary" }
}

なぜ ccontext？（痛み → 効果）

よくある問題

  • セッションを跨ぐと「何をしていたか」を忘れる。
  • マルチエージェントは共通の事実源がないと調整コストが N² になる。
  • コンテキストが肥大化し、古い情報がノイズ/誤誘導になる。

得られる効果

  • 即再開：毎回同じ構造化コンテキストから続きができる。
  • 協調が整理される：presence は「誰が何をしているか」、tasks は「何がどこまで終わったか」。
  • 長期運用に強い：diagnostics が「コンテキストの負債」を可視化し、ライフサイクルが肥大化を防ぐ。

✨ ccontext の強み

🗂️ ローカルファースト / 移植性
コンテキストはリポジトリ内の YAML。DB もクラウドも不要、ロックインなし。

📋 エージェント向け構造
Vision/Sketch/Milestones/Tasks/Notes で「実行」を支える形に最適化。

⚡ 低摩擦の更新
commit_updates() で status + task step + note を 1 回で更新。

🧹 コンテキスト衛生
get_context() が diagnostics/top issues を返し、次の手入れが明確。

⏳ ライフサイクル内蔵
notes/refs は ttl により減衰・自動アーカイブされ、鮮度を維持。

👥 読める Presence
Presence は単一行・重複排除で、表示が破綻しにくい。

コアモデル（Contract）

  • Vision：1 行の北極星。頻繁に変えない。
  • Sketch：静的ブループリントのみ（設計/戦略/制約/重要決定）。
    TODO/日次進捗/タスクリストは 書かない（tasks/milestones に置く）。
  • Milestones：粗いフェーズ（通常 2–6）。active は原則 1 つ。
  • Tasks：成果物単位、3–7 steps。handoff を跨ぐ仕事は task にする。
  • Notes/References：忘れてはいけない知見と、参照すべき場所。
  • Presence：いま何をしている/考えているか（短く）。

この contract は context.yaml の meta.contract に埋め込まれ、単体運用でも迷わないようにします。

インストール

Claude Code

# uvx（推奨）
claude mcp add ccontext -- uvx ccontext-mcp

# または pipx
claude mcp add ccontext -- pipx run ccontext-mcp

Claude Desktop

claude_desktop_config.json に追加：

{
  "mcpServers": {
    "ccontext": {
      "command": "uvx",
      "args": ["ccontext-mcp"],
      "env": { "CCONTEXT_ROOT": "/path/to/your/project" }
    }
  }
}

その他の MCP クライアント / 手動実行

pip install ccontext-mcp
CCONTEXT_ROOT=/path/to/project ccontext-mcp

ルート選択: CCONTEXT_ROOT があればそれを使用し、なければカレントディレクトリを使用します。

推奨エージェントループ

  1. 毎回最初にコンテキストを読む
ctx = get_context()  # first
  1. 足りなければ基礎を整える
update_vision("Ship a reliable X that achieves Y.")
update_sketch("## Architecture\n...\n## Strategy\n...\n## Risks\n...")
  1. active milestone を 1 つ保つ
create_milestone(name="Phase 1: Foundation", description="...", status="active")
  1. 実作業は tasks に落とす
create_task(
  name="Implement auth",
  goal="Users can sign in and sessions are validated",
  steps=[
    {"name":"Design", "acceptance":"Spec reviewed"},
    {"name":"Implement", "acceptance":"Tests passing"},
    {"name":"Rollout", "acceptance":"Docs updated"}
  ],
  milestone_id="M1",
  assignee="peer-a"
)
  1. 更新は 1 回でまとめる
commit_updates(ops=[
  {"op":"presence.set","agent_id":"peer-a","status":"Auth: implementing session validation; checking edge cases"},
  {"op":"task.step","task_id":"T001","step_id":"S2","step_status":"done"},
  {"op":"note.add","content":"Edge case: empty header triggers fallback path","ttl":50}
])

Tools 一覧

カテゴリ Tool 目的
Context get_context() 最初に呼ぶ。version/now/diagnostics + 全体の context を返す。
commit_updates() presence + task 進捗 + notes/refs を 1 回で更新。
Vision / Sketch update_vision() 北極星を設定。
update_sketch() ブループリント更新（静的。TODO/進捗は書かない）。
Presence get_presence() 他のエージェント状況を見る。
update_my_status() 自分の状況を更新（1–2 文）。
clear_status() 状況をクリア（古い status を残さない）。
Milestones create_milestone() / update_milestone() / complete_milestone() / remove_milestone() フェーズ管理。
Tasks list_tasks() / create_task() / update_task() / delete_task() 成果物と steps を管理。
Notes / Refs add_note() / update_note() / remove_note() 知見を残す（ttl ライフサイクル）。
add_reference() / update_reference() / remove_reference() 参照（ファイル/URL）を残す（ttl ライフサイクル）。

Version Tracking（ETag 風）

軽量に変更検出できます：

v = get_context()["version"]
# ... later ...
if get_context()["version"] != v:
    ctx = get_context()

注：version はセマンティックです。notes/refs の ttl 減衰は意図的に無視し、頻繁な read で version が揺れないようにします。

Diagnostics & Lifecycle（衛生と鮮度）

  • Diagnostics：get_context() が diagnostics（debt_score と top_issues など）を返し、手入れポイントが分かる。
  • TTL ライフサイクル：notes/refs は get_context() 呼び出しで -1 され、古いものは自動アーカイブ。
  • Presence 正規化：agent_id は正規化 + 重複排除。status は単一行に整形し、読みやすく保つ。

Git 推奨設定

多くのチームは以下を好みます：

context/presence.yaml
context/.ccontext.lock
context/archive/

context/context.yaml と context/tasks/ はコミットし、変更がレビュー可能になるようにします。

単体でも、Orchestrator と一緒でも

  • 単体運用：MCP 対応のエージェントクライアントでそのまま使えます。
  • Orchestrator 連携：CCCC のようなツールは同じ context/ を読み書きしてランタイム UX を提供できます。
  • MCP がなくても：YAML を直接読み書きできます（ただし batch updates や diagnostics の利便性は落ちます）。

License

MIT