MCP Sqlew

🚀 sqlew

sqlew 是一個模型上下文協議（MCP）服務器，為 AI 代理提供跨會話的、基於 SQL 的共享上下文存儲庫，避免 AI 每次會話都從零開始，有效解決 AI 編碼中的上下文缺失問題。

🚀 快速開始

安裝

要求

• Node.js 20.0.0 或更高版本
• npm 或 npx

快速安裝

在項目根目錄的 .mcp.json 文件中添加以下內容：

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

建議初始化後重啟 Claude：首次運行時，sqlew 會初始化數據庫、安裝自定義代理和斜槓命令，但此時代理和命令不會加載。因此，請退出 Claude 並再次啟動。

基本使用

你無需手動調用該工具，建議通過提示調用：

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

或者調用專用代理：

/sqw-plan implementation of feature X .

專用代理能更高效地使用 sqlew。

注意：/sqlew 命令取代了之前的多命令系統（/sqw-plan、/sqw-scrum 等）。現在所有功能都可通過統一的 /sqlew 界面使用，且能自動檢測意圖。

高級用法：直接訪問 MCP 工具

高級用戶仍可直接調用 MCP 工具。具體工具如下：

工具	用途	示例用法
decision	記錄選擇和原因	"We chose PostgreSQL"
constraint	定義規則	"DO NOT use raw SQL, use ORM"
task	跟蹤工作	"Implement feature X"
file	跟蹤更改	"Modified auth.ts"
stats	數據庫指標	Get layer summary
suggest	查找相似決策（v3.9.0）	Duplicate detection, pattern search

✨ 主要特性

解決 AI 編碼痛點

現有問題

每個 Claude 會話都從零上下文開始，你必須重新解釋決策，代理可能會重新引入錯誤，且無法跟蹤決策的原因。雖然可以使用 Markdown 文件記錄，但對於大規模項目和長期維護，會產生大量文檔，導致 AI 系統中的上下文腐爛，性能下降。

sqlew 的解決方案

sqlew 通過使用關係數據庫為 AI 構建高效的外部上下文存儲庫：

• 記錄決策背後的推理過程
• 支持查詢過去的上下文
• 通過約束防止反模式
• 通過任務管理消除重複工作

決策與約束存儲庫層

sqlew 最初旨在減少多個 AI 代理之間的重複工作和不一致行為，將上下文集中在共享的 SQL 數據庫中。現代版本的 sqlew 將決策和約束歷史視為一流數據：

• 數據庫架構圍繞決策和約束進行優化，而非通用筆記
• 三層 重複檢測和建議系統 幫助你重用現有的決策/約束，避免創建幾乎相同的內容
• 移除或簡化了舊的、未使用的功能，專注於長期上下文和一致性

核心優勢

🧠 組織記憶

傳統的代碼分析（如 git）告訴你 做了什麼，而 sqlew 在此基礎上增加了 為什麼 和 如何做：

• 決策 → 為什麼進行更改
• 約束 → 應該如何編寫
• 任務 → 需要做什麼

⚡ 令牌效率

在多會話項目中，通過結構化數據存儲和選擇性查詢，減少 60 - 75% 的令牌使用。

🎯 開發工作流程的關鍵優勢

• 🧠 跨會話的上下文持久性：無需重新解釋決策，會話可無縫延續，團隊成員可快速瞭解過去的決策。
• 🛡️ 防止上下文腐爛和不一致：定義架構約束，跟蹤決策演變。
• 🎯 實現一致、高質量的代碼：防止 AI 重新引入已修復的錯誤，確保代碼符合團隊風格，提供上下文感知的建議，記錄決策的原因。
• 📊 透明的 AI 工作跟蹤：瞭解任務依賴關係，自動更新任務狀態，查看 AI 的工作進度。
• ⚡ 效率和可靠性：減少令牌使用，降低上下文腐爛風險，經過實際項目測試。

📦 安裝指南

要求

• Node.js 20.0.0 或更高版本
• npm 或 npx

快速安裝

在項目根目錄的 .mcp.json 文件中添加以下內容：

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

建議初始化後重啟 Claude：首次運行時，sqlew 會初始化數據庫、安裝自定義代理和斜槓命令，但此時代理和命令不會加載。因此，請退出 Claude 並再次啟動。

注意事項

• 不建議全局安裝：因為 sqlew 每個項目需要獨立的設置，每個項目應在 .sqlew/sqlew.db 中維護自己的上下文數據庫。
• 自定義數據庫路徑：可通過添加路徑作為參數："args": ["sqlew", "/path/to/db.db"]
• 默認位置：.sqlew/sqlew.db
• 不支持 Junie AI：Junie AI 在 MCP 服務器配置中不能使用相對路徑，這使其與 sqlew 的基於項目的數據庫模型不兼容。每個項目需要在 .sqlew/sqlew.db 有自己獨立的數據庫，但 Junie AI 的全局 MCP 配置無法處理每個項目的數據庫路徑。

💻 使用示例

基礎用法

你無需手動調用該工具，建議通過提示調用：

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

或者調用專用代理：

/sqw-plan implementation of feature X .

專用代理能更高效地使用 sqlew。

高級用法

/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 工具。

📚 詳細文檔

按需文檔

所有工具支持以下操作：

• action: "help" - 參數參考和描述
• action: "example" - 使用場景和示例
• action: "use_case" - 實際使用示例

針對 AI 代理的文檔

基礎指南

• 工具選擇 - 決策樹，何時使用每個工具
• 工作流程 - 多步驟示例，多代理協調
• 工具參考 - 參數、批量操作、模板
• 最佳實踐 - 常見錯誤、故障排除

任務系統

• 任務概述 - 生命週期、狀態轉換
• 任務操作 - 所有操作及示例
• 任務依賴 - 阻塞關係
• 任務鏈接 - 鏈接到決策/約束/文件
• 任務遷移 - 從基於決策的跟蹤遷移

高級功能

• 決策智能 - 三層重複檢測（v3.9.0）
• 決策上下文 - 豐富的決策文檔
• 自動文件跟蹤 - 零令牌任務管理
• 驗收標準 - 所有檢查類型

參考文檔

• 共享概念 - 層定義、枚舉值
• 配置 - 配置文件設置，所有選項
• 架構 - 技術架構

高級用法文檔

• 配置指南 - TOML 配置文件設置
• CLI 模式概述 - 數據庫遷移、導出/導入命令
• 從源代碼構建 - 設置說明
• 遷移指南 - 版本升級指南

🔧 技術細節

技術特性

• 6 個專用 MCP 工具（決策、任務、文件、約束、統計、建議）
• 智能相似度評分（0 - 100 分算法）
• 運行時重新連接
• 參數驗證
• 元數據驅動的組織

性能指標

• 查詢速度：2 - 50ms
• 併發代理：5 個以上同時運行
• 存儲效率：每個決策約 140 字節
• 令牌節省：典型項目中節省 60 - 75%

數據庫支持

sqlew 支持多種數據庫後端，適用於不同的部署場景：

數據庫	使用場景	狀態
SQLite	個人或小型項目	✅ 默認
MySQL 8.0 / MariaDB 10+	生產環境、共享環境、遠程工作	✅ 支持
PostgreSQL 12+	生產環境、共享環境、遠程工作	✅ 支持

當然，它也適用於 Docker 關係數據庫實例。

配置文件

首次運行時，會創建 .sqlew/config.toml 文件用於持久設置：

SQLite（默認）

[database]
path = ".sqlew/custom.db"

[autodelete]
ignore_weekend = true
message_hours = 48

PostgreSQL

[database]
type = "postgres"

[database.connection]
host = "localhost"
port = 5432
database = "sqlew_db"

[database.auth]
type = "direct"
user = "sqlew_user"
password = "secret"

MySQL/MariaDB

[database]
type = "mysql"

[database.connection]
host = "localhost"
port = 3306
database = "sqlew_db"

[database.auth]
type = "direct"
user = "sqlew_user"
password = "secret"

同時會創建 .sqlew/config.example.toml 文件供參考。

設置優先級：CLI 參數 > config.toml > 數據庫默認值。

CLI 配置（推薦）

配置僅通過 .sqlew/config.toml 文件和 CLI 參數 管理。為簡化起見，已移除 MCP config 工具。

僅使用 CLI 配置的原因

• 無偏差：單一事實來源（配置文件）
• 版本控制：將配置提交到 git，與團隊共享
• 清晰的文檔：配置文件記錄項目要求
• 類型安全：TOML 驗證在啟動時捕獲錯誤

常見 CLI 參數

# 自定義數據庫路徑
npx sqlew /path/to/database.db

# 自動刪除設置
npx sqlew --autodelete-message-hours=48
npx sqlew --autodelete-file-history-days=30
npx sqlew --autodelete-ignore-weekend

# 自定義配置文件
npx sqlew --config-path=.sqlew/custom.toml

對於持久設置，建議編輯 .sqlew/config.toml 文件，而非使用 CLI 參數。

📄 許可證

本軟件採用 AGPLv3 許可證，可免費使用。嵌入或修改時需開源。詳情請見 LICENSE。

鏈接

• npm 包
• GitHub 倉庫
• 模型上下文協議

支持與文檔

• 問題反饋：GitHub Issues
• 文檔：docs/ 目錄

致謝

本項目基於 Model Context Protocol SDK、better-sqlite3 和 TypeScript 構建。

作者：sin5ddd

版本

當前版本：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 目錄

建議參考 docs/DECISION_INTELLIGENCE.md 瞭解建議工具的詳細信息。

⚠️ 重要提示

全局安裝 (npm install -g) 不推薦，因為 sqlew 每個項目需要獨立的設置。每個項目應在 .sqlew/sqlew.db 中維護自己的上下文數據庫。Junie AI 不能使用相對路徑在 MCP 服務器配置中，與 sqlew 的基於項目的數據庫模型不兼容。

💡 使用建議

對於持久設置，建議編輯 .sqlew/config.toml 文件，而非使用 CLI 參數。建議初始化後重啟 Claude，以確保代理和命令正常加載。