snippets_cms/MCP_SERVER_GUIDE.md

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:

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

Server → Client Response:

{
  "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!