金大哥 - oracle-v2 MCP 详情

article

README

🚀 Oracle Nightly - MCP Memory Layer

Oracle Nightly - MCP Memory Layer 是一个用于对 Oracle 哲学进行语义搜索的 TypeScript MCP 服务器，它采用了 SQLite FTS5 和 ChromaDB 的混合搜索方式，同时提供 HTTP API 和 Vault CLI 工具。

🚀 快速开始

本项目提供了多种启动方式，你可以根据自己的需求选择合适的方法。

安装

bunx（推荐）

本项目通过 GitHub 进行分发，无需在 npm 上发布：

# MCP 服务器（标准输入输出，适用于 Claude Code）
bunx --bun oracle-v2@github:Soul-Brews-Studio/oracle-v2#main

# Vault CLI（辅助二进制文件 — 使用 --package）
bunx --bun --package oracle-v2@github:Soul-Brews-Studio/oracle-v2#main oracle-vault --help

添加到 Claude Code

claude mcp add oracle-v2 -- bunx --bun oracle-v2@github:Soul-Brews-Studio/oracle-v2#main

或者在 ~/.claude.json 中添加以下内容：

{
  "mcpServers": {
    "oracle-v2": {
      "command": "bunx",
      "args": ["--bun", "oracle-v2@github:Soul-Brews-Studio/oracle-v2#main"]
    }
  }
}

从源代码安装

git clone https://github.com/Soul-Brews-Studio/oracle-v2.git
cd oracle-v2 && bun install
bun run dev          # MCP 服务器
bun run server       # 在端口 47778 上启动 HTTP API

安装脚本（旧版）

curl -sSL https://raw.githubusercontent.com/Soul-Brews-Studio/oracle-v2/main/scripts/install.sh | bash

故障排除

| 问题 | 解决方案 | |---------|-----| | bun: command not found | export PATH="$HOME/.bun/bin:$PATH" | | ChromaDB 挂起/超时 | 跳过它 — SQLite FTS5 在没有向量的情况下也能正常工作 | | 服务器在空数据库上崩溃 | 先运行 bun run index 来索引知识库 |

✨ 主要特性

混合搜索：结合 SQLite FTS5 和 ChromaDB 进行语义搜索。
HTTP API：提供丰富的 API 接口，方便进行各种操作。
Vault CLI：全局 CLI 工具，用于管理 Oracle 知识库。
多工具支持：提供 22 种工具，可通过 Claude Code 使用。

📦 安装指南

系统要求

Bun 运行时（>=1.2.0）
SQLite + FTS5 用于全文搜索
ChromaDB 用于向量/语义搜索
Drizzle ORM 用于类型安全的查询
Hono 用于 HTTP API
MCP 协议用于 Claude 集成

安装步骤

见上文快速开始部分的安装说明。

💻 使用示例

MCP 工具

本项目提供了 22 种工具，可通过 Claude Code 使用： | 工具 | 描述 | |------|-------------| | oracle_search | 混合搜索（FTS5 + ChromaDB） | | oracle_reflect | 随机智慧 | | oracle_learn | 添加新模式 | | oracle_list | 浏览文档 | | oracle_stats | 数据库统计信息 | | oracle_concepts | 列出概念标签 | | oracle_supersede | 将文档标记为已取代 | | oracle_handoff | 会话交接 | | oracle_inbox | 收件箱消息 | | oracle_verify | 验证文档 | | oracle_thread | 创建线程 | | oracle_threads | 列出线程 | | oracle_thread_read | 读取线程 | | oracle_thread_update | 更新线程 | | oracle_trace | 创建跟踪 | | oracle_trace_list | 列出跟踪 | | oracle_trace_get | 获取跟踪 | | oracle_trace_link | 链接跟踪 | | oracle_trace_unlink | 取消链接跟踪 | | oracle_trace_chain | 跟踪链 | | oracle_schedule_add | 添加日程条目 | | oracle_schedule_list | 列出日程 |

Vault CLI

全局 CLI 工具，用于管理 Oracle 知识库：

oracle-vault init <owner/repo>    # 使用 GitHub 仓库初始化 Vault
oracle-vault status               # 显示配置和待处理的更改
oracle-vault sync                 # 提交并推送到 GitHub
oracle-vault pull                 # 将 Vault 文件拉取到本地 ψ/
oracle-vault migrate              # 从 ghq 仓库中导入 Vault

API 端点

HTTP API 在端口 47778 上运行（bun run server）： | 端点 | 描述 | |----------|-------------| | GET /api/health | 健康检查 | | GET /api/search?q=... | 全文搜索 | | GET /api/consult?q=... | 获取指导 | | GET /api/reflect | 随机智慧 | | GET /api/list | 浏览文档 | | GET /api/stats | 数据库统计信息 | | GET /api/graph | 知识图谱数据 | | GET /api/context | 项目上下文 | | POST /api/learn | 添加新模式 | | GET /api/threads | 列出线程 | | GET /api/decisions | 列出决策 |

📚 详细文档

项目架构

oracle-v2 (一个包，两个二进制文件)
├── bunx oracle-v2                          → MCP 服务器 (src/index.ts)
├── bunx --package oracle-v2 oracle-vault   → Vault CLI (src/vault/cli.ts)
├── bun run server                          → HTTP API (src/server.ts)
└── bun run index                           → 索引器 (src/indexer.ts)

oracle-studio (单独的仓库)
└── bunx oracle-studio                      → React 仪表盘

项目结构

oracle-v2/
├── src/
│   ├── index.ts          # MCP 服务器入口
│   ├── server.ts         # HTTP API (Hono)
│   ├── indexer.ts        # 知识索引器
│   ├── vault/
│   │   └── cli.ts        # Vault CLI 入口
│   ├── tools/            # MCP 工具处理程序
│   ├── trace/            # 跟踪系统
│   ├── db/
│   │   ├── schema.ts     # Drizzle 模式
│   │   └── index.ts      # 数据库客户端
│   └── server/           # HTTP 服务器模块
├── scripts/              # 设置和实用脚本
├── docs/                 # 文档
└── drizzle.config.ts     # Drizzle 配置

配置

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | ORACLE_PORT | 47778 | HTTP 服务器端口 | | ORACLE_REPO_ROOT | process.cwd() | 知识库根目录 |

数据库操作

Drizzle ORM 与 SQLite 结合使用：

bun db:push       # 将模式推送到数据库
bun db:generate   # 生成迁移文件
bun db:migrate    # 应用迁移
bun db:studio     # 打开 Drizzle Studio GUI

测试

bun test              # 运行所有测试
bun test:unit         # 运行单元测试
bun test:integration  # 运行集成测试
bun test:e2e          # 运行 Playwright E2E 测试
bun test:coverage     # 运行测试并生成覆盖率报告

🔧 技术细节

运行时：使用 Bun 运行时（>=1.2.0），提供高效的开发和运行环境。
搜索技术：采用 SQLite FTS5 进行全文搜索，ChromaDB 进行向量/语义搜索，结合两者的优势，提供更准确的搜索结果。
ORM：使用 Drizzle ORM 进行类型安全的数据库查询，确保代码的健壮性。
HTTP API：使用 Hono 构建 HTTP API，提供简洁高效的接口。
MCP 协议：通过 MCP 协议与 Claude 集成，实现更强大的功能。

📄 许可证

文档未提及相关许可证信息。

🔗 参考资料

TIMELINE.md - 完整的演变历史
docs/API.md - API 文档
docs/architecture.md - 架构细节
Drizzle ORM
MCP SDK

🙏 致谢

本项目受到了 Alex Newman 的 claude-mem 的启发，借鉴了其进程管理模式、工作服务架构和钩子系统的概念。

oracle-v2