Adding a New Tool

Start by deciding which MCP server owns the capability:

• Add diagnostics, RBAC, security, and upgrade tools to pkg/mcp/server/.
• Add deployment and app-operation tools to pkg/deploy/mcp/.

Step 1: choose the implementation file

Keep handlers grouped by domain.

• Add diagnostics logic to diagnostics.go or a new domain-specific file in pkg/mcp/server/.
• Add deploy, GitOps, Helm, or kubectl logic to the matching pkg/deploy/mcp/tools_*.go file.

Step 2: add the tool schema to the tool list

Expose the tool to MCP clients by adding it to the tool catalog in the relevant server file:

• pkg/mcp/server/server.go → handleToolsList
• pkg/deploy/mcp/server.go → handleListTools

At this stage define:

• The tool name.
• A clear description.
• The JSON input schema.
• Required fields.

Step 3: wire the dispatcher

Add a new case in the tool dispatch switch:

• pkg/mcp/server/server.go → handleToolsCall
• pkg/deploy/mcp/server.go → handleToolCall

This is what connects the public MCP tool name to your Go handler.

Step 4: implement the handler

Implementation conventions differ slightly by binary.

kubestellar-ops

• Implement a method on *Server.
• Accept context.Context when the tool performs Kubernetes I/O.
• Use getClientForCluster, discoverer, or shared helpers.
• Return a readable text summary and whether the call should be marked as an error.

kubestellar-deploy

• Implement a method on *Server.
• Unmarshal the raw arguments into a typed request struct.
• Use Executor, Selector, ClientManager, and pkg/gitops helpers as needed.
• Return a structured response object and an error.

Step 5: add tests

Add focused unit tests beside the implementation.

Examples already in the repo:

• pkg/mcp/server/tools_test.go
• pkg/mcp/server/diagnostics_test.go
• pkg/deploy/mcp/tools_app_test.go
• pkg/deploy/mcp/tools_gitops_test.go

Favor the existing testing style:

• Exercise the handler directly.
• Inject fakes or stubs for cluster discovery, kube clients, or manifest readers where supported.
• Assert both success output and error cases.

Step 6: update user-facing docs when needed

If the tool changes the user experience, update the relevant files:

• README.md or docs/ for developer and operator guidance.
• Matching markdown in commands/ if the Claude Code command descriptions should surface the new workflow.