149 lines
4 KiB
Markdown
149 lines
4 KiB
Markdown
# 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!
|