Snippets MCP

🚀 Snippets MCP

A MCP server for storing, searching, and managing code snippets, leveraging semantic search and traditional keyword matching.

This server allows you to easily save code snippets via your coding agent (such as claude code, cursor, cline, opencode, etc.). When you need to find relevant snippets, simply provide a query, and it will quickly locate the appropriate code for you.

🚀 Quick Start

Just tell your coding agent (claude code, cursor, cline, opencode, etc.) to save a certain snippet. When needed, just tell it to search for code snippets related to: your query.

✨ Features

• Semantic Search: Utilize AI embeddings to find snippets by meaning, not just keywords.
• Hybrid Search: Combine semantic similarity and keyword matching for more accurate results.
• Automatic Language Detection: Automatically identify the programming language of the code snippet.
• Tag-based Organization: Organize and filter snippets using tags.
• Date Range Filtering: Filter snippets based on their creation date.
• JSON-based Storage: No need for a database; store snippets in a JSON file.
• Vector Embedding Caching: Cache vector embeddings for fast retrieval.

📦 Installation

npm install @freakynit/snippets-mcp

💻 Usage Examples

Basic Usage

Here are the basic operations of using this library:

add-snippet

Adds a new code snippet to the database.

# Example of adding a snippet
npx @freakynit/snippets-mcp add-snippet --code "console.log('Hello, World!')" --tags ["example"] --language "javascript" --description "A simple hello world example"

search-snippets

Searches snippets using hybrid semantic and keyword matching.

# Example of searching snippets
npx @freakynit/snippets-mcp search-snippets --query "hello world"

Advanced Usage

update-snippet

Updates an existing snippet. Re-generates embeddings if code, tags, or description change.

# Example of updating a snippet
npx @freakynit/snippets-mcp update-snippet --id "your-snippet-id" --updates '{"code": "console.log(\'Updated Hello, World!\')"}'

delete-snippet

Deletes a snippet from the database.

# Example of deleting a snippet
npx @freakynit/snippets-mcp delete-snippet --id "your-snippet-id"

get-snippet

Retrieves a single snippet by ID.

# Example of getting a snippet
npx @freakynit/snippets-mcp get-snippet --id "your-snippet-id"

📚 Documentation

Available Tools

add-snippet

Adds a new code snippet to the database.

Parameters:

search-snippets

Searches snippets using hybrid semantic and keyword matching.

Parameters:

update-snippet

Updates an existing snippet. Re-generates embeddings if code, tags, or description change.

Parameters:

delete-snippet

Deletes a snippet from the database.

Parameters:

get-snippet

Retrieves a single snippet by ID.

Parameters:

Environment Variables

How It Works

The library uses a hybrid search approach:

1. Semantic Search (70% weight): Uses the all-MiniLM-L6-v2 model to perform vector search against embeddings generated off code, description, tags, and language.
2. Keyword Matching (30% weight): Traditional text matching for exact term matches based on code and tags.
3. Hard Filters: Applied first to narrow results by tags, language, and date range.

Embeddings are generated once when adding/updating snippets and cached for fast retrieval.

Storage

Snippets are stored in a JSON file specified by environment variable SNIPPETS_FILE_PATH, or at default path: ~/.snippets-mcp-db.json with the following structure:

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

Configuring using mcpServers json

For Mac and Linux

{
  "mcpServers": {
    "snippets-mcp": {
      "command": "npx",
      "args": ["-y", "@freakynit/snippets-mcp@latest"],
      "env": {
        "SNIPPETS_FILE_PATH": "Optional... path to save snippets and embeddings in.. should have .json extension"
      }
    }
  }
}

For Windows

{
  "mcpServers": {
    "snippets-mcp": {
      "command": "cmd",
      "args": ["/k", "npx", "-y", "@freakynit/snippets-mcp@latest"],
      "env": {
        "SNIPPETS_FILE_PATH": "Optional... path to save snippets and embeddings in.. should have .json extension"
      }
    }
  }
}

📄 License

MIT