SQLite Vector MCP Server（Electron + Bun）

概要

このプロジェクトは、Electron で常駐する MCP サーバーを立ち上げ、SQLite + sqlite-vec を使ってベクトル検索を提供します。MCP への接続は SSE（Server-Sent Events）で行い、埋め込み生成とテキスト生成は llama.cpp を利用します。

構成

Electron: 常駐アプリ（トレイ）としての実行基盤
MCP Server: SSE でツールを提供
DB: better-sqlite3 + sqlite-vec
ORM: knex（items テーブルの操作に使用）
LLM: llama.cpp（埋め込み生成・テキスト生成）

フォルダ構成

src/db.js: DB 接続・初期化
src/mcp-tools.js: MCP ツール定義
src/mcp-handlers.js: ツールの処理
src/mcp-server.js: SSE と MCP の接続
src/main.js: Electron 起動と常駐処理
src/llama-client.js: llama.cpp API クライアント

ツール一覧

add_item_text: テキストから埋め込みを生成して保存
add_item: ベクトルを直接指定して保存
search_text: テキストから埋め込みを生成して検索
search_vector: ベクトルで検索
llm_generate: llama.cpp でテキスト生成

データフロー（図解）

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

ER図

erDiagram
  items {
    INTEGER id PK
    TEXT content
    TEXT path
    TEXT created_at
    TEXT updated_at
  }

  vec_items {
    INTEGER id PK
    FLOAT embedding[VEC_DIM]
  }

  items ||--|| vec_items : "id = id"

環境変数

.env に以下を設定します。

LLAMA_CPP_BASE_URL=http://127.0.0.1:8080
LLAMA_CPP_EMBEDDING_MODEL=
LLAMA_CPP_MODEL=
VEC_DIM=3

実行

bun start

API 定義（REST / SSE）

SSE 接続

GET /sse
- MCP の SSE セッションを開始します。

MCP メッセージ送信

POST /messages
- MCP のリクエスト/レスポンスメッセージを送信します。
- SSE セッションが未接続の場合は 400 を返します。

注: /messages のペイロードは MCP 仕様に準拠します。

REST（追加予定）

現在は MCP 経由のツール呼び出しが主です。REST API を追加する場合は以下のような構成になります。

POST /api/items
- テキストから埋め込みを生成して保存
- Body: { "content": "..." }
POST /api/search
- テキストから埋め込みを生成して検索
- Body: { "content": "..." }

MCP 設定例

mcp.json などに以下を設定します。

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

⚠️ 重要な注意事項

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

問題:

knex は標準的な SQL クエリビルダーです
SQLite の sqlite-vec 拡張で提供される MATCH 演算子には対応していません
knex を経由してベクトル検索クエリを実行すると、MATCH 演算子がエスケープされてしまい、検索が機能しません

現在の解決方法:

// ベクトル検索は db.prepare() + raw SQL で実行
const results = db.prepare(`
  SELECT ... FROM vec_items v
  WHERE embedding MATCH ?    // ← sqlite-vec の MATCH 演算子
  ORDER BY distance
  LIMIT 5
`).all(new Float32Array(embedding));

// 通常のテーブル操作は knex で実行
const insertIds = await knexDb("items").insert({ content, path });

ベストプラクティス:

ベクトル検索（vec_items）: db.prepare() + raw SQL を使用する
通常の CRUD（items）: knex で効率的に実行する
このハイブリッド方式を維持してください

sqlite-vec の制限事項

sqlite-vec は現在 alpha 版 (0.1.7-alpha.2)
本番環境での使用は慎重に検討してください
安定版リリースを待つか、代替ベクトルDB を検討する選択肢もあります