micro--go-micro
Asim Aslam
e5bf72abd8
Replace the drifted, contradictory roadmap set (two public roadmaps, the AI-native-era business-model doc, stale status snapshots) with one canonical roadmap focused on agentic development and developer experience. - internal/website/docs/roadmap.md — the single source of truth: where we are (v6), the principles (build into what people run; CLI-first; the 0->1 and 0->hero getting-started contract; interaction; battle-tested), and prioritized work (cross-provider conformance + resilience now; durable agent loop, streaming, observability next). - ROADMAP.md — concise, points to the canonical. - roadmap-2026 + the internal ROADMAP_2026/STATUS docs — collapsed to pointers (keeps blog/CLAUDE links alive, removes drift). - CLAUDE.md — references the single roadmap + CHANGELOG for status. Co-authored-by: Claude <noreply@anthropic.com>
147 行
6.3 KiB
Markdown
147 行
6.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 | `ROADMAP.md` (full: `internal/website/docs/roadmap.md`) |
|
|
| Status | `CHANGELOG.md` |
|
|
| Changelog | `CHANGELOG.md` |
|
|
| Docs Site | `internal/website/docs/` |
|
|
|
|
## Roadmap & Status Documents
|
|
|
|
- **[ROADMAP.md](ROADMAP.md)** - the single, current roadmap (agentic development + DX). Full version at `internal/website/docs/roadmap.md`.
|
|
- **[CHANGELOG.md](CHANGELOG.md)** - what shipped and when (the source of truth for status).
|
|
- **[internal/docs/IMPLEMENTATION_SUMMARY.md](internal/docs/IMPLEMENTATION_SUMMARY.md)** - Implementation notes
|
|
- **[CHANGELOG.md](CHANGELOG.md)** - What changed and when
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](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`)
|