feat(mcp): add MCP module

[flemzord]

Summary

• add the new MCP stack module backed by ghcr.io/formancehq/stack-mcp
• deploy the formance-mcp service with required env vars, probes, resources, OTEL wiring, and public stack URL/auth issuer config
• expose MCP public Gateway routes at /mcp, /.well-known/oauth-protected-resource, and /_healthcheck
• generate CRDs/RBAC/Helm/docs/client code and add MCP samples
• add envtest coverage and a Chainsaw e2e scenario for MCP routing/configuration

Validation

• make generate
• make manifests
• just helm-update
• just generate-docs
• just helm-validate
• KUBEBUILDER_ASSETS=$(pwd)/$(bin/setup-envtest use 1.32.0 --bin-dir bin -p path -i) go test ./...
• ./bin/chainsaw lint test --file tests/e2e/chainsaw/25-mcp-module/chainsaw-test.yaml

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1898b4e3-ffd1-437d-9b46-c0bd5f6e6fe8

📥 Commits

Reviewing files that changed from the base of the PR and between de735dc and 7e0efbb.

⛔ Files ignored due to path filters (16)

• config/crd/bases/formance.com_gatewayhttpapis.yaml is excluded by !**/*.yaml
• config/crd/bases/formance.com_mcps.yaml is excluded by !**/*.yaml
• config/crd/kustomization.yaml is excluded by !**/*.yaml
• config/rbac/role.yaml is excluded by !**/*.yaml
• config/samples/formance.com_v1beta1_mcp.yaml is excluded by !**/*.yaml
• config/samples/kustomization.yaml is excluded by !**/*.yaml
• helm/crds/templates/crds/apiextensions.k8s.io_v1_customresourcedefinition_gatewayhttpapis.formance.com.yaml is excluded by !**/*.yaml
• helm/crds/templates/crds/apiextensions.k8s.io_v1_customresourcedefinition_mcps.formance.com.yaml is excluded by !**/*.yaml
• helm/operator/templates/gen/rbac.authorization.k8s.io_v1_clusterrole_formance-manager-role.yaml is excluded by !**/gen/**, !**/*.yaml, !**/gen/**
• pkg/client/formance.com/v1beta1/client.go is excluded by !pkg/client/**
• pkg/client/formance.com/v1beta1/mcp.go is excluded by !pkg/client/**
• tests/e2e/chainsaw/25-mcp-module/chainsaw-test.yaml is excluded by !**/*.yaml
• tests/e2e/chainsaw/25-mcp-module/resources/gateway.yaml is excluded by !**/*.yaml
• tests/e2e/chainsaw/25-mcp-module/resources/mcp.yaml is excluded by !**/*.yaml
• tests/e2e/chainsaw/25-mcp-module/resources/settings.yaml is excluded by !**/*.yaml
• tests/e2e/chainsaw/25-mcp-module/resources/stack.yaml is excluded by !**/*.yaml

📒 Files selected for processing (12)

• PROJECT
• api/formance.com/v1beta1/gatewayhttpapi_types.go
• api/formance.com/v1beta1/mcp_types.go
• api/formance.com/v1beta1/zz_generated.deepcopy.go
• docs/04-Modules/11-MCP.md
• docs/09-Configuration reference/02-Custom Resource Definitions.md
• internal/resources/all.go
• internal/resources/gatewayhttpapis/create.go
• internal/resources/gateways/Caddyfile.gotpl
• internal/resources/mcps/deployment.go
• internal/resources/mcps/init.go
• internal/tests/mcp_controller_test.go

---

Walkthrough

This PR introduces a new MCP (Model Context Protocol) module to the Kubebuilder operator. The implementation adds MCP custom resource types with full Kubernetes integration, extends the gateway to support public API routes, and implements reconciliation logic to deploy and manage the MCP service with appropriate configuration.

Changes

MCP Module Integration

Layer / File(s)	Summary
MCP API type contract and registration PROJECT, api/formance.com/v1beta1/mcp_types.go, api/formance.com/v1beta1/zz_generated.deepcopy.go	Defines MCPSpec, MCPStatus, MCP, and MCPList types with kubebuilder markers, readiness/status helper methods, and scheme registration. Registers MCP resource in Kubebuilder project configuration and generates deepcopy methods for Kubernetes API compliance.
Gateway public route support api/formance.com/v1beta1/gatewayhttpapi_types.go, internal/resources/gatewayhttpapis/create.go, internal/resources/gateways/Caddyfile.gotpl	Adds optional Public boolean field to GatewayHTTPAPIRule to expose routes at the gateway root instead of under /api/<service>. Caddyfile template conditionally renders public routes without the /api prefix. Introduces WithName helper function for gateway HTTP API configuration.
MCP reconciliation logic internal/resources/mcps/init.go, internal/resources/mcps/deployment.go	Implements MCP reconciler that creates gateway HTTP API rules for public endpoints (POST /mcp, GET /.well-known/oauth-protected-resource, GET /_healthcheck), resolves image configuration from registries, and deploys the MCP service with environment variables, AWS service account integration, and fixed resource constraints.
Resource aggregation and wiring internal/resources/all.go	Registers the mcps package to ensure MCP reconciliation is included when the resource aggregator is imported.
Module documentation docs/04-Modules/11-MCP.md, docs/09-Configuration reference/02-Custom Resource Definitions.md	Provides user-facing documentation describing MCP requirements, deployed endpoints, configuration reference, and CRD field reference with MCPSpec and MCPStatus field tables.
MCP controller integration tests internal/tests/mcp_controller_test.go	Comprehensive Ginkgo test suite verifying Deployment creation with expected container args, image tag, environment variables, and resource limits, plus validation of GatewayHTTPAPI public rules and Caddyfile route rendering for MCP endpoints.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 A rabbit's ode to public routes

The gateway once hid all paths away,
Tucked under /api/ in the fray,
But MCP said "nay! let me be free!"
Now public routes flourish at the gateway tree 🌳
With proto and health checks in view,
The operator's hops make MCP dreams come true!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(mcp): add MCP module' directly and clearly describes the main change: introduction of a new MCP module to the codebase.
Description check	✅ Passed	The description is directly related to the changeset, providing detailed bullet points about MCP module addition, deployment configuration, routing, and validation steps performed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/add-mcp-module

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}