Context Book

エージェントに何度も説明するのはもうやめましょう。必要なときに、適切なコンテキストを提供します。

LLM はステートレスなため、会話のたびにゼロから始まります。ContextBook は、AI ツールが必要なときに適切なコンテキストを取り出せる、永続的で検索可能なナレッジライブラリを提供します。余計な機能も、事前に読み込まれた不要な情報もありません。必要な情報を、必要なときに提供します。

仕組み

flowchart LR
    AI["🤖 AI Clients\nClaude · Cursor · Windsurf"]
    Browser["🌐 Browser Dashboard"]
    MCP["🔌 MCP Server :8081\n8 Bearer-authenticated tools"]
    API["⚙️ REST API :8080\nOAuth 2.0 · Books · Pages · Search"]
    DB["🗄️ PostgreSQL\npgvector · pg_trgm"]
    VOYAGE["🧠 Voyage AI\nvoyage-4 (1024-dim)"]

    AI -- "MCP · Bearer Token" --> MCP
    Browser -- "Session · HTTP JSON" --> API
    MCP --- DB
    API --- DB
    API -- "OAuth 2.0 PKCE" --> AI
    DB --- VOYAGE

2 つの Go バイナリが PostgreSQL データベースを共有します。

• API サーバー（cmd/api） — コントロールプレーン：ユーザーログイン、OAuth 2.0、ダッシュボード、Book／ページの CRUD
• MCP サーバー（cmd/mcp） — データプレーン：AI エージェント向けの 8 つの MCP ツール。Bearer トークンで保護されています

MCP ツール

すべてのツールには有効な Bearer トークンが必要で、認証済みユーザーのスコープに限定されます。

ツール	説明
book_create_or_update	Book を作成するか、メタデータを更新します
book_list	Book のメタデータをページネーション付きで一覧表示します
book_get	Book のすべてのページを取得します
page_insert	Book にアトミックなページを追加し、すぐに埋め込みを生成します
page_update	ページの内容を置き換え、埋め込みを再生成します
page_delete	ページを削除します（インデックスは振り直されません）
page_search	すべての Book を対象にセマンティック検索します
readme	使用ガイドを返します（セッションごとに 1 回呼び出してください）

クイックスタート

前提条件

• Go 1.26+
• Node.js 22+
• pgvector および pg_trgm を備えた PostgreSQL 16+
• Voyage AI の API キー

1. データベースをセットアップする

CREATE DATABASE contextbook_db;
\c contextbook_db
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

API サーバーの起動時にマイグレーションが自動的に実行されます。

2. 環境を設定する

cp .env.example backend/.env
# Edit backend/.env — set DATABASE_URL, API_KEY_SALT, VOYAGE_API_KEY

3. バックエンドを実行する

cd backend
go run ./cmd/api/main.go    # API + dashboard (:8080)
go run ./cmd/mcp/main.go     # MCP server (:8081)

4. フロントエンドを実行する（任意）

cd frontend
npm install && npm run dev    # Vite dev server on :5173

5. AI クライアントを接続する

Cursor の場合（.cursor/mcp.json）：

{
  "mcpServers": {
    "contextbook": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

MCP 互換クライアントの場合は、サーバー URL に http://localhost:8081/mcp を指定してください。

ドキュメント

• バックエンド README — API ルート、認証フロー、データベーススキーマ、MCP ツール、設定
• フロントエンド README — コンポーネント、ルーティング、デザインシステム、開発環境のセットアップ
• アーキテクチャ — Mermaid 図を含むシステム全体の概要

プロジェクト構成

context-book/
├── backend/
│   ├── cmd/api/main.go          REST API + auth server
│   ├── cmd/mcp/main.go          MCP tool server
│   └── internal/
│       ├── api/                  REST handlers + routes
│       ├── auth/                 OAuth 2.0 PKCE, sessions, SSO
│       ├── context/              Book/Page business logic
│       ├── db/                  pgx queries + migrations
│       ├── embedding/            Voyage AI client
│       ├── logger/               slog + HTTP access logging
│       └── mcp/                  8 MCP tool handlers
├── frontend/                     React 19 + Vite + TypeScript SPA
│   └── src/
│       ├── App.tsx               Router + app shell
│       ├── lib/api.ts            HTTP client
│       └── components/           UI components
├── Dockerfile                    API server container
├── Dockerfile.mcp                MCP server container
└── go.work                       Go workspace

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/my-feature）
3. 変更を加えます
4. バックエンドがコンパイルできることを確認します（cd backend && go build ./cmd/api ./cmd/mcp）
5. フロントエンドをビルドできることを確認します（cd frontend && npm run build）
6. コミットしてプッシュします
7. Pull Request を作成します

ライセンス

MIT — 詳細は LICENSE ファイルをご覧ください。