marp-lens

Marpプレゼンテーション用のベクトル検索CLIツール。Gemini APIを使用してスライドの意味検索を実現します。

特徴

• 意味検索: Geminiの埋め込みモデルを使用したセマンティック検索
• インクリメンタルインデックス: 変更されたファイルのみを再インデックス
• 画像説明: Gemini Visionによるスライド内画像の自動説明（オプション）
• スピーカーノート対応: スピーカーノートも検索対象に含める
• 高速: SQLite + sqlite-vecによる高速ベクトル検索
• ウォッチモード: ファイル変更時の自動再インデックス

インストール

npxで直接実行（推奨）

インストール不要で直接実行できます：

npx marp-lens search "機械学習"
npx marp-lens index -d ./slides
npx marp-lens stats

グローバルインストール

npm install -g marp-lens

ソースからビルド

git clone https://github.com/hirokidaichi/marp-lens.git
cd marp-lens
npm install
npm run build

セットアップ

1. .envファイルを作成:

cp .env.example .env

2. Gemini APIキーを設定:

# .env
GEMINI_API_KEY=your-api-key-here

APIキーはGoogle AI Studioで取得できます。

使い方

スライドのインデックス

# カレントディレクトリのMarkdownファイルをインデックス
marp-lens index

# 特定のディレクトリをインデックス
marp-lens index -d ./slides

# 画像説明付きでインデックス
marp-lens index -d ./slides --with-images

# インデックスを再構築
marp-lens index -d ./slides --rebuild

# 特定のファイルのみインデックス
marp-lens index -f ./slides/presentation.md

スライドの検索

# 意味検索
marp-lens search "機械学習の基礎"

# 結果数を制限
marp-lens search "アーキテクチャ" --limit 5

# 類似度閾値を設定
marp-lens search "API設計" --threshold 0.7

# JSON形式で出力
marp-lens search "テスト" --format json

特定スライドの取得

# ファイル名とスライド番号で取得
marp-lens get "presentation.md #3"

# パスの一部でも検索可能
marp-lens get "slides.md #10"

統計情報の表示

marp-lens stats

出力例:

Database Statistics

┌─────────────────────────┬────────────────────┐
│ Total Files             │ 3                  │
├─────────────────────────┼────────────────────┤
│ Total Slides            │ 17                 │
├─────────────────────────┼────────────────────┤
│ Total Embeddings        │ 17                 │
├─────────────────────────┼────────────────────┤
│ Database Size           │ 3.08 MB            │
└─────────────────────────┴────────────────────┘

ウォッチモード（自動再インデックス）

# ファイル変更を監視して自動的に再インデックス
marp-lens watch -d ./slides

# 画像説明付きで監視
marp-lens watch -d ./slides --with-images

出力例:

marp-lens watch
──────────────────────────────────────────────────
  Directory: /path/to/slides
  Database:  /path/to/marp-lens.db
  Images:    No
──────────────────────────────────────────────────

Watching for changes... (Ctrl+C to stop)

15:30:45 [change] presentation.md
  Generating embeddings for 5 slides...
  Indexed: 5 slides

コマンドリファレンス

marp-lens index

Markdownファイルをインデックスします。

| オプション | 説明 | デフォルト | |-----------|------|-----------| | -d, --dir <path> | 検索対象ディレクトリ | カレントディレクトリ | | --db <path> | データベースファイルパス | ./marp-lens.db | | -f, --file <path> | 特定ファイルのみインデックス | - | | -r, --rebuild | インデックスを再構築 | false | | -i, --with-images | 画像説明を含める | false |

marp-lens search <query>

スライドを意味検索します。

| オプション | 説明 | デフォルト | |-----------|------|-----------| | -l, --limit <number> | 最大結果数 | 10 | | -t, --threshold <number> | 最小類似度閾値 (0-1) | 0 | | -o, --format <format> | 出力形式 (table or json) | table | | --db <path> | データベースファイルパス | ./marp-lens.db |

marp-lens get <file-slide>

特定のスライドの内容を取得します。

形式: <ファイルパス> #<スライド番号>

marp-lens stats

データベースの統計情報を表示します。

marp-lens watch

ファイル変更を監視して自動的に再インデックスします。

| オプション | 説明 | デフォルト | |-----------|------|-----------| | -d, --dir <path> | 監視対象ディレクトリ | カレントディレクトリ | | --db <path> | データベースファイルパス | ./marp-lens.db | | -i, --with-images | 画像説明を含める | false |

環境変数

| 変数 | 説明 | 必須 | |------|------|------| | GEMINI_API_KEY | Gemini APIキー | Yes | | MARP_LENS_DB | デフォルトのデータベースパス | No | | MARP_LENS_DIR | デフォルトのスライドディレクトリ | No |

開発

# 開発モードで実行
npm run dev -- index -d samples

# 型チェック
npm run typecheck

# テスト実行
npm test

# ビルド
npm run build

AIエージェント向けスキル

AIエージェントにmarp-lensスキルを追加すると、プレゼンテーションの検索・参照が可能になります。

npx skills add hirokidaichi/marp-lens

追加後、エージェントに「スライドを検索して」「プレゼンの内容を教えて」などと指示すると、自動的にmarp-lensを使用してスライドを検索します。

技術スタック

• TypeScript: 型安全な開発
• Gemini API: 埋め込み生成 (text-embedding-004) と画像説明 (gemini-2.0-flash)
• SQLite + sqlite-vec: ベクトルデータベース
• Commander.js: CLIフレームワーク
• Vitest: テストフレームワーク

ライセンス

MIT