SQLite Vector MCP Server (Electron + Bun)

🚀 Bun と Electron を使用した常駐型 MCP サーバー。SQLite + sqlite-vec でベクトル検索機能を提供。

特徴

• 🎯 常駐アプリ：システムトレイで常時実行
• 🔍 ベクトル検索：sqlite-vec で高速な近傍検索
• 🧠 LLM 統合：llama.cpp でテキスト生成・埋め込み生成
• 📡 MCP サーバー：SSE（Server-Sent Events）で接続可能
• ✅ テストスイート：35 テスト、100% 成功
• 🔧 設定可能：環境変数で柔軟にカスタマイズ

対応する MCP ツール

クイックスタート

前提条件

• Node.js/Bun: bun 1.3.8 以上
• Electron: アプリケーション内で自動インストール
• llama.cpp: 埋め込み・生成機能を使う場合は別途サーバー起動

インストール

git clone <repository-url>
cd sqlitevector
bun install

環境設定

.env ファイルを作成（またはコピー）：

# 既存の .env をコピー
cp .env.example .env  # 存在する場合

# または手動作成
cat > .env << 'EOF'
LLAMA_CPP_BASE_URL=http://127.0.0.1:8080
LLAMA_CPP_EMBEDDING_MODEL=nomic-embed-text
LLAMA_CPP_MODEL=mistral
VEC_DIM=3
MCP_PORT=3000
EOF

起動

# Electron アプリとして起動
bun start

# ポート指定で起動
MCP_PORT=3001 bun start

アプリケーション起動後、システムトレイに SQLite Vector MCP アイコンが表示されます。

設定

環境変数

MCP クライアント設定

mcp.json または Claude Desktop など MCP クライアントの設定ファイルに：

{
  "mcpServers": {
    "sqlite-vector-electron": {
      "url": "http://localhost:3000/sse"
    }
  }
}

使用方法

MCP ツール呼び出し例

// テキストから自動的に埋め込みを生成して保存
await callTool("add_item_text", {
  content: "This is a sample document",
  path: "/docs/sample.txt"
});

// ベクトルで検索
await callTool("search_vector", {
  vector: [0.1, 0.2, 0.3]
});

// テキストで検索（自動的に埋め込みを生成）
await callTool("search_text", {
  content: "Similar documents"
});

// llama.cpp でテキスト生成
await callTool("llm_generate", {
  prompt: "What is machine learning?",
  options: { temperature: 0.7, n_predict: 128 }
});

テスト

すべてのテストを実行

bun test

特定のテストモジュール実行

bun test test/db.test.js            # DB テスト（5テスト）
bun test test/mcp-tools.test.js     # ツール定義テスト（11テスト）
bun test test/mcp-handlers.test.js  # ハンドラーテスト（6テスト）
bun test test/llama-client.test.js  # LLama テスト（9テスト）
bun test test/integration.test.js   # 統合テスト（4テスト）

ウォッチモード（ファイル変更時に自動実行）

bun run test:watch

テスト結果: 35 テスト全て成功 (139 expect calls)

プロジェクト構造

sqlitevector/
├── src/
│   ├── main.js           # Electron 起動・常駐処理
│   ├── mcp-server.js     # MCP SSE サーバー
│   ├── mcp-tools.js      # ツール定義
│   ├── mcp-handlers.js   # ツール実装
│   ├── db.js             # DB 接続・初期化
│   ├── llama-client.js   # llama.cpp API
│   └── index.html        # GUI ウィンドウ
├── test/
│   ├── setup.js          # テスト用ユーティリティ
│   ├── db.test.js        # DB テスト
│   ├── mcp-tools.test.js # ツール定義テスト
│   ├── mcp-handlers.test.js
│   ├── llama-client.test.js
│   ├── integration.test.js
│   └── README.md         # テスト詳細ドキュメント
├── document/
│   ├── overview.md       # アーキテクチャ解説
│   └── openapi.yaml      # REST API 仕様
├── journals/
│   └── 20260206-0000-案件.md  # 作業報告書
├── .env                  # 環境変数
├── .gitignore
├── package.json
└── README.md (this file)

アーキテクチャ

データフロー

graph TD
  A[MCP Client] -->|SSE| B[Express /sse]
  B --> C[MCP Server]
  C --> D{Tool Handler}
  D -->|embedding| L[llama.cpp API]
  D -->|insert| E[knex: items]
  D -->|insert| F[sqlite-vec: vec_items]
  D -->|search| F
  F --> G[Results]
  E --> G
  G --> C
  C --> B
  B --> A

データベーススキーマ

items table:
  ├── id (PRIMARY KEY)
  ├── content (TEXT) - アイテムテキスト
  ├── path (TEXT) - ファイルパス参照
  ├── created_at (TIMESTAMP)
  └── updated_at (TIMESTAMP)

vec_items table (sqlite-vec):
  ├── id (PRIMARY KEY)
  └── embedding (float[VEC_DIM]) - ベクトル

トラブルシューティング

better-sqlite3 compilation error

electron-rebuild

MCP サーバーが接続できない

1. ポート確認: netstat -an | grep 3000（Windows: netstat -ano | findstr "3000"）
2. mcp.json の URL を確認: http://localhost:3000/sse
3. .env の MCP_PORT を確認

llama.cpp 接続エラー

# llama.cpp サーバーが起動しているか確認
curl http://127.0.0.1:8080/health

# .env の LLAMA_CPP_BASE_URL を確認

テストが失敗する

# DB ファイルをクリア
rm -f vector.db test-*.db

# テストを再実行
bun test

開発ガイド

新しいツールを追加

1. src/mcp-tools.js で定義
2. src/mcp-handlers.js で実装
3. test/ でテスト作成

コード品質

• すべてのツール変更は test/ でテスト作成
• 既存の 35 テストは常に成功を維持

⚠️ 重要な注意事項

knex はベクトル検索に対応していません

ベクトル検索は 必ず db.prepare() + raw SQL で実装してください。詳細は document/overview.md を参照。

sqlite-vec は Alpha 版

• 本番環境での使用は慎重に検討してください
• 安定版のリリースを待つか、代替ベクトルDB を検討してください

ライセンス

ISC License - 詳細は LICENSE を参照

貢献

プルリクエストを歓迎します！

参考リンク

• MCP Specification
• sqlite-vec
• llama.cpp
• Electron
• Bun