# MCP Server for Code Snippets Database

## Overview

Building an MCP (Model Context Protocol) server to create a CRUD interface for managing code snippets. The goal is to enable Claude to save commands/code directly to your snippets database through natural conversation.

## What is an MCP Server?

An MCP server is an executable that communicates with clients (like Claude IDE) by exchanging JSON messages. At its core:

1. **Reads JSON** from stdin (messages from the client)
2. **Writes JSON** to stdout (responses back)
3. Implements the MCP protocol using JSON-RPC 2.0

Official docs: https://modelcontextprotocol.io/docs/concepts/architecture

## Transport Mechanisms

MCP servers support three transport types (choose one):

### 1. **Stdio** (Most Common)
- Server runs as a subprocess
- Client spawns the executable and pipes JSON over stdin/stdout
- Best for: local integrations, Claude IDE plugins

### 2. **HTTP**
- Server runs as an HTTP service (listens on a port)
- Client sends JSON over HTTP requests
- Best for: remote servers, shared services, multiple clients

### 3. **SSE** (Server-Sent Events)
- Used alongside HTTP for server→client streaming
- Less common

For this project, **stdio is the natural choice** — simple implementation and works seamlessly with Claude IDE.

## Protocol Flow

### 1. Initialize Handshake

**Client → Server:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "claude-code",
      "version": "1.0.0"
    }
  }
}
```

**Server → Client Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      },
      "resources": {
        "listChanged": true
      },
      "prompts": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "snippets-server",
      "version": "1.0.0"
    }
  }
}
```

Key points:
- **JSON-RPC 2.0 format**: includes `jsonrpc`, `id`, and `method` fields
- **Server declares capabilities**: tells client what it offers (tools, resources, prompts)
- **Protocol version agreement**: both sides confirm compatibility
- **Server info**: client learns about your server

### 2. Subsequent Calls

After initialization, the client can call methods like:
- `tools/list` - get list of available tools
- `tools/call` - execute a specific tool
- `resources/list` - get available resources
- `resources/read` - read a resource

## Implementation Plan for Snippets Server

Your MCP server should expose CRUD tools:

1. **`create_snippet`** - Save a new snippet (language, description, code)
2. **`list_snippets`** - List all snippets or filter by language/tag
3. **`get_snippet`** - Retrieve a specific snippet by ID
4. **`update_snippet`** - Modify an existing snippet
5. **`delete_snippet`** - Remove a snippet
6. **`search_snippets`** - Search snippets by content or description

Each tool definition includes:
- Name and description
- Input schema (JSON Schema format)
- Output schema

## Getting Started

1. Choose a language (Node.js/Bun, Python, Go, Rust recommended)
2. Create a basic stdio-based server that:
   - Reads from stdin
   - Parses JSON-RPC messages
   - Implements initialize handshake
   - Implements tools/list and tools/call
3. Connect to your snippets database/storage
4. Test by running the server and sending JSON messages

## Useful Resources

- MCP Protocol Spec: https://modelcontextprotocol.io/
- Official example servers: https://github.com/modelcontextprotocol/servers
- JSON-RPC 2.0: https://www.jsonrpc.org/specification

## Use Case Flow

```
User (Claude IDE):
"Save this bash command to my snippets"
    ↓
Claude analyzes and calls:
    tools/call with tool="create_snippet"
    ↓
MCP Server receives JSON-RPC request
    ↓
Server creates snippet in database
    ↓
Returns success response to Claude
    ↓
User sees confirmation and snippet is saved
```

This creates a seamless workflow where your snippet database grows through natural conversation!