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 工具。具體工具如下：

✨ 主要特性

解決 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 支持多種數據庫後端，適用於不同的部署場景：

當然，它也適用於 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，以確保代理和命令正常加載。