---
slug: "marp-lens"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/hirokidaichi/marp-lens@main/README.md"
repo: "https://github.com/hirokidaichi/marp-lens"
source_file: "README.md"
branch: "main"
---
# marp-lens

<p align="center">
  <img src="img/logo.png" alt="marp-lens logo" width="400">
</p>

[![CI](https://github.com/hirokidaichi/marp-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/hirokidaichi/marp-lens/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/marp-lens.svg)](https://www.npmjs.com/package/marp-lens)

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

## 特徴

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

## インストール

### npxで直接実行（推奨）

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

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

### グローバルインストール

```bash
npm install -g marp-lens
```

### ソースからビルド

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

## セットアップ

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

```bash
cp .env.example .env
```

2. Gemini APIキーを設定:

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

APIキーは[Google AI Studio](https://aistudio.google.com/)で取得できます。

## 使い方

### スライドのインデックス

```bash
# カレントディレクトリの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
```

### スライドの検索

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

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

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

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

### 特定スライドの取得

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

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

### 統計情報の表示

```bash
marp-lens stats
```

出力例:
```
Database Statistics

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

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

```bash
# ファイル変更を監視して自動的に再インデックス
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 |

## 開発

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

# 型チェック
npm run typecheck

# テスト実行
npm test

# ビルド
npm run build
```

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

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

```bash
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