/examples/mcp/crud/README.md

CRUD Contact Book Example

A complete CRUD service with MCP integration — the kind of service you'd actually build in production.

What This Shows

• 6 operations: Create, Get, Update, Delete, List, Search
• Rich documentation: Every handler has doc comments with @example tags
• Struct tag descriptions: All fields have description tags for agents
• Input validation: Required field checks with clear error messages
• Partial updates: Update only changes non-empty fields
• Seed data: Starts with 3 contacts so agents can explore immediately

Run

go run .

Test

# List all MCP tools
curl http://localhost:3001/mcp/tools | jq

# Create a contact
curl -X POST http://localhost:3001/mcp/call \
  -H 'Content-Type: application/json' \
  -d '{"tool": "contacts.Contacts.Create", "arguments": {"name": "Dave", "email": "dave@example.com"}}'

# Search contacts
curl -X POST http://localhost:3001/mcp/call \
  -H 'Content-Type: application/json' \
  -d '{"tool": "contacts.Contacts.Search", "arguments": {"query": "engineer"}}'

Use with Claude Code

micro mcp serve

Then ask: "List all contacts and find the engineers."

Key Patterns

Doc Comments for Agents

// Create adds a new contact to the book. Name and email are required.
//
// @example {"name": "Dave Wilson", "email": "dave@example.com", "role": "Engineer"}
func (h *Contacts) Create(ctx context.Context, req *CreateRequest, rsp *CreateResponse) error {

Struct Tag Descriptions

type Contact struct {
    ID    string `json:"id" description:"Unique contact identifier"`
    Name  string `json:"name" description:"Full name"`
    Email string `json:"email" description:"Email address"`
}

Partial Updates

Only update fields that are provided (non-empty), so agents can change one field without overwriting others:

if req.Name != "" {
    contact.Name = req.Name
}