micro--go-micro
Asim Aslam
870b540922
* docs: add MCP migration guide and troubleshooting guide - Migration guide: 3 approaches to add MCP to existing services (WithMCP one-liner, standalone gateway, CLI) - Troubleshooting guide: common issues with agents, WebSocket, Claude Code, auth, rate limiting, and performance https://claude.ai/code/session_01GkduEhcrqcG45rdfYh8dAc * feat: add CRUD example, error handling guide, and status updates - CRUD contact book example (examples/mcp/crud/) with 6 operations, rich doc comments, @example tags, and description struct tags - Error handling guide for writing agent-friendly error responses using typed errors, actionable messages, and idempotency patterns - Updated MCP examples index, CLAUDE.md, and status summary https://claude.ai/code/session_01GkduEhcrqcG45rdfYh8dAc --------- Co-authored-by: Claude <noreply@anthropic.com>
75 行
1.9 KiB
Markdown
75 行
1.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
go run .
|
|
```
|
|
|
|
## Test
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
micro mcp serve
|
|
```
|
|
|
|
Then ask: "List all contacts and find the engineers."
|
|
|
|
## Key Patterns
|
|
|
|
### Doc Comments for Agents
|
|
|
|
```go
|
|
// 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
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
if req.Name != "" {
|
|
contact.Name = req.Name
|
|
}
|
|
```
|