MCP Sqlew

🚀 sqlew

sqlew は、AIエージェントにセッションをまたいで共有のSQLベースのコンテキストリポジトリを提供するModel Context Protocol (MCP)サーバーです。これにより、AIコーディングにおける文脈の欠如や重複作業の問題を解決します。

🚀 クイックスタート

/sqlewコマンドの使用

/sqlew コマンドは、sqlewを使用する最も簡単な方法です！ Claude Codeで自然言語入力とともに /sqlew と入力するだけです。

よく使うケース

# ステータスを表示し、提案を取得
/sqlew

# 決定事項を記録
/sqlew record we use PostgreSQL 15 for production database

# 過去の決定事項を検索
/sqlew search why we chose Knex for migrations

# 残りのタスクを一覧表示
/sqlew show remaining tasks

# 新しい機能を計画（タスクに分割）
/sqlew plan implementing user authentication

/sqlew コマンドは、あなたの意図（検索、記録、一覧表示、実行、タスク作成）を自動的に検出し、適切なMCPツールを呼び出します。

インストールと初期設定

sqlewをインストールし、Claudeを起動してから一度終了し、再度Claudeを起動します。

基本的な使用法

手動で呼び出す必要はありません。プロンプトを介してこのツールを呼び出すことをお勧めします。

read sqlew usecases, and plan implementation of feature X using sqlew.

または、専用エージェントを呼び出すこともできます。

/sqw-plan implementation of feature X .

専用エージェントは、sqlewをより効率的に使用します。

高度な使用法: 直接のMCPツールアクセス

上級ユーザーは、MCPツールを直接呼び出すこともできます。詳細は利用可能なツールセクションを参照してください。

利用可能なツール

✨ 主な機能

AIコーディングの問題解決

AIコーディングでは、各Claudeセッションはゼロコンテキストから始まります。決定事項を再説明する必要があり、エージェントがバグを再導入する可能性があり、決定がなされた理由を追跡する方法がありません。Markdownファイルを使用して記録を保持することも可能ですが、大規模プロジェクトや長期的な保守のために記録を維持すると、膨大な量のドキュメントが生成されます。これは、AIシステムにおけるコンテキストの腐敗を引き起こし、パフォーマンスの低下につながる問題となっています。

sqlewによる解決策

sqlewは、リレーショナルデータベースを使用してAI用の効率的な外部コンテキストリポジトリを構築します。

• 決定の理由を記録します。
• 過去のコンテキストを照会できます。
• 制約によってアンチパターンを防止します。
• タスク管理によって重複作業を排除します。

決定と制約リポジトリレイヤーの概念

sqlewは、複数のAIエージェント間での重複作業と不一致な動作を減らす方法として始まりました。新しいセッションが同じドキュメントを再読み込みし、似たようなコードを再作成する代わりに、sqlewは共有のSQLデータベースにコンテキストを集約します。

最近の大規模言語モデルでは、この共有コンテキストの最も価値のある部分は、決定と制約の履歴であることが判明しています。

• 決定は、変更や設計選択がなされた理由（トレードオフ、棄却されたオプション、根拠）を捕捉します。
• 制約は、物事がどのように行われるべきか（コーディングルール、アーキテクチャの境界、パフォーマンス要件）を捕捉します。

最新バージョンのsqlewは、この決定と制約の履歴を第一級データとして扱います。

• データベーススキーマは、汎用的なメモではなく、決定と制約を中心に最適化されています。
• 三段階の重複検出と提案システムは、ほぼ同一のものを作成する代わりに、既存の決定/制約を再利用するのに役立ちます。
• 古い、未使用の機能は削除または簡素化され、長期的なコンテキストと一貫性に焦点を当てています。

実際には、sqlewはAIツールの決定と制約リポジトリレイヤーとして機能します。エージェントは、以前に決定されたこと、すでに存在するルール、および以前の類似状況がどのように処理されたかを照会できます。

使用する理由

🧠 組織的記憶

gitのような従来のコード分析は、何が行われたかを教えてくれますが、sqlewはそれになぜとどのようにを追加します。

• 決定 → なぜ変更されたのか
• 制約 → どのように書くべきか
• タスク → 何をする必要があるか

⚡ トークン効率

構造化データの保存と選択的な照会により、マルチセッションプロジェクトで60 - 75%のトークン削減が可能です。

🎯 開発ワークフローにおける主要な利点

🧠 セッションをまたいだコンテキストの永続化

• 再説明の不要：AIは数週間前の決定事項を記憶しているため、「なぜPostgreSQLをMongoDBよりも選んだのか」を再説明する必要がありません。
• セッションの継続性：数日または数週間後でも、中断したところから正確に再開できます。
• チームの知識共有：新しいチームメンバー（または新しいAIセッション）は、過去の決定事項をすぐに理解できます。

🛡️ コンテキストの腐敗と不一致の防止

• アーキテクチャの制約：一度ルールを定義すると（「常にasync/awaitを使用し、コールバックを使用しない」）、AIは永遠にそれに従います。
• バージョン履歴：決定がどのように進化したかを追跡できます。何がいつ変更されたかを確認できます。

🎯 一貫した高品質コードの実現

• バグの防止：AIはすでに修正したバグを再導入することはありません（決定事項には「うまくいかなかったこと」が記録されています）。
• パターンの強制：制約により、AIがチームのスタイルに合致したコードを書くことが保証されます。
• コンテキストを考慮した提案：AIは新しい決定を作成する前に関連する決定事項を参照します（「すでにこの問題を解決していることを知っていますか？」）。
• 根拠の文書化：すべての決定には、なぜその決定がなされたのかが記載されており、無思考なプログラミングを防止します。

📊 透明なAI作業の追跡

• タスクの依存関係：AIは、タスクBがタスクAの完了を必要とすることを知っています。
• 自動ファイル監視：AIが追跡対象のファイルを編集すると、タスクが自動的に更新されます（手動での更新は不要）。
• 進捗の可視化：AIが何に取り組んでいるか、何がブロックされているか、何が完了したかを正確に確認できます。

⚡ 効率と信頼性

• 60 - 75%のトークン削減：構造化データは、プロンプトに全体のコンテキストをダンプするよりも優れています。
• コンテキストの腐敗の削減：「このREADMEは50ページあり、AIが半分を無視する」ということはなくなります。
• 本番環境での使用可能：495/495のテストが合格（100%）しており、実際のプロジェクトで十分にテストされています。

📦 インストール

必要条件

• Node.js 20.0.0以上
• npmまたはnpx

クイックインストール

プロジェクトのルートにある .mcp.json に以下の行を追加します。

{
  "mcpServers": {
    "sqlew": {
      "command": "npx",
      "args": ["sqlew"]
    }
  }
}

初期化後にClaudeを再起動することをお勧めします 初回起動時に、sqlewはデータベースを初期化し、カスタムエージェントとスラッシュコマンドをインストールします。ただし、この時点ではエージェントとコマンドは読み込まれません。したがって、Claudeを一度終了し、再度起動してください。 これで準備完了です！

注意事項

⚠️ 重要提示

グローバルインストール (npm install -g) は推奨されません。なぜなら、sqlewはプロジェクトごとに独立した設定が必要だからです。各プロジェクトは、.sqlew/sqlew.db に独自のコンテキストデータベースを保持する必要があります。

カスタムデータベースパス: 引数としてパスを追加します。 "args": ["sqlew", "/path/to/db.db"]

デフォルトの場所: .sqlew/sqlew.db

Junie AIは、MCPサーバーの設定で相対パスを使用できません。このため、sqlewのプロジェクトベースのデータベースモデルと互換性がありません。各プロジェクトは、.sqlew/sqlew.db に独自の分離されたデータベースが必要ですが、Junie AIのグローバルMCP設定では、プロジェクトごとのデータベースパスを処理できません。

📚 ドキュメント

オンデマンドドキュメント

すべてのツールは以下をサポートしています。

• action: "help" - パラメーターの参照と説明
• action: "example" - 使用シナリオと例
• action: "use_case" - 実際の使用例

AIエージェント向け

必須ガイド

• ツール選択 - 決定木、各ツールの使用時期
• ワークフロー - 多段階の例、複数エージェントの協調
• ツールリファレンス - パラメーター、バッチ操作、テンプレート
• ベストプラクティス - 一般的なエラー、トラブルシューティング

タスクシステム

• タスクの概要 - ライフサイクル、ステータス遷移
• タスクアクション - すべてのアクションと例
• タスクの依存関係 - ブロッキング関係
• タスクのリンク - 決定事項/制約/ファイルへのリンク
• タスクの移行 - 決定ベースの追跡からの移行

高度な機能

• 決定インテリジェンス - 三段階の重複検出 (v3.9.0)
• 決定コンテキスト - 詳細な決定事項の文書化
• 自動ファイル追跡 - ゼロトークンのタスク管理
• 受け入れ基準 - すべてのチェックタイプ

リファレンス

• 共有概念 - レイヤー定義、列挙値
• 設定 - 設定ファイルのセットアップ、すべてのオプション

高度な使用法

• 設定ガイド - TOML設定ファイルのセットアップ
• CLIモードの概要 - データベースの移行、エクスポート/インポートコマンド
• ソースからのビルド - セットアップ手順
• 移行ガイド - バージョンアップグレードガイド

利用事例

• 複数エージェントの協調：オーケストレーターがタスクを作成し、エージェントがステータス更新を送信します。
• 破壊的変更の管理：廃止事項を記録し、アーキテクチャの制約を追加します。
• 決定コンテキスト：根拠、検討された代替案、およびトレードオフを文書化します。
• セッションの継続性：セッション1での進捗を保存し、セッション2で再開します。 詳細な多段階の例については、docs/WORKFLOWS.md を参照してください。

パフォーマンス

• クエリ速度：2 - 50ms
• 同時エージェント数：5以上
• ストレージ効率：決定事項1つあたり約140バイト
• トークン節約：典型的なプロジェクトで60 - 75%

サポート

開発をサポートするには、GitHub Sponsors を通じて行ってください。一度の支援または月額のオプションが利用可能です。

バージョン

現在のバージョン: 4.0.2 リリース履歴については、CHANGELOG.md を参照してください。

v4.0.2の新機能

• 統一されたCLIエントリポイント - npx sqlew db:export が直接動作します（npm install は不要）。
• JSONのみによるクロスデータベース移行 - SQLダンプはもはやクロスデータベース変換をサポートしません。
• Node.js 20以上が必要 - 最小バージョン要件が更新されました。

v4.0.0の新機能

• スキーマのリファクタリング - 統一されたv4_テーブル接頭辞、エージェントシステムが完全に削除されました。
• クリーンなスキーマ - 古い列がなく、決定と制約リポジトリに最適化されています。
• 改善された移行システム - v3/v4ディレクトリが再編成されました。 suggestツールの詳細については、docs/DECISION_INTELLIGENCE.md を参照してください。

📄 ライセンス

AGPLv3 - 無料で使用できます。組み込みまたは変更する場合は、オープンソース化が必要です。詳細については、LICENSE を参照してください。

リンク

• npmパッケージ
• GitHubリポジトリ
• Model Context Protocol

サポートとドキュメント

• 問題報告: GitHub Issues
• ドキュメント: docs/ ディレクトリ

謝辞

このソフトウェアは、Model Context Protocol SDK、better-sqlite3、およびTypeScriptを使用して構築されています。

作者: sin5ddd