{"owner":"micro","repo":"go-micro","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"files":{"CLAUDE.md":"# CLAUDE.md - Go Micro Project Guide\n\n## Project Overview\n\nGo 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.\n\nThe framework is evolving into an **AI-native platform** where every microservice is automatically accessible to AI agents via the Model Context Protocol (MCP).\n\n## Build & Test\n\n```bash\n# Run all tests\nmake test\n\n# Run tests for a specific package\ngo test ./gateway/mcp/...\ngo test ./ai/...\ngo test ./model/...\n\n# Lint\nmake lint\n\n# Format\nmake fmt\n\n# Build CLI\ngo build -o micro ./cmd/micro\n\n# Run locally with hot reload\nmicro run\n```\n\n## Project Structure\n\n```\ngo-micro/\n├── agent/          # Agent abstraction (intelligent service management)\n├── ai/             # AI model providers (Anthropic, OpenAI, Gemini, etc.)\n├── auth/           # Authentication (JWT, no-op)\n├── broker/         # Message broker (NATS, RabbitMQ)\n├── cache/          # Caching (Redis)\n├── client/         # RPC client (gRPC)\n├── cmd/micro/      # CLI tool (run, deploy, mcp, build, server)\n├── codec/          # Message codecs (JSON, Proto)\n├── config/         # Dynamic config (env, file, etcd, NATS)\n├── errors/         # Error handling\n├── events/         # Event system (NATS JetStream)\n├── flow/           # Event-driven LLM orchestration\n├── gateway/\n│   ├── api/        # REST API gateway\n│   └── mcp/        # MCP gateway (core AI integration)\n│       └── deploy/ # Helm charts for MCP gateway\n├── health/         # Health checking\n├── logger/         # Logging\n├── metadata/       # Context metadata\n├── model/          # Typed data models (CRUD, queries, schemas)\n├── registry/       # Service discovery (mDNS, Consul, etcd)\n├── selector/       # Client-side load balancing\n├── server/         # RPC server\n├── service/        # Service interface + profiles\n├── store/          # Data persistence (Postgres, NATS KV)\n├── transport/      # Network transport\n├── wrapper/        # Middleware (auth, trace, metrics)\n├── examples/       # Working examples\n└── internal/       # Non-public: docs, utils, test harness\n```\n\n## Key Architectural Decisions\n\n- **Plugin architecture**: All abstractions use Go interfaces. Defaults work out of the box, everything is swappable.\n- **Progressive complexity**: Zero-config for development, full control for production.\n- **AI-native by default**: Every service is automatically an MCP tool. No extra code needed.\n- **In-repo plugins**: Plugins live in the main repo to avoid version compatibility issues.\n- **Reflection-based registration**: Handlers are registered via reflection for minimal boilerplate.\n\n## Code Conventions\n\n- Standard Go conventions (gofmt, golint)\n- Functional options pattern for configuration (`WithX()` functions)\n- Interface-first design: define the interface, then implement\n- Tests alongside code (not in separate test directories)\n- Commit messages: imperative mood, concise summary line\n\n## Current Focus & Priorities (March 2026)\n\n### Status\n- **Q1 2026 (MCP Foundation):** COMPLETE\n- **Q2 2026 (Agent DX):** COMPLETE (100%)\n- **Q3 2026 (Production):** 50% complete (ahead of schedule)\n\n### Priority 1: Agent Showcase & Examples\nBuild compelling demos showing agents interacting with go-micro services in realistic scenarios.\n\n### Priority 2: Additional Protocol Support\n- gRPC reflection-based MCP\n- HTTP/3 support\n\n### Priority 3: Kubernetes & Deployment\n- Helm Charts for MCP gateway\n- Kubernetes Operator with CRDs\n\n### Recently Completed\n- **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/`)\n- **`micro new` MCP Templates** - Scaffolds MCP-enabled services with doc comments, `@example` tags, `WithMCP()`. `--no-mcp` to opt out.\n- **CRUD Example** - Contact book service with 6 operations, rich agent docs (`examples/mcp/crud/`)\n- **Migration Guide** - \"Add MCP to Existing Services\" guide with 3 approaches\n- **Troubleshooting Guide** - Common MCP issues and solutions\n- **Error Handling Guide** - Patterns for agent-friendly error responses\n- **Documentation Guides** - Six guides: AI-native services, MCP security, tool descriptions, agent patterns, error handling, troubleshooting\n- **WithMCP Option** - One-line MCP setup (`gateway/mcp/option.go`)\n- **Agent Playground Redesign** - Chat-focused UI with collapsible tool calls\n- **Gateway command** - `micro gateway` (formerly `micro server`) runs the HTTP API, dashboard, auth, and — with `--mcp-address` — the MCP gateway with production controls (rate limit, scopes, auth, audit, circuit breaker, x402). Deployed via the micro CLI image; the standalone `micro-mcp-gateway` binary was folded into it.\n- **WebSocket Transport** - Bidirectional JSON-RPC 2.0 streaming (`gateway/mcp/websocket.go`)\n- **OpenTelemetry Integration** - Full span instrumentation with W3C trace context (`gateway/mcp/otel.go`)\n- **LlamaIndex SDK** - Python package with RAG examples (`contrib/go-micro-llamaindex/`)\n\n## Key Files\n\n| Purpose | File |\n|---------|------|\n| MCP Gateway | `gateway/mcp/mcp.go` |\n| MCP Docs | `gateway/mcp/DOCUMENTATION.md` |\n| AI Interface | `ai/model.go` |\n| Model Layer | `model/model.go` |\n| CLI Entry | `cmd/micro/main.go` |\n| MCP CLI | `cmd/micro/mcp/` |\n| Server (run/server) | `cmd/micro/server/server.go` |\n| Roadmap | `ROADMAP.md` (full: `internal/website/docs/roadmap.md`) |\n| Status | `CHANGELOG.md` |\n| Changelog | `CHANGELOG.md` |\n| Docs Site | `internal/website/docs/` |\n\n## Roadmap & Status Documents\n\n- **[ROADMAP.md](ROADMAP.md)** - the single, current roadmap (agentic development + DX). Full version at `internal/website/docs/roadmap.md`.\n- **[CHANGELOG.md](CHANGELOG.md)** - what shipped and when (the source of truth for status).\n- **[internal/docs/IMPLEMENTATION_SUMMARY.md](internal/docs/IMPLEMENTATION_SUMMARY.md)** - Implementation notes\n- **[CHANGELOG.md](CHANGELOG.md)** - What changed and when\n\n## Coordination with Codex\n\nGo Micro is maintained by two AI tools — **Claude Code** (you) and **Codex** (its playbook is [CODEX.md](CODEX.md)) — plus the human maintainer, who routes work and owns every merge. To work side by side without collisions:\n\n- **Lanes / branches.** You work on `claude/*` branches; Codex on `codex/*`. Never push to Codex's branch, and never have both agents committing the same branch at once.\n- **Base PRs on `master`; don't stack on Codex's in-flight branch.** If that base squash-merges, your commit gets orphaned (this happened — the #3007 fixes had to be re-landed). If the code you need isn't merged yet, wait for it, then branch off `master`. To improve an *open* Codex PR, fix it in place (once Codex is done with the branch, or via an `@codex` comment on the PR) rather than a separate stacked PR.\n- **One concern per PR.** Single-purpose PRs; don't bundle (e.g.) a feature with a docs change.\n- **Cross-review.** Review Codex's PRs before merge — mechanical fixes you can land yourself (based on `master`), but design/scope/positioning calls go to the human; don't silently rewrite Codex's intent. Codex reviews yours via `@codex review`.\n- **Dispatching Codex.** Start a task by commenting `@codex <instruction>` on an issue/PR (that issue/PR is its context). `@codex review` is reserved for review; any other instruction starts a *task*. It's consequential (spends a Codex task slot, pushes commits) and **serial** (one task at a time) — so dispatch one task at a time, only on the human's go-ahead, and never write a literal `@codex` in a comment unless you intend to trigger it (write \"Codex\" in prose otherwise).\n- **CI is the gate.** `go build`, `go test`, `golangci-lint` (blocking), and `make harness` must pass before merge. `internal/harness/` and `examples/` are excluded from errcheck; everything else gets the full set.\n- **Backlog = GitHub issues**, each a scoped, self-contained brief with acceptance criteria.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. Key points:\n- Open an issue before large changes\n- Include tests for new features\n- Run `make test` and `make lint` before submitting\n- Follow commit message format: `type: description` (e.g., `feat: add WebSocket transport`)\n","AGENTS.md":"# Repository agent instructions\n\nThese instructions apply to the entire repository.\n\n## Pull requests from Codex tasks\n\nWhen a Codex task makes repository changes and the requested outcome is a PR:\n\n1. Keep the change focused on the assigned issue or prompt.\n2. Run the relevant verification commands and capture their results\n   (`go build ./...`, `go test ./...`, `golangci-lint run ./...`).\n3. Check `git status --short` and review the diff before finishing.\n4. Create a uniquely-named branch under the `codex/` prefix (do not work on\n   `master`, and do not use a generic name like `work`):\n\n   ```sh\n   git switch -c codex/<issue-number>-<short-slug>\n   ```\n5. Stage the intended files and commit on that branch.\n6. Open the pull request yourself with the GitHub CLI, which is installed in the\n   environment and whose `origin` points at this repository, then enable\n   auto-merge so GitHub merges it once the required CI checks pass:\n\n   ```sh\n   git push -u origin HEAD\n   gh pr create --base master --label codex \\\n     --title \"<concise title>\" \\\n     --body \"<summary of the change and testing, including 'Closes #<issue>'>\"\n   gh pr merge --squash --auto --delete-branch\n   ```\n\nThe branch should start with `codex/` and the PR should carry the `codex`\nlabel. Auto-merge waits for the required status checks (build, tests,\ngolangci-lint) — never merge a PR manually before CI is green.\n\nDo not just say that a PR was opened, and do **not** rely on the `make_pr` tool:\nin this environment `make_pr` only records the title/body and never pushes a\nbranch or creates a PR. The task is not complete until `gh pr create` has opened\na real pull request and printed its URL.\n"}}