Context Book

别再反复向 Agent 解释。及时为它提供正确的上下文。

大模型没有状态——每次对话都从头开始。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

两个 Go 二进制程序共用一个 PostgreSQL 数据库：

• API 服务（cmd/api）——控制平面：用户登录、OAuth 2.0、仪表盘、书籍／页面 CRUD
• MCP 服务（cmd/mcp）——数据平面：为 AI Agent 提供 8 个 MCP 工具，并通过 Bearer 令牌进行保护

MCP 工具

所有工具都需要有效的 Bearer 令牌，并且仅限已通过身份验证的用户使用。

工具	说明
book_create_or_update	创建书籍或更新其元数据
book_list	分页列出书籍元数据
book_get	获取一本书的所有页面
page_insert	向书籍中推送一个原子页面；立即生成嵌入向量
page_update	替换页面内容；重新生成嵌入向量
page_delete	移除页面（不重新编号索引）
page_search	跨所有书籍进行语义搜索
readme	返回使用指南（每个会话调用一次）

快速开始

前置要求

• Go 1.26+
• Node.js 22+
• PostgreSQL 16+，并安装 pgvector 和 pg_trgm
• 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. Fork 此仓库
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 文件。