Snippets MCP

🚀 Snippets MCP

Snippets MCP 是一個 MCP 服務器，用於存儲、搜索和管理代碼片段。它結合了語義搜索和傳統的關鍵字匹配，讓代碼片段的管理更加高效。你只需告知你的編碼代理（如 claude code、cursor、cline、opencode 等）保存特定的代碼片段，後續有需要時，讓它搜索與 你的查詢 相關的代碼片段即可。

🚀 快速開始

Snippets MCP 提供了便捷的代碼片段管理功能，你可以輕鬆地存儲、搜索和更新代碼片段。

✨ 主要特性

• 語義搜索：利用 AI 嵌入技術，根據代碼含義而非僅關鍵字來查找代碼片段。
• 混合搜索：結合語義相似度和關鍵字匹配的搜索方式。
• 自動語言檢測：自動識別代碼的編程語言。
• 基於標籤的組織和過濾：可通過標籤對代碼片段進行分類和篩選。
• 日期範圍過濾：根據代碼片段的創建日期進行篩選。
• 無需數據庫：基於 JSON 進行存儲。
• 向量嵌入緩存：緩存向量嵌入以實現快速檢索。

📦 安裝指南

使用以下命令安裝 Snippets MCP：

npm install @freakynit/snippets-mcp

💻 使用示例

基礎用法

添加代碼片段（add-snippet）

將新的代碼片段添加到數據庫中。

# 示例命令
npx @freakynit/snippets-mcp add-snippet --code "console.log('Hello, World!')" --tags "javascript, example" --language "javascript" --description "A simple JavaScript example"

搜索代碼片段（search-snippets）

使用混合語義和關鍵字匹配搜索代碼片段。

# 示例命令
npx @freakynit/snippets-mcp search-snippets --query "JavaScript example" --tags "javascript" --language "javascript"

更新代碼片段（update-snippet）

更新現有的代碼片段。如果代碼、標籤或描述發生變化，將重新生成嵌入。

# 示例命令
npx @freakynit/snippets-mcp update-snippet --id "your-snippet-id" --updates '{"code": "console.log(\'Updated!\')", "tags": ["javascript", "updated"]}'

刪除代碼片段（delete-snippet）

從數據庫中刪除代碼片段。

# 示例命令
npx @freakynit/snippets-mcp delete-snippet --id "your-snippet-id"

獲取代碼片段（get-snippet）

通過 ID 檢索單個代碼片段。

# 示例命令
npx @freakynit/snippets-mcp get-snippet --id "your-snippet-id"

高級用法

根據不同的參數組合，可以實現更復雜的搜索和管理操作。例如，結合日期範圍和標籤進行更精確的篩選：

# 示例命令：搜索特定日期範圍內的 JavaScript 代碼片段
npx @freakynit/snippets-mcp search-snippets --query "JavaScript function" --tags "javascript" --language "javascript" --dateStart "2024-01-01T00:00:00Z" --dateEnd "2024-12-31T23:59:59Z"

📚 詳細文檔

可用工具說明

add-snippet

將新的代碼片段添加到數據庫中。 參數說明：

search-snippets

使用混合語義和關鍵字匹配搜索代碼片段。 參數說明：

update-snippet

更新現有的代碼片段。如果代碼、標籤或描述發生變化，將重新生成嵌入。 參數說明：

delete-snippet

從數據庫中刪除代碼片段。 參數說明：

get-snippet

通過 ID 檢索單個代碼片段。 參數說明：

環境變量

• SNIPPETS_FILE_PATH：可選，保存代碼片段和嵌入的文件的完整路徑。默認值為 ~/.snippets-mcp-db.json。

工作原理

該庫採用混合搜索方法：

1. 語義搜索（70%權重）：使用 all-MiniLM-L6-v2 模型對代碼、描述、標籤和語言生成的嵌入進行向量搜索。
2. 關鍵字匹配（30%權重）：基於代碼和標籤進行傳統的文本匹配，以查找精確的術語匹配。
3. 硬過濾：首先應用，通過標籤、語言和日期範圍縮小搜索結果。

嵌入在添加/更新代碼片段時生成一次，並進行緩存以實現快速檢索。

存儲方式

代碼片段存儲在由環境變量 SNIPPETS_FILE_PATH 指定的 JSON 文件中，若未指定則使用默認路徑：~/.snippets-mcp-db.json，其結構如下：

{
  "id": "uuid",
  "code": "string",
  "language": "string",
  "tags": ["array"],
  "description": "string",
  "embedding": [/* 向量數組 */],
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

使用 mcpServers json 進行配置

對於 Mac 和 Linux

{
  "mcpServers": {
    "snippets-mcp": {
      "command": "npx",
      "args": ["-y", "@freakynit/snippets-mcp@latest"],
      "env": {
        "SNIPPETS_FILE_PATH": "可選... 保存代碼片段和嵌入的路徑，應具有 .json 擴展名"
      }
    }
  }
}

對於 Windows

{
  "mcpServers": {
    "snippets-mcp": {
      "command": "cmd",
      "args": ["/k", "npx", "-y", "@freakynit/snippets-mcp@latest"],
      "env": {
        "SNIPPETS_FILE_PATH": "可選... 保存代碼片段和嵌入的路徑，應具有 .json 擴展名"
      }
    }
  }
}

📄 許可證

本項目採用 MIT 許可證。