init MCP server

2026-02-28 19:47:00 +01:00 · 2026-02-28 19:47:00 +01:00 · 8ea0eee299
commit 8ea0eee299
parent fff03fa0d5
11 changed files with 253 additions and 21 deletions
--- a/MCP_SERVER_GUIDE.md
+++ b/MCP_SERVER_GUIDE.md
@ -0,0 +1,149 @@
+# 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!