AI导哈

知识库管理工具

Heptabase MCP CLI 是一个命令行工具，用于通过官方 MCP API 搜索、读取和写入 Heptabase 知识库，提供语义搜索、白板探索、对象深度读取、PDF 工具等功能。

  • by johnliu33
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 johnliu33/heptabase-mcp-cli

使用说明

Heptabase MCP CLI

正体中文版README

CLI工具，用于搜索、阅读和编写您的 乙酰肝素酶 通过官方的知识库 主控程序 API

特性

  • OAuth身份验证 --基于浏览器的登录，令牌自动刷新
  • 9个MCP工具 -Heptabase官方MCP API全面覆盖
  • 语义搜索 --跨笔记、期刊、PDF的混合全文+语义搜索
  • 白板探索 --搜索和检查白板结构
  • 对象深度读取 --检索任何卡片、日记或媒体的全部内容
  • 日记和写作 --读取/附加日记，创建笔记卡
  • PDF工具 --BM25 PDF内搜索，页面范围提取
  • 5个工作流程 --多步自动化流水线（白板深度学习、PDF研究、知识复习、主题分析、孤儿检测）
  • TUI模式 --带有斜线命令的REPL式终端
  • 交互模式 --菜单驱动的深入探索
  • 内存缓存 -避免多余的API调用（60秒用于搜索，300秒用于读取）
  • 带抖动重试 --指数退避+随机抖动以获得稳定性

先决条件

安装

git clone https://github.com/johnliu33/heptabase-mcp-cli.git
cd heptabase-mcp-cli
pnpm install
pnpm build

快速开始

正体中文快速上手指南

# 1. Login via OAuth (opens browser)
heptabase auth login

# 2. Search your notes
heptabase search "machine learning"

# 3. Launch TUI mode (recommended)
heptabase tui

命令

auth --身份验证

heptabase auth login     # OAuth login (opens browser)
heptabase auth status    # Show token status
heptabase auth logout    # Clear local token

search --语义搜索

# Single query
heptabase search "MCP protocol"

# Multiple queries for broader coverage (max 3)
heptabase search "machine learning" "deep learning"

# Filter by object type
heptabase search "notes" --type card journal

# JSON output
heptabase search "MCP" --json

whiteboard --白板操作

# Search whiteboards by keywords (max 5)
heptabase whiteboard search "project" "design"

# Get whiteboard structure by ID
heptabase whiteboard get <whiteboard-id>

object --对象操作

# Read full content of a card
heptabase object get <object-id>

# Specify object type (default: card)
heptabase object get <id> --type journal
heptabase object get <id> --type pdfCard

journal --日志操作

# Read today's journal
heptabase journal today

# Read journals by date range (auto-splits if > 90 days)
heptabase journal get --from 2025-01-01 --to 2025-01-31

# Append content to today's journal
heptabase journal append "Today I learned about MCP"

save --创建笔记卡

# Create a new card (first h1 becomes the title)
heptabase save "# My Title\n\nSome content here"

pdf --PDF操作

# Search within a PDF (BM25)
heptabase pdf search <pdfCardId> "keyword1" "keyword2"

# Get specific pages
heptabase pdf pages <pdfCardId> 1 5

workflow --多步骤工作流

# Whiteboard deep dive: search + fetch all objects
heptabase workflow whiteboard-deep-dive --query "project"
heptabase workflow wdd --id <whiteboard-id> --json

# PDF research: find PDF + extract relevant pages
heptabase workflow pdf-research "machine learning"
heptabase workflow pr "topic" --pdf-id <id>

# Knowledge review: journals + related notes
heptabase workflow knowledge-review 2025-01-01 2025-01-31 --topic "AI"

# Topic analysis: semantic search + full content
heptabase workflow topic-analysis "deep learning" --max-notes 5

# Orphan detection: find notes not on any whiteboard
heptabase workflow orphan-detection --query "project"

工作流程说明

工作流 描述
whiteboard-deep-dive 搜索白板，然后获取白板上每个对象的完整内容。PDF对象使用 search_pdf_content 而不是 get_object.
pdf-research 通过语义搜索按主题查找PDF，使用BM25定位相关块，然后提取匹配页面的整页内容。
knowledge-review 检索某个日期范围内的日记，可以选择按主题搜索相关笔记。自动拆分范围>90天。
topic-analysis 对主题进行语义搜索，然后并行获取每个匹配笔记的完整内容（最多可达 max_notes).
orphan-detection 将通过语义搜索找到的对象与放置在白板上的对象进行比较，显示不在任何白板上的笔记。

tui --TUI模式

heptabase tui
# or
heptabase t

带有斜线命令的REPL风格终端。支持所有搜索/读/写操作和所有5个工作流：

/search <query>              Semantic search
/journal [from] [to]         Read journals
/append <content>            Append to today's journal
/save <content>              Create note card
/whiteboard <keywords>       Search whiteboards
/object <id> <type>          Read object
/deep-dive <query|id>        Whiteboard deep dive workflow
/pdf-research <topic> [id]   PDF research workflow
/review <start> <end> [topic] Knowledge review workflow
/topic <topic> [max]         Topic analysis workflow
/orphans [query]             Orphan detection workflow
/help                        Show all commands

interactive --交互模式

heptabase interactive
# or
heptabase i

菜单驱动模式：搜索笔记、浏览白板、深入对象。

全局选项

heptabase --verbose ...   # Enable debug logging
heptabase --version       # Show version

建筑

CLI / TUI (commander + readline)
 └─ Workflows (multi-step orchestration)
     └─ HeptabaseClient (Layer 2 — cache + logging)
         └─ McpClient (Layer 1 — StreamableHTTP + OAuth + retry)
             └─ Heptabase Official MCP Server
                https://api.heptabase.com/mcp

这个项目是 客户端层 包装官方的Heptabase MCP——它不实现自己的MCP服务器。所有数据访问都通过9个官方MCP工具：

工具 说明
semantic_search_objects 混合全文+语义搜索
search_whiteboards 白板关键字搜索
get_whiteboard_with_objects 阅读白板结构和对象
get_object 读取任何对象的完整内容
get_journal_range 按日期范围阅读期刊
save_to_note_card 创建新的笔记卡
append_to_journal 将内容添加到今天的日记中
search_pdf_content BM25在PDF中搜索
get_pdf_pages 阅读PDF的特定页面

发展

pnpm dev           # Run with tsx
pnpm build         # Build with tsup
pnpm test          # Run tests (vitest)
pnpm test:e2e      # Run E2E tests
pnpm lint          # Type check (tsc --noEmit)

项目结构

src/
├── index.ts                 # CLI entry point
├── transport/               # Layer 1: MCP connection + OAuth
├── client/                  # Layer 2: typed tool wrappers (search, read, write, pdf)
├── cli/commands/            # CLI subcommands + TUI
├── cache/                   # In-memory TTL cache
├── types/                   # TypeScript type definitions
├── workflows/               # Multi-step workflow orchestrations
└── utils/                   # Logger, retry with backoff + jitter

tests/
├── contract/                # Contract tests (CT-01 ~ CT-12)
├── workflow/                # Workflow tests (WT-01 ~ WT-06)
├── e2e/                     # E2E integration tests (E2E-01 ~ E2E-02)
└── unit/                    # Unit tests (cache, retry, date-range)

测试覆盖率

  • 合同测试 （CT-01~CT-12）：验证每个MCP工具包装器对模拟响应的行为是否正确
  • 工作流测试 （WT-01~WT-06）：验证多步骤工作流编排和容错
  • E2E测试 （E2E-01~E2E-02）：使用模拟MCP客户端进行端到端集成测试
  • 单元测试：缓存TTL，抖动重试，日期范围分割

令牌存储

OAuth令牌存储在 ~/.heptabase-extension/token.json 随着 0600 权限（仅限所有者读/写）。

路线图

  • [x] 第一阶段：搜索+读取（4个工具）+OAuth+缓存+CLI
  • [x] 第2阶段：日志、书写操作、PDF工具（共9个工具）
  • [x] 第三期：工作流程（白板深度学习、PDF研究、知识复习）+TUI
  • [x] 阶段4：主题分析、孤儿检测、性能优化、E2E测试

许可证

麻省理工学院

相关 MCP