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 许可证。