Heptabase MCP CLI
正体中文版README
CLI工具，用于搜索、阅读和编写您的 乙酰肝素酶 通过官方的知识库 主控程序 API
特性
- OAuth身份验证 --基于浏览器的登录，令牌自动刷新
- 9个MCP工具 -Heptabase官方MCP API全面覆盖
- 语义搜索 --跨笔记、期刊、PDF的混合全文+语义搜索
- 白板探索 --搜索和检查白板结构
- 对象深度读取 --检索任何卡片、日记或媒体的全部内容
- 日记和写作 --读取/附加日记，创建笔记卡
- PDF工具 --BM25 PDF内搜索，页面范围提取
- 5个工作流程 --多步自动化流水线（白板深度学习、PDF研究、知识复习、主题分析、孤儿检测）
- TUI模式 --带有斜线命令的REPL式终端
- 交互模式 --菜单驱动的深入探索
- 内存缓存 -避免多余的API调用（60秒用于搜索，300秒用于读取）
- 带抖动重试 --指数退避+随机抖动以获得稳定性
先决条件
- Node.js>=18
- A. 乙酰肝素酶 账户
- pnpm（推荐）或npm
安装
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 tokensearch --语义搜索
# 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" --jsonwhiteboard --白板操作
# Search whiteboards by keywords (max 5)
heptabase whiteboard search "project" "design"
# Get whiteboard structure by ID
heptabase whiteboard get object --对象操作
# Read full content of a card
heptabase object get
# Specify object type (default: card)
heptabase object get --type journal
heptabase object get --type pdfCardjournal --日志操作
# 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
"keyword1" "keyword2"
# Get specific pages
heptabase pdf pages
1 5workflow --多步骤工作流
# Whiteboard deep dive: search + fetch all objects
heptabase workflow whiteboard-deep-dive --query "project"
heptabase workflow wdd --id --json
# PDF research: find PDF + extract relevant pages
heptabase workflow pdf-research "machine learning"
heptabase workflow pr "topic" --pdf-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 Semantic search
/journal [from] [to] Read journals
/append Append to today's journal
/save Create note card
/whiteboard Search whiteboards
/object Read object
/deep-dive Whiteboard deep dive workflow
/pdf-research [id] PDF research workflow
/review [topic] Knowledge review workflow
/topic [max] Topic analysis workflow
/orphans [query] Orphan detection workflow
/help Show all commandsinteractive --交互模式
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测试
许可证
麻省理工学院