Skip to content
mcpgen

Contributing and architecture

Contributions are welcome. Open an issue or a PR on GitHub. The license is MIT.

Architecture overview

Section titled “Architecture overview”
main.go → internal/app.Run(args, stdin, stdout, stderr) int   (semantic exit codes)
│
├── internal/cli       JSON envelope, exit codes, error codes, `mcpgen schema` document
├── internal/config    mcpgen.json v1 model, validation, load/save, schema.json (JSON Schema)
├── internal/ops       core operations (new/add/check/schema) shared by CLI and MCP mode
├── internal/app       subcommand dispatch: new, add, check, schema, version, mcp, interactive TUI
├── internal/generator templates (go:embed), ownership model, .mcpgen/manifest.json, golden tests
├── internal/adder     `add`: marker-region insertion via go/parser + go/ast + go/format
├── internal/checks    `check` staged pipeline (config → … → conformance → inspector)
├── internal/mcpserver `mcpgen mcp` stdio MCP server (dogfoods the go-sdk)
└── internal/scaffold, internal/ui, internal/pkg/utils

Key invariants:

  • CLI and MCP server mode call the same internal/ops functions, so the two interfaces cannot diverge.
  • Generation is deterministic: same mcpgen.json in, same project out. Golden snapshots live in internal/generator/testdata/golden and are regenerated with make golden (UPDATE_GOLDEN=1).
  • The generated/ directory is a checked-in sample project, regenerated with mcpgen new generated ....

Local workflow

Section titled “Local workflow”
Terminal window
make check     # go mod tidy, gofmt -w ., go vet ./..., go test -count=1 -race -v ./...
make golden    # regenerate golden snapshots
make gen       # run the CLI from source: go run .
make docs-gen  # regenerate the docs reference pages (tools/docgen)
make docs-build # build the docs site (docs/)

Before finishing a code change: gofmt -w . and go test ./... must pass; prefer the CI-parity run go test -race -count=1 -v ./.... If you change dependencies, run go mod tidy. See AGENTS.md in the repo root for the full style guide.

Tests

Section titled “Tests”
  • Unit tests per package, table-driven, require for setup and assert for value checks.
  • Golden tests compare generated output byte-for-byte against testdata/golden.
  • internal/app/e2e_test.go runs the real command flows.
  • CI (.github/workflows/ci.yaml) runs the ultimate-go-ci action (lint, modernize, govulncheck, tidy, race tests with coverage), an explicit gofmt gate, a goreleaser dry-run, and a generate-and-verify matrix (stdio-default, http-full, http-latest-only with tasks,skills,oauth, stdio-empty): each permutation is generated into a temp dir and pushed through mcpgen check, including the conformance suite for http, so SDK/spec drift fails CI immediately.

Docs site

Section titled “Docs site”

The docs in docs/ are an Astro Starlight project. Reference pages under docs/src/content/docs/reference/generated/ are generated by tools/docgen from the Go sources (make docs-gen); CI fails if they drift. Content pages are hand-written MDX. Run make docs-dev to preview locally.

Releases

Section titled “Releases”

Tag vX.Y.Z and push. Goreleaser (.goreleaser.yaml) builds binaries for linux/darwin/windows (amd64/arm64, no CGO) and publishes a GitHub release with checksums; the version is stamped via -ldflags -X .../internal/app.Version. Release notes are grouped from conventional commit messages (feat, fix, others). Release binaries are linked from the Releases page; go install github.com/alesr/mcpgen@latest also works.

Next steps

Section titled “Next steps”