txn2/kubefwd

MCP Server Improvements

Graceful Startup Without API Connection

The MCP server now starts and registers all tools even when the kubefwd API is unavailable. This enables:

• Registry Discovery: Smithery, Glama.ai, and other MCP registries can now introspect kubefwd's tool definitions without requiring kubefwd to be running
• Better Developer Experience: Tools return helpful, structured error messages guiding users to start kubefwd when the API isn't available

Consistent Error Handling

All MCP tool handlers now return structured ProviderUnavailableError responses with:

• Clear diagnosis explaining the issue
• Suggested actions to resolve
• Retry recommendations

Example error response:

{
  "code": "provider_unavailable",
  "message": "State reader not available",
  "diagnosis": "kubefwd may not be running. Start it with: sudo -E kubefwd",
  "suggested_actions": [{"action": "get_health", "hint": "Check kubefwd status"}],
  "retry_recommended": true
}

New Files

• glama.json: Configuration for Glama.ai MCP registry claiming
• docs/images/kubefwd-logo.svg: Logo asset for documentation

Testing

• Added unit tests for MCP command package (cmd/kubefwd/mcp/mcp_test.go)
• Test coverage for cmd/kubefwd/mcp: 0% → 13.5%
• All existing tests pass
• Lint clean

Upgrade Notes

This is a non-breaking change. The MCP server behavior is improved but maintains backward compatibility. Users who previously ran kubefwd mcp without the API available will now see the server start (with warnings) instead of immediately exiting.

Full Changelog

• Improve MCP server initialization and API connection handling
• Replace generic error messages with structured NewProviderUnavailableError
• Add unit tests for MCP command flags and API connection validation
• Add glama.json configuration file for registry claiming
• Add kubefwd logo SVG for documentation

Changelog

• 7881c5a68a87fcd446e02fc3a81b5acbe580ac92 Fix gofmt -s simplification issues
• 6efedb9669701d4d0744c18bfbf038112f7adcb6 MCP server improvements (#372)
• dd8a3d2c69cbbef80cefafe315e11d47c42dc724 Quality/gocyclo (#363)
• cd084caeffc75b30f0cf1343c3ee4ec402748d58 Quality/housekeeping (#369)
• 080853c342563ecf22b5e027579833ba3ff450b8 Replace outdated TUI guide with revamped User Guide (#360)
• bdacb6d4ca6b5964b4d0e6ddd88668ef24ad96d3 Revert "Fix gofmt -s simplification issues"
• 6ad2509647c6f8e1927a48f0ca733f2920980edb Tests/coverage (#362)
• b96ea6df1fec1947f4c9aa277f64bf66e54e5a4d ci: bump actions/checkout from 4.2.2 to 6.0.1 (#370)
• a9610532a46bb46b23e2d94d67baf2ca500ed669 ci: bump actions/setup-go from 5.2.0 to 6.1.0 (#368)
• a84426d5921903d1c252cf57af3bc1f20c1bde12 ci: bump codecov/codecov-action from 5.4.3 to 5.5.2 (#365)
• 9e9da2d06017f39719263b0d9d38a78270371dfd ci: bump github/codeql-action from 3.27.9 to 4.31.9 (#367)
• f265619a957f296463c833ef187604223f7bc2a6 ci: bump golangci/golangci-lint-action from 6.1.1 to 9.2.0 (#366)
• e8b851fe697d89ac1de35c503e98d036ac8fe491 ci: bump ossf/scorecard-action from 2.4.1 to 2.4.3 (#364)