/CLAUDE.md

CLAUDE.md - Go Micro Project Guide

Project Overview

Go Micro is a framework for distributed systems development in Go. It provides pluggable abstractions for service discovery, RPC, pub/sub, config, auth, storage, and more.

The framework is evolving into an AI-native platform where every microservice is automatically accessible to AI agents via the Model Context Protocol (MCP).

Build & Test

# Run all tests
make test

# Run tests for a specific package
go test ./gateway/mcp/...
go test ./ai/...
go test ./model/...

# Lint
make lint

# Format
make fmt

# Build CLI
go build -o micro ./cmd/micro

# Run locally with hot reload
micro run

Project Structure

go-micro/
├── agent/          # Agent abstraction (intelligent service management)
├── ai/             # AI model providers (Anthropic, OpenAI, Gemini, etc.)
├── auth/           # Authentication (JWT, no-op)
├── broker/         # Message broker (NATS, RabbitMQ)
├── cache/          # Caching (Redis)
├── client/         # RPC client (gRPC)
├── cmd/micro/      # CLI tool (run, deploy, mcp, build, server)
├── codec/          # Message codecs (JSON, Proto)
├── config/         # Dynamic config (env, file, etcd, NATS)
├── errors/         # Error handling
├── events/         # Event system (NATS JetStream)
├── flow/           # Event-driven LLM orchestration
├── gateway/
│   ├── api/        # REST API gateway
│   └── mcp/        # MCP gateway (core AI integration)
│       └── deploy/ # Helm charts for MCP gateway
├── health/         # Health checking
├── logger/         # Logging
├── metadata/       # Context metadata
├── model/          # Typed data models (CRUD, queries, schemas)
├── registry/       # Service discovery (mDNS, Consul, etcd)
├── selector/       # Client-side load balancing
├── server/         # RPC server
├── service/        # Service interface + profiles
├── store/          # Data persistence (Postgres, NATS KV)
├── transport/      # Network transport
├── wrapper/        # Middleware (auth, trace, metrics)
├── examples/       # Working examples
└── internal/       # Non-public: docs, utils, test harness

Key Architectural Decisions

• Plugin architecture: All abstractions use Go interfaces. Defaults work out of the box, everything is swappable.
• Progressive complexity: Zero-config for development, full control for production.
• AI-native by default: Every service is automatically an MCP tool. No extra code needed.
• In-repo plugins: Plugins live in the main repo to avoid version compatibility issues.
• Reflection-based registration: Handlers are registered via reflection for minimal boilerplate.

Code Conventions

• Standard Go conventions (gofmt, golint)
• Functional options pattern for configuration (WithX() functions)
• Interface-first design: define the interface, then implement
• Tests alongside code (not in separate test directories)
• Commit messages: imperative mood, concise summary line

Current Focus & Priorities (March 2026)

Status

• Q1 2026 (MCP Foundation): COMPLETE
• Q2 2026 (Agent DX): COMPLETE (100%)
• Q3 2026 (Production): 50% complete (ahead of schedule)

Priority 1: Agent Showcase & Examples

Build compelling demos showing agents interacting with go-micro services in realistic scenarios.

Priority 2: Additional Protocol Support

• gRPC reflection-based MCP
• HTTP/3 support

Priority 3: Kubernetes & Deployment

• Helm Charts for MCP gateway
• Kubernetes Operator with CRDs

Recently Completed

• Agent Plan & Delegate - Two built-in agent tools: plan (ordered plan persisted to store-backed memory, surfaced in the prompt) and delegate (hand a subtask to another agent — RPC to a registered agent, else an ephemeral sub-agent with isolated context). Added automatically to every agent; no harness or graph. (agent/builtin.go, examples/agent-plan-delegate/)
• micro new MCP Templates - Scaffolds MCP-enabled services with doc comments, @example tags, WithMCP(). --no-mcp to opt out.
• CRUD Example - Contact book service with 6 operations, rich agent docs (examples/mcp/crud/)
• Migration Guide - "Add MCP to Existing Services" guide with 3 approaches
• Troubleshooting Guide - Common MCP issues and solutions
• Error Handling Guide - Patterns for agent-friendly error responses
• Documentation Guides - Six guides: AI-native services, MCP security, tool descriptions, agent patterns, error handling, troubleshooting
• WithMCP Option - One-line MCP setup (gateway/mcp/option.go)
• Agent Playground Redesign - Chat-focused UI with collapsible tool calls
• Standalone Gateway Binary - micro-mcp-gateway with Docker support
• WebSocket Transport - Bidirectional JSON-RPC 2.0 streaming (gateway/mcp/websocket.go)
• OpenTelemetry Integration - Full span instrumentation with W3C trace context (gateway/mcp/otel.go)
• LlamaIndex SDK - Python package with RAG examples (contrib/go-micro-llamaindex/)

Key Files

Purpose	File
MCP Gateway	gateway/mcp/mcp.go
MCP Docs	gateway/mcp/DOCUMENTATION.md
AI Interface	ai/model.go
Model Layer	model/model.go
CLI Entry	cmd/micro/main.go
MCP CLI	cmd/micro/mcp/
Server (run/server)	cmd/micro/server/server.go
Roadmap	internal/docs/ROADMAP_2026.md
Status	internal/docs/CURRENT_STATUS_SUMMARY.md
Changelog	CHANGELOG.md
Docs Site	internal/website/docs/

Roadmap & Status Documents

• ROADMAP.md - General framework roadmap
• internal/docs/ROADMAP_2026.md - AI-native era roadmap with business model
• internal/docs/CURRENT_STATUS_SUMMARY.md - Quick status overview
• internal/docs/PROJECT_STATUS_2026.md - Detailed technical status
• internal/docs/IMPLEMENTATION_SUMMARY.md - Implementation notes
• CHANGELOG.md - What changed and when

Contributing

See CONTRIBUTING.md for full guidelines. Key points:

• Open an issue before large changes
• Include tests for new features
• Run make test and make lint before submitting
• Follow commit message format: type: description (e.g., feat: add WebSocket transport)