diff --git a/README.md b/README.md index d0f9044..8ad1b78 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🦀 SQLite Vector MCP Server (Tauri 2 Edition) -> **究極のパフォーマンスとポータビリティを追求した、ローカル完結型ベクトル検索基盤** +> **SQLite と Rust で構築された、ローカル向けベクトル検索サーバー** [![Tauri 2](https://img.shields.io/badge/Tauri-2.0-blue?style=for-the-badge&logo=tauri)](https://tauri.app/) [![Rust](https://img.shields.io/badge/Rust-LATEST-orange?style=for-the-badge&logo=rust)](https://www.rust-lang.org/) @@ -8,147 +8,130 @@ ## 📝 イントロダクション -このプロジェクトは、Model Context Protocol (MCP) に準拠した、高性能なベクトル検索サーバーです。かつて Electron + Bun で構成されていた基盤を、**Tauri 2 + Rust** へと完全にフルスクラッチで移植しました。 +Model Context Protocol (MCP) に準拠した、ローカル実行用のベクトル検索サーバーです。以前の設計から Tauri v2 および Rust をベースにした構成に整理しました。 -単なる移植に留まらず、**Gemma 3 300M Embedding** モデルのフルサポートと、`llama-server` の **Sidecar 自動管理機能**を標準装備。これにより、外部サーバーや複雑な環境構築に頼ることなく、ダブルクリック一つで高度なセマンティック検索環境があなたのローカルマシン上で完結します。 +Gemma 3 300M Embedding モデルや `llama-server` をサイドカー(外部プロセス)として利用することで、外部ネットワークに依存せず、ローカル環境のみでテキストのベクトル化と検索を行うことができます。 --- -## ✨ 主要な特徴と技術的優位性 +## ✨ 主な機能 -### 1. 🚀 超軽量・高反応な常駐型デザイン +### 1. 常駐型バックエンド -バックエンドを Rust で構築したことで、Electron 時代と比較してメモリ使用量を劇的に削減しました。システムトレイにスマートに常駐し、バックグラウンドで静かに、かつ確実に MCP リクエストに応答します。 +Rust で実装されており、システムトレイに常駐して MCP プロトコルのリクエストに応答します。 -### 2. 🔍 プロ格のベクトル検索性能 +### 2. SQLite によるベクトル検索 -`sqlite-vec` 拡張を Rust から直接制御。SQLite の堅牢なリレーショナル機能と、高速な近傍検索(`MATCH` 演算子)を融合させました。 +`sqlite-vec` 拡張を利用しており、SQLite 上で効率的なベクトル検索を行うことができます。 -### 3. 🤖 Sidecar 統合による「ゼロ設定」LLM +### 3. サイドカープロセスの管理 -`llama-server` をアプリケーションに内蔵(Sidecar)。アプリの起動と共に、最適化された Embedding 生成エンジンが自動的にスピンアップします。 +`llama-server` を外部プロセスとして管理し、アプリケーションの起動に合わせて自動的に Embedding エンジンを準備します。 -### 4. 🛠️ 型安全なデータ管理 (SeaORM & SQLite) +### 4. データベース管理 -Rust の強力な型システムと **SeaORM** を採用。リレーショナルデータとベクトルデータの不整合を排除し、`created_at` / `updated_at` の自動更新トリガーなど、運用面での信頼性も追求しています。 +SeaORM を利用し、メタデータや更新日時の管理を自動化しています。 -### 5. 📅 万全のロギングと運用性 +### 5. ロギング -`tauri-plugin-log` による詳細なログ記録に加え、10MB×5世代の自動ローテーションを実装。デバッグ時にはプロジェクトルート、本番環境では OS 標準のログフォルダへと適切に振り分けます。 +動作ログを適切に記録し、一定のサイズに達すると自動でローテーションを行います。 --- ## 📁 ディレクトリ構成 -プロジェクトは、論理的な役割に基づいて以下のように「合理的」に整理されています。 +プロジェクトの役割に応じて、以下のようにディレクトリを整理しています。 ```text . -├── bin/ # 🚀 サイドカーバイナリ (llama-server等) -├── data/ # 🗄️ データベースファイル (vector.db) -├── document/ # 📚 技術詳細ドキュメント -├── journals/ # 開発の軌跡(非公開) -├── logs/ # 📝 実行ログ (開発時) -├── resources/ # 🎨 静的アセット (icons等) -├── scripts/ # 🏗️ セットアップ・自動化スクリプト +├── bin/ # 外部バイナリ (llama-server等) +├── data/ # データベースファイル (vector.db) +├── document/ # 仕様・設計ドキュメント +├── journals/ # 開発記録 +├── logs/ # 開発用ログ +├── resources/ # アイコン等のアセット +├── scripts/ # 各種ユーティリティ ├── src/ -│ ├── backend/ # 🦀 Tauri / Rust (Core Source Only) -│ └── frontend/ # ⚛️ Webview UI (React) -├── target/ # 🏗️ ビルド成果物 (一括集約) -└── test/ # 🧪 E2E / 統合テスト +│ ├── backend/ # Rust / Tauri バックエンド +│ └── frontend/ # Webview 用 UI +├── target/ # ビルド成果物 +└── test/ # テストコード ``` --- -## 🏗️ システムアーキテクチャ - -本システムは、高い分離性と連携性を両立した 3 レイヤー構造を採用しています。 +## 🏗️ システム構造 ```mermaid graph TD - subgraph "Frontend Layer (WebView2)" - UI["User Interface (React/JS)"] + subgraph "Frontend" + UI["UI (JS)"] end - subgraph "Tauri Backend Layer (Rust / v2)" - Tray["System Tray Manager"] - Axum["MCP SSE Server (Axum)"] - SeaORM["ORM Logic (SeaORM)"] - LlamaClient["Llama API Client"] - SidecarMgr["Sidecar Process Manager"] + subgraph "Backend (Rust)" + Axum["MCP Server"] + SeaORM["DB Access"] + Sidecar["Sidecar Manager"] end - subgraph "Sidecar Layer (Local Process)" - llama["llama-server.exe"] - Model["Gemma 3 300M GGUF"] + subgraph "External" + LS["llama-server"] + DB["SQLite"] end - subgraph "Persistence Layer" - DB[("SQLite + sqlite-vec")] - end - - UI <-->|Tauri Commands| Tray + UI <--> Axum Axum <--> SeaORM SeaORM <--> DB - LlamaClient <-->|HTTP/JSON| llama - SidecarMgr -->|Spawn/Lifecycle| llama - llama -->|Memory Mapped| Model - SidecarMgr -.->|DLL Path Solution| llama + Sidecar --> LS ``` --- ## 🚀 クイックスタート -### プリリクエスト - ### 1. セットアップ -プロジェクトの実行に必要なアセットを一括で準備します。 +依存関係のインストールとバイナリのダウンロードを行います。 ```bash bun install bun setup ``` -**`bun setup` が行うこと:** +**`bun setup` の実行内容:** -- **サイドカーの準備**: `llama-server` バイナリと依存 DLL を `bin/` フォルダへダウンロード。 -- **モデルの準備**: ベクトル生成用の Gemma 3 300M モデル (`.gguf`) を `models/` フォルダへダウンロード。 +- `bin/`: `llama-server` と依存 DLL をダウンロード +- `models/`: ベクトル生成用モデルをダウンロード -### 2. 開発起動 +### 2. 実行 ```bash bun dev ``` -または、プロジェクトルートの `launch.cmd` をダブルクリックするだけでも起動可能です。 -起動後、システムトレイに 🦀 アイコンが表示されます。 +または、`launch.cmd` を実行しても起動できます。 --- -## 🛠️ MCP ツール仕様 +## 🛠️ MCP ツール -本サーバーは以下のツールを外部エージェント(Claude Desktop 等)に提供します。 - -| ツール名 | 説明 | 主要引数 | -| :--- | :--- | :--- | -| `add_item_text` | 文書を追加(自動ベクトル化) | `content`, `path` | -| `search_text` | 自然言語による類似文書検索 | `content`, `limit` | -| `add_item` | ベクトルを指定して文書追加 | `content`, `vector`, `path` | -| `search_vector` | 純粋なベクトル検索 | `vector`, `limit` | -| `llm_generate` | 内蔵 LLM によるテキスト生成 | `prompt`, `n_predict` | +| ツール名 | 用途 | +| :--- | :--- | +| `add_item_text` | 文書の追加とベクトル化 | +| `search_text` | 文書の類似検索 | +| `add_item` | ベクトル指定での追加 | +| `search_vector` | ベクトル検索 | +| `llm_generate` | テキスト生成 | --- -## 📘 詳細ドキュメント +## 📘 詳細情報 -より深い情報を知りたい場合は、以下のドキュメントを参照してください。 +詳細は `document/` 配下のファイルを参照してください。 -- [📖 アーキテクチャ詳細](document/architecture.md): 内部モジュールと役割の解説 -- [⚙️ Sidecar 統合の仕組み](document/sidecar_integration.md): Windows におけるパス解決と DLL 管理 -- [🗄️ データベース設計](document/database.md): Schema 構成と `sqlite-vec` の動作 -- [💻 開発ガイド](document/development_guide.md): 新機能の追加とテスト手順 +- [アーキテクチャ](document/architecture.md) +- [セットアップ詳細](document/sidecar_integration.md) +- [データベース設計](document/database.md) ---