Update dependency txn2/kubefwd to v1.25.9

[renovate]

Note: This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Update	Change
txn2/kubefwd	minor	1.22.5 → v1.25.9

---

Release Notes

txn2/kubefwd (txn2/kubefwd)

v1.25.9: kubefwd-v1.25.9

Compare Source

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

• 7881c5a Fix gofmt -s simplification issues
• 6efedb9 MCP server improvements (#​372)
• dd8a3d2 Quality/gocyclo (#​363)
• cd084ca Quality/housekeeping (#​369)
• 080853c Replace outdated TUI guide with revamped User Guide (#​360)
• bdacb6d Revert "Fix gofmt -s simplification issues"
• 6ad2509 Tests/coverage (#​362)
• b96ea6d ci: bump actions/checkout from 4.2.2 to 6.0.1 (#​370)
• a961053 ci: bump actions/setup-go from 5.2.0 to 6.1.0 (#​368)
• a84426d ci: bump codecov/codecov-action from 5.4.3 to 5.5.2 (#​365)
• 9e9da2d ci: bump github/codeql-action from 3.27.9 to 4.31.9 (#​367)
• f265619 ci: bump golangci/golangci-lint-action from 6.1.1 to 9.2.0 (#​366)
• e8b851f ci: bump ossf/scorecard-action from 2.4.1 to 2.4.3 (#​364)

v1.25.8: kubefwd-v1.25.8

Compare Source

Bug Fixes

• fix: Windows hosts path auto-detection (#​359) - kubefwd now automatically detects the correct hosts file path based on the operating system:

  • Windows: C:\Windows\System32\drivers\etc\hosts
  • Linux/macOS: /etc/hosts

  Previously, the --hosts-path flag defaulted to /etc/hosts on all platforms, causing kubefwd to fail immediately on Windows with "Hosts path does not exist: /etc/hosts".

Changes

• Added runtime import to detect OS at runtime
• Added defaultHostsPath() function that returns OS-appropriate path
• Updated --hosts-path flag to use dynamic default

Windows Support

This release fixes a critical issue that prevented kubefwd from running on Windows without manually specifying the --hosts-path flag. Windows users can now run kubefwd without any additional configuration:

Before (Windows):

kubefwd svc -n mynamespace
FATA[12:34:18] Hosts path does not exist: /etc/hosts

After (Windows):

kubefwd --help | findstr hosts-path
--hosts-path string          Hosts file path. (default "C:\Windows\System32\drivers\etc\hosts")

Installation

Windows

Download from GitHub Releases and extract to your PATH.

# Download and extract (PowerShell)
Invoke-WebRequest -Uri "https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Windows_x86_64.zip" -OutFile kubefwd.zip
Expand-Archive kubefwd.zip -DestinationPath C:\kubefwd

# Add C:\kubefwd to your PATH

macOS (Homebrew)

brew install txn2/tap/kubefwd

Linux

Download from GitHub Releases or use your package manager.

Verifying This Release

All release artifacts are signed with Sigstore for supply chain security. Each binary archive has its own .sigstore.json signature bundle.

Verify Individual Binaries

# Example: Verify the Linux x86_64 binary
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz.sigstore.json

cosign verify-blob \
  --bundle kubefwd_Linux_x86_64.tar.gz.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_Linux_x86_64.tar.gz

Verify Checksums File

curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt.sigstore.json

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Available Signed Artifacts

Platform	Archive	Signature
Linux x86_64	kubefwd_Linux_x86_64.tar.gz	kubefwd_Linux_x86_64.tar.gz.sigstore.json
Linux arm64	kubefwd_Linux_arm64.tar.gz	kubefwd_Linux_arm64.tar.gz.sigstore.json
Linux armv6	kubefwd_Linux_armv6.tar.gz	kubefwd_Linux_armv6.tar.gz.sigstore.json
Linux i386	kubefwd_Linux_i386.tar.gz	kubefwd_Linux_i386.tar.gz.sigstore.json
macOS x86_64	kubefwd_Darwin_x86_64.tar.gz	kubefwd_Darwin_x86_64.tar.gz.sigstore.json
macOS arm64	kubefwd_Darwin_arm64.tar.gz	kubefwd_Darwin_arm64.tar.gz.sigstore.json
Windows x86_64	kubefwd_Windows_x86_64.zip	kubefwd_Windows_x86_64.zip.sigstore.json
Windows i386	kubefwd_Windows_i386.zip	kubefwd_Windows_i386.zip.sigstore.json

Docker Image Verification

cosign verify txn2/kubefwd:v1.25.8 \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*"

v1.25.7: kubefwd-v1.25.7

Compare Source

TUI Browse Modal

Introduces an interactive Browse Modal for discovering and forwarding Kubernetes services directly from the TUI. Press f to open a hierarchical browser that navigates through contexts, namespaces, and services - then forward individual services or entire namespaces without leaving the interface.

Browse Modal Features

• Three-level navigation: Contexts → Namespaces → Services
• Forward services on demand: Select any service and press Enter to start forwarding
• Bulk forwarding: "Forward All" option forwards every service in a namespace
• Visual indicators: Already-forwarded services show a checkmark (✓)
• Port display: See service ports before forwarding
• Context switching: Press c to switch Kubernetes contexts

Keyboard Shortcuts

Key	Action
f	Open browse modal
j / ↓	Move down
k / ↑	Move up
g	Jump to top
G	Jump to bottom
Enter / →	Select / Forward service
Esc / ← / q	Go back / Close
c	Switch Kubernetes context

Use Case

Start kubefwd with minimal namespaces, then dynamically add services as needed:

# Start with one namespace
sudo -E kubefwd svc -n default --tui

# Press 'f' to browse, navigate to another namespace,

# and forward additional services on demand

Bug Fixes

Pod Logs Streamer Reliability

Fixed nil interface issues with clientSet initialization in the TUI pod logs streamer. Improved namespace manager integration ensures reliable log streaming.

Log Spam Prevention

ServiceFWD now tracks "no pods" warnings with a flag to prevent repeated log messages. The flag resets when pods become available, allowing future warnings if pods disappear again.

Test Coverage Improvements

Significant expansion of TUI test coverage:

Package	Before	After
pkg/fwdtui	4.63%	74.8%
pkg/fwdtui/events	—	100.0%
pkg/fwdtui/state	—	97.9%
Overall	60.65%	67.6%

New test files:

• browse_test.go — 1,277 lines covering BrowseModel navigation, loading states, error handling
• tui_test.go — 1,712 lines covering RootModel, event handling, and UI components

Documentation

Updated API reference and OpenAPI specification with documentation for Kubernetes pod debugging and event endpoints (no new code, documentation only).

CI Updates

• Updated GitHub Actions dependencies for security and compatibility
• Pinned codeql-action/upload-sarif version in Scorecard workflow

No MCP/API Code Changes

This release contains no changes to the MCP server or REST API functionality. All MCP tools (29 total) continue to work as documented in v1.25.6.

Changes

• Add TUI Browse Modal for interactive service discovery (#​358)
• Add API documentation for Kubernetes pod/event endpoints (#​357)
• Code quality improvements (#​353, #​354, #​355)
• Documentation housekeeping (#​356)
• CI dependency updates (#​345, #​346, #​347, #​348, #​349)

Full Changelog

Changelog

• 269f550 Add Kubernetes pod debugging and event APIs (#​357)
• 3f0f812 Documentation and badge housekeepin (#​352)
• f259e34 Housekeeping/documentation (#​356)
• addd289 Potential fixes for 2 code quality findings (#​353)
• fc2215f Potential fixes for 3 code quality findings (#​354)
• 56ad479 Potential fixes for 3 code quality findings (#​355)
• 1351ad1 TUI Browse Modal & Tests (#​358)
• ebe298b ci: bump actions/setup-python from 5.3.0 to 6.1.0 (#​349)
• 76a9fad ci: bump actions/upload-artifact from 4.6.1 to 6.0.0 (#​345)
• 118f9de ci: bump anchore/sbom-action from 0.18.0 to 0.21.0 (#​347)
• a15b5f1 ci: bump docker/setup-buildx-action from 3.7.1 to 3.12.0 (#​348)
• 49b7db3 ci: bump sigstore/cosign-installer from 3.7.0 to 4.0.0 (#​346)

v1.25.6: kubefwd-v1.25.6

Compare Source

Fixes critical issues with the Kubernetes discovery MCP tools introduced in v1.25.5. The tools were defined but their HTTP API routes were not registered, causing 404 errors.

Fixed: Missing API Routes

The following MCP tools now work correctly:

Tool	Issue	Fix
get_pod_logs	404 - route not registered	Added /v1/kubernetes/pods/:namespace/:podName/logs
list_pods	404 - route not registered	Added /v1/kubernetes/pods/:namespace
get_pod	404 - route not registered	Added /v1/kubernetes/pods/:namespace/:podName
get_events	404 - route not registered	Added /v1/kubernetes/events/:namespace
get_endpoints	404 - route not registered	Added /v1/kubernetes/endpoints/:namespace/:serviceName

Fixed: Response Format Errors

Tool	Issue	Fix
list_pods	JSON unmarshal error	Return array directly, not wrapped in object
get_events	JSON unmarshal error	Return array directly, not wrapped in object

Fixed: get_connection_info Without Namespace

Previously, calling get_connection_info with only a service name (no namespace) would return 404. Now it:

1. Searches for services matching the name
2. If exactly one match, returns that service's connection info
3. If multiple matches, returns an error listing namespaces to disambiguate

# Now works:
get_connection_info(service_name="postgres")

# If ambiguous, helpful error:
"multiple services found with name 'postgres' in namespaces: [staging, production]. Please specify namespace"

Changes

• Fix missing HTTP routes for 5 MCP Kubernetes discovery tools
• Fix response format for list_pods and get_events
• Fix get_connection_info to work without namespace parameter

Full Changelog

Changelog

• 516bdc3 Fix Missing Kubernetes API Routes for MCP (#​351)
• 60238c7 deps: bump github.com/bep/debounce from 1.2.0 to 1.2.1 (#​344)

v1.25.5: kubefwd-v1.25.5

Compare Source

MCP Kubernetes Discovery Enhancements

Expands MCP server capabilities with comprehensive Kubernetes read operations for debugging and discovery. Previously, users could not inspect Kubernetes resources beyond forwarded services through the MCP interface.

New MCP Tools (5 tools)

Tool	Description	Key Parameters
get_pod_logs	Get container logs from a pod	namespace, pod_name, tail_lines, previous, timestamps
list_pods	List pods with status/ready/restarts	namespace, label_selector, service_name
get_pod	Detailed pod info (containers, conditions, resources)	namespace, pod_name
get_events	K8s events for debugging startup failures	namespace, resource_kind, resource_name, limit
get_endpoints	Service endpoints showing backing pods	namespace, service_name

Use Cases

Claude Desktop (or any MCP client) can now:

1. Debug a failing service:

   • "What pods are backing auth-service?" → list_pods with service_name filter
   • "Is the pod healthy?" → get_pod for detailed status
   • "Why won't it start?" → get_events for scheduling/pulling/startup events

2. Investigate pod issues:

   • "Show me the logs" → get_pod_logs
   • "What was the last error?" → get_pod_logs with previous=true
   • "Check container status" → get_pod with container details

3. Verify service routing:

   • "Which pods are ready?" → get_endpoints shows ready vs not-ready addresses

Complete MCP Tool Inventory (29 tools)

Forwarding Management (7): add_namespace, remove_namespace, add_service, remove_service, reconnect_service, reconnect_all_errors, sync_service

Service Discovery (7): list_services, get_service, find_services, list_k8s_namespaces, list_k8s_services, list_contexts, get_connection_info, list_hostnames

Pod Operations (5) — NEW: list_pods, get_pod, get_pod_logs, get_events, get_endpoints

Monitoring & Diagnostics (10): get_health, get_quick_status, get_metrics, get_http_traffic, get_analysis, diagnose_errors, get_logs, get_history

OpenSSF Scorecard

Added OpenSSF Scorecard workflow for security best practices monitoring. The scorecard analyzes the repository for security posture including branch protection, dependency management, and code review practices.

Changes

• Add MCP Kubernetes discovery tools for pod/event/endpoint inspection (#​350)
• Add OpenSSF Scorecard security analysis workflow (#​343)

Full Changelog

v1.25.4: kubefwd-v1.25.4

Compare Source

This release focuses on MCP tool response, code quality improvements, test reliability, and bug fixes identified by GitHub's security scorecard and code quality analysis tools.

Bug Fixes

MCP Tool Response Format

• Fixed all 24 MCP tool handlers to return complete JSON data instead of text summaries
• AI clients now receive full structured data when using MCP tools like list_services, add_namespace, etc.
• Resolves issue where add_namespace reported "Discovered 0 services" despite successful forwarding

SLSA Provenance Generation

• Fixed artifact hash generation in release workflow
• Previous implementation failed silently when certain file types (e.g., .zip) didn't exist
• Now uses find command to reliably locate all artifacts before hashing

Test Improvements

Eliminated Flaky Tests

• Replaced time.Sleep patterns with proper synchronization using waitForCondition helper
• Affected tests in pkg/fwdsvcregistry now poll for conditions instead of arbitrary delays

Race Condition Fixes

• Replaced sync.Once with mutex-protected bool in pkg/fwdapi/manager.go and pkg/fwdapi/logbuffer.go
• Tests can now properly reset and restore global state without race conditions

Code Quality

• Replaced confusing string(rune('0'+i)) patterns with fmt.Sprintf for clarity
• Fixed invalid port number (99999 → 65535) in network error test
• Replaced custom contains helper with strings.Contains
• Improved non-string conversion test to verify actual type assertions

Build/CI Improvements

• Pinned GoReleaser version to ~> v2.13 in both CI and release workflows
• Improved artifact hash generation reliability for SLSA provenance

Full Changelog

Changed Files

• .github/workflows/ci.yml - Pin GoReleaser version
• .github/workflows/release.yml - Pin GoReleaser version, fix hash generation
• pkg/fwdapi/logbuffer.go - Replace sync.Once with mutex pattern
• pkg/fwdapi/logbuffer_test.go - Improve test reliability and clarity
• pkg/fwdapi/manager.go - Replace sync.Once with mutex pattern
• pkg/fwdapi/manager_test.go - Update for new initialization pattern
• pkg/fwdmcp/httpclient_test.go - Fix invalid port number
• pkg/fwdmcp/tools.go - Return nil CallToolResult for proper JSON responses
• pkg/fwdmcp/tools_test.go - Update tests for new handler behavior
• pkg/fwdmetrics/httpsniff_test.go - Replace confusing string expressions
• pkg/fwdns/manager_test.go - Use strings.Contains
• pkg/fwdsvcregistry/fwdsvcregistry_test.go - Add waitForCondition, eliminate time.Sleep

Changelog

• 0271289 MCP Registry Readiness (#​341)
• 1f7def5 MCP and Test Quality Improvements (#​342)

v1.25.3: kubefwd-v1.25.3

Compare Source

Changelog

• 41931d2 Improve Unit Test Coverage (#​340)

v1.25.2: kubefwd-v1.25.2

Compare Source

This release focuses on security improvements, OpenSSF Scorecard compliance, and MCP bug fixes.

---

Highlights

Security Fix: IP Parsing Bounds Validation

Fixed CodeQL security alert for incorrect integer conversion in IP parsing. The ipFromString() function now validates that each octet is within 0-255 bounds before casting to byte, preventing potential overflow issues.

MCP Bug Fixes

• Fixed namespace state corruption - remove_namespace no longer corrupts state for subsequent add_service calls
• Fixed service discovery reporting - add_namespace now correctly reports discovered service count via direct K8s API query
• Restored parameter hints - All MCP tool descriptions now include required parameter hints (e.g., "Requires key (e.g., 'servicename.namespace.context')")

OpenSSF Scorecard Improvements

• Pinned all workflow dependencies by SHA hash
• Restricted token permissions to job-level scope
• Expected Scorecard improvement: Pinned-Dependencies 8→10/10, Token-Permissions 0→10/10

MCPB Bundle Signing

MCPB bundles are now signed with Cosign and included in SLSA provenance attestation for enhanced supply chain security.

---

What's New

Security

• Fixed CodeQL alert: bounds validation for IP octet parsing (#​339)
• Added fuzz tests for IP parsing to catch edge cases (#​336)
• Fixed panic in ipFromString for malformed input (#​336)

Bug Fixes

• Fixed remove_namespace corrupting state for subsequent add_service calls (#​338)
• Fixed add_namespace reporting "Discovered 0 services" (#​338)
• Restored MCP tool parameter hints that were accidentally removed (#​338)
• Added missing switch cases for StatusPending and StatusStopping (#​338)
• Fixed nil pointer panic in fwdsvcregistry.GetAll() (#​338)

Build/CI

• Improved OpenSSF Scorecard compliance (#​337)
• Pinned workflow dependencies by SHA hash
• Restricted token permissions to job-level
• Sign MCPB bundles with Cosign (#​335)
• Include MCPB bundles in SLSA provenance attestation
• Fix MCPB build script for goreleaser arm64 directory naming (#​334)
• Pin mkdocs-material version in docs workflow
• Add fuzz testing to CI workflow

Testing

• Added fuzz tests for IP parsing functions
• Added 11 unit tests for IP octet bounds validation
• Added tests covering values >255, negative values, edge cases

Dependencies

• Bumped github.com/quic-go/quic-go from 0.54.0 to 0.57.0

---

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Claude Desktop (MCPB)

Download the appropriate .mcpb file for your platform and double-click to install.

Binary Download

Download the appropriate archive for your platform from the release assets.

Docker

docker pull txn2/kubefwd:v1.25.2

Package Managers

• APK: kubefwd_amd64.apk, kubefwd_arm64.apk
• DEB: kubefwd_amd64.deb, kubefwd_arm64.deb
• RPM: kubefwd_amd64.rpm, kubefwd_arm64.rpm

---

Checksums & Verification

All release artifacts include:

• SHA256 checksums in kubefwd_checksums.txt
• Sigstore signature in kubefwd_checksums.txt.sigstore.json
• SBOM (Software Bill of Materials) for each archive
• SLSA Level 3 provenance attestation

Verify signatures with:

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.github/workflows/release.yml@refs/tags/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

---

Breaking Changes

None.

---

Upgrade Notes

This is a drop-in replacement for v1.25.1. No configuration changes required.

---

Contributors

Thanks to all contributors who made this release possible.

---

Full Changelog

See the commit log for the complete list of changes.

Changelog

• b4ffd89 Add fuzz testing to CI workflow
• 6345ab0 Add fuzz tests and fix panic in ipFromString
• a7735fa Fix CodeQL autobuild and improve Scorecard compliance
• c762a68 Fix CodeQL security alert (#​339)
• 8bbb961 Fix MCPB build script for goreleaser arm64 directory naming
• bdd56dd Improve OpenSSF Scorecard - Pin dependencies and restrict token permissions (#​337)
• 64510b0 MCP Bug Fixes and Improvements (#​338)
• ce94be8 Pin mkdocs-material version in docs workflow
• cafed0b Sign MCPB bundles with Cosign and include in SLSA provenance
• 56615cf deps: bump github.com/quic-go/quic-go from 0.54.0 to 0.57.0

v1.25.1: kubefwd-v1.25.1

Compare Source

This release focuses on MCP (Model Context Protocol) stability improvements, MCPB bundle distribution for Claude Desktop, and enhanced test coverage.

---

Highlights

MCPB Bundle Support for Claude Desktop

kubefwd now ships with .mcpb bundles for one-click installation in Claude Desktop:

• macOS (Intel): kubefwd-1.25.1-darwin-amd64.mcpb
• macOS (Apple Silicon): kubefwd-1.25.1-darwin-arm64.mcpb
• Windows: kubefwd-1.25.1-windows-amd64.mcpb

Simply download and double-click to install kubefwd as an MCP server in Claude Desktop.

MCP Stability Improvements

• Fixed add_service race condition - The tool now waits for pod discovery to complete before returning, ensuring services appear in state immediately with correct connection info
• Improved tool descriptions - All 23 MCP tools now explicitly document required parameters, helping AI assistants use them correctly on the first try
• Enhanced namespace removal - Added proper cleanup of orphaned forwards and services when namespaces are removed

Event Bus Enhancements

• Added NamespaceRemoved event type for proper cleanup coordination
• Implemented unsubscribe logic for event handlers to prevent memory leaks
• Added blocking/unblocking logic to prevent race conditions during namespace removal

---

What's New

Features

• MCPB bundle generation and distribution via GitHub releases
• NamespaceRemoved event type and handler for TUI cleanup
• RemoveByNamespace method to clean up orphaned forwards and services
• MCP mode detection with banner suppression for cleaner output
• PodAdded event subscription for accurate service initialization

Bug Fixes

• Fixed race condition in add_service MCP tool that returned before pod discovery completed
• Fixed namespace removal leaving orphaned services in state store
• Fixed potential race conditions during namespace removal operations

Documentation

• Expanded MCP integration guide with detailed capability descriptions
• Added API documentation image to reference guide
• Updated README with new links for API Reference and MCP Integration
• Fixed typo: "API Refrence" → "API Reference"

Testing

• Added comprehensive MCP integration tests (398+ lines)
• Added test utilities and fixtures for MCP state management
• Added tests for RemoveByNamespace functionality
• Added tests for namespace blocking/unblocking behavior
• Added event bus unsubscribe tests
• Added TUI event handling tests

Dependencies

• Bumped golang.org/x/crypto from 0.44.0 to 0.45.0

---

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Claude Desktop (MCPB)

Download the appropriate .mcpb file for your platform and double-click to install.

Binary Download

Download the appropriate archive for your platform from the release assets.

Docker

docker pull txn2/kubefwd:v1.25.1

Package Managers

• APK: kubefwd_amd64.apk, kubefwd_arm64.apk
• DEB: kubefwd_amd64.deb, kubefwd_arm64.deb
• RPM: kubefwd_amd64.rpm, kubefwd_arm64.rpm

---

Checksums & Verification

All release artifacts include:

• SHA256 checksums in kubefwd_checksums.txt
• Sigstore signature in kubefwd_checksums.txt.sigstore.json
• SBOM (Software Bill of Materials) for each archive
• SLSA Level 3 provenance attestation

Verify signatures with:

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

---

Breaking Changes

None.

---

Upgrade Notes

This is a drop-in replacement for v1.25.0. No configuration changes required.

---

Contributors

Thanks to all contributors who made this release possible.

---

Full Changelog

See the commit log for the complete list of changes.

Changelog

• 2514351 Add API documentation image to reference guide
• 6bd4863 Add MCP mode detection and banner suppression logic
• 6d7d1d0 Add NamespaceRemoved event type and its handler
• 833ee0b Add RemoveByNamespace to clean up orphaned forwards and services
• f52eeaf Add script and workflows to build and upload MCPB bundles
• 6af4115 Add test utilities and integration tests for MCP state management
• 6078193 Add tests for RemoveByNamespace in store
• 8a0b841 Add tests for namespace blocking and unblocking behavior in state store
• 684f61a Add unsubscribe logic and tests for event handlers in Bus implementation
• 8b5b215 Emit NamespaceRemoved event after service removal
• 77fc7dc Fix typo in README: correct "API Refrence" to "API Reference"
• b6439a0 Handle NamespaceRemoved event in TUI
• e95fad3 Improve context handling and logging for namespace and service operations
• 0c07d77 Prevent race conditions during namespace removal by introducing blocking/unblocking logic in the state store
• 5111771 Revise and expand MCP integration guide with enhanced feature descriptions
• 971c307 Specify required parameters in MCP tool descriptions
• 6695eb4 Subscribe to PodAdded events for services to ensure accurate initialization
• 4aca09f Update README with new links for API Reference and MCP Integration
• da3255f deps: bump golang.org/x/crypto from 0.44.0 to 0.45.0

v1.25.0: kubefwd-v1.25.0

Compare Source

This is a major release introducing a REST API for programmatic control and an MCP (Model Context Protocol) server for AI assistant integration. Developers can now manage port forwards dynamically through API calls or by chatting with AI tools like Claude Desktop, Cursor, and VS Code Copilot. This release also introduces "idle mode" for daemon-style operation, allowing kubefwd to start without any namespaces and add them on-the-fly.

Highlights

• REST API: Full-featured HTTP API with 40+ endpoints for programmatic control, real-time SSE event streaming, and OpenAPI documentation
• MCP Server: First-class integration with AI assistants via 23 tools, 8 resources, and 10 prompts
• Idle Mode: Run kubefwd without namespaces, add/remove them dynamically via API or MCP
• AI-Optimized Analysis: Endpoints designed for LLM consumption with structured errors and suggested actions
• Security Hardening: CORS origin whitelist and bounded memory allocations

---

New Features

REST API (PR #​330)

kubefwd now includes a comprehensive REST API built with Gin, enabling programmatic control over port forwarding:

# Start kubefwd with API enabled
sudo -E kubefwd svc -n default --api

# Or use idle mode (API enabled by default)
sudo -E kubefwd

# Test the API
curl http://kubefwd.internal/api/health

API Features

• 40+ Endpoints: Complete control over services, forwards, namespaces, and diagnostics
• OpenAPI Documentation: Interactive docs at http://kubefwd.internal/docs
• SSE Event Streaming: Real-time events at /api/v1/events
• AI-Optimized Endpoints: /api/v1/analyze and /api/v1/status designed for LLM consumption
• History Tracking: Event, error, and reconnection history with ring buffer storage

Key Endpoints

Category	Endpoints	Description
Health	GET /api/health, /api/info	Health checks and version info
Services	GET/POST/DELETE /api/v1/services	List, add, remove services
Forwards	GET /api/v1/forwards	Active port forward details
Namespaces	GET/POST/DELETE /api/v1/namespaces	Dynamic namespace management
Metrics	GET /api/v1/metrics[/services]	Traffic statistics
Logs	GET /api/v1/logs[/stream]	Recent and streaming logs
Events	GET /api/v1/events (SSE)	Real-time event stream
Diagnostics	GET /api/v1/diagnostics	Network and error diagnostics
Analysis	GET /api/v1/analyze, /api/v1/status	AI-friendly status analysis
History	GET /api/v1/history/*	Event and error history
Kubernetes	GET /api/v1/kubernetes/*	Cluster discovery

Example: Add a Namespace Dynamically

# Add a namespace to forward
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{"namespace": "staging", "context": "my-cluster"}'

# List forwarded services
curl http://kubefwd.internal/api/v1/services

# Remove when done
curl -X DELETE http://kubefwd.internal/api/v1/namespaces/staging.my-cluster

---

MCP Server Integration (PR #​330)

kubefwd now includes a full Model Context Protocol server for seamless AI assistant integration:

# Start MCP server on stdio (for Claude Desktop, Cursor, etc.)
kubefwd mcp

# MCP over HTTP (connects to running kubefwd API)
kubefwd mcp --http

MCP Capabilities

• 23 Tools: Complete control from AI conversations
• 8 Resources: Expose state to AI assistants
• 10 Prompts: Guided workflows for common tasks

Available Tools

Category	Tools	Description
Services	list_services, get_service, find_services	Query forwarded services
Management	add_namespace, remove_namespace, add_service, remove_service	Dynamic control
Actions	reconnect_service, reconnect_all_errors, sync_service	Recovery operations
Metrics	get_metrics, get_logs, get_http_traffic	Monitoring
Kubernetes	list_k8s_namespaces, list_k8s_services, list_contexts	Cluster discovery
Analysis	diagnose_errors, get_health, get_analysis, get_quick_status	AI-optimized diagnostics
Connection	get_connection_info, list_hostnames	Developer helpers
History	get_history	Event and error history

Available Resources

URI	Description
kubefwd://services	All forwarded services with status
kubefwd://forwards	Active port forwards with IPs and ports
kubefwd://metrics	Traffic statistics
kubefwd://summary	High-level health summary
kubefwd://errors	Current errors with details
kubefwd://status	Quick health status (ok/issues/error)
kubefwd://http-traffic	Recent HTTP requests
kubefwd://contexts	Available Kubernetes contexts

Available Prompts

Prompt	Description
setup_local_dev	Set up local development environment
connection_guide	Get connection info for a service
forward_namespace	Forward all services in a namespace
troubleshoot	Systematic debugging guide
fix_errors	Step-by-step error resolution
debug_service	Debug a specific service
quick_connect	Fastest path to connect to a service
analyze_issues	Comprehensive issue analysis
explain_status	Non-technical status explanation
monitor	Traffic and health monitoring guide

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "kubefwd": {
      "command": "kubefwd",
      "args": ["mcp"],
      "env": {
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Then chat naturally with Claude:

"Connect me to the postgres database in the staging namespace"
"What services are currently having errors?"
"Show me connection info for the auth-service"

Cursor Integration

Add to Cursor settings:

{
  "mcp": {
    "servers": {
      "kubefwd": {
        "command": "sudo",
        "args": ["-E", "kubefwd", "mcp"],
        "type": "stdio"
      }
    }
  }
}

---

Idle Mode (PR #​330)

kubefwd can now run without specifying namespaces upfront, enabling daemon-style operation:

# Start in idle mode (no namespaces, API enabled by default)
sudo -E kubefwd

# Add namespaces via API
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -d '{"namespace": "production"}'

# Or via MCP (from AI assistant)

# "Forward the production namespace"

This is particularly useful for:

• Long-running development environments: Start once, add namespaces as needed
• CI/CD pipelines: Programmatically control which services are forwarded
• AI-driven workflows: Let AI assistants manage port forwarding based on context

---

Namespace Manager (PR #​330)

New dynamic namespace management system (pkg/fwdns):

• Add namespaces at runtime: No restart required
• Remove namespaces cleanly: Stops all forwards, cleans up hosts file
• Label selectors: Filter services within a namespace
• Multi-context support: Forward from multiple clusters simultaneously

---

Security Improvements

CORS Origin Whitelist

The API now uses an explicit origin whitelist instead of Access-Control-Allow-Origin: *:

var allowedOrigins = map[string]bool{
    "http://kubefwd.internal":   true,
    "http://localhost":          true,
    "http://localhost:8080":     true,
    "http://127.0.0.1":          true,
    "http://127.0.0.1:8080":     true,
    "http://127.2.27.1":         true,
    "http://127.2.27.1:8080":    true,
}

Bounded Memory Allocations (CWE-770)

All ring buffer allocations now have explicit bounds to prevent memory exhaustion:

• Event history: max 10,000 entries
• Error history: max 5,000 entries
• Reconnection history: max 2,000 entries per service
• Log buffer: max 10,000 entries

---

Improvements

AI-Friendly Error Handling

Errors now include machine-readable codes and suggested actions:

{
  "error": {
    "code": "CONNECTION_REFUSED",
    "message": "Failed to connect to pod",
    "suggestion": "The pod may not be ready. Try 'reconnect_service' after the pod is running.",
    "affectedService": "postgres.default.minikube"
  }
}

Event History

New ring buffer-based history system tracks:

• Service lifecycle events (added, removed, connected, errored)
• Errors with timestamps and context
• Reconnection attempts with success/failure status

HTTP Traffic Inspection

Monitor HTTP requests flowing through port forwards:

# Via API
curl http://kubefwd.internal/api/v1/services/myapi.default.ctx/http

# Returns recent requests with method, path, status, duration

OpenAPI Documentation

Interactive API documentation available at /docs:

• Try endpoints directly from the browser
• Full request/response schemas
• Authentication and error documentation

---

Testing

New Test Coverage

Comprehensive tests added for all new packages:

• pkg/fwdapi: API handlers, middleware, adapters
• pkg/fwdmcp: MCP server, tools, resources, prompts
• pkg/fwdns: Namespace manager
• pkg/fwdapi/history: Ring buffer storage
• pkg/fwdapi/handlers: All HTTP handlers

Test Infrastructure

• Mock implementations for all interfaces
• Table-driven tests for edge cases
• Race condition testing with -race flag

---

Build and Infrastructure

New Packages

Package	Description
pkg/fwdapi	REST API server with Gin framework
pkg/fwdapi/handlers	HTTP request handlers
pkg/fwdapi/middleware	CORS, logging, recovery middleware
pkg/fwdapi/types	API types and interfaces
pkg/fwdapi/history	Event and error history storage
pkg/fwdmcp	MCP server implementation
pkg/fwdns	Dynamic namespace manager

Dependencies

New dependencies for this release:

• github.com/gin-gonic/gin - HTTP framework
• github.com/modelcontextprotocol/go-sdk/mcp - MCP protocol

---

Documentation

New Documentation

• REST API Reference: Complete endpoint documentation
• MCP Integration Guide: AI assistant setup instructions
• OpenAPI Specification: Machine-readable API spec at /openapi.yaml

Updated Documentation

• README.md: Added API and MCP quick start examples
• CLAUDE.md: Updated architecture documentation

---

Bug Fixes

• Fixed lint issues across multiple packages (errcheck, staticcheck, unused)
• Fixed CORS configuration (was too permissive with *)
• Fixed unbounded slice allocations (CodeQL CWE-770)
• Fixed embedded mutex field access patterns
• Fixed time.Now().Sub() to use time.Since() idiom

---

Breaking Changes

None. This release is fully backward compatible with v1.24.x.

The new features are opt-in:

• API disabled by default (use --api flag or idle mode)
• MCP server is a separate subcommand (kubefwd mcp)

---

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Docker

docker pull txn2/kubefwd:v1.25.0

Binary Downloads

Download pre-built binaries from the GitHub Releases page.

Available for:

• Linux (amd64, arm64, arm, 386)
• macOS (amd64, arm64)
• Windows (amd64, 386)

Package Managers

• APK (Alpine): kubefwd_arm64.apk, kubefwd_amd64.apk
• DEB (Debian/Ubuntu): kubefwd_arm64.deb, kubefwd_amd64.deb
• RPM (RHEL/CentOS/Fedora): kubefwd_arm64.rpm, kubefwd_amd64.rpm

---

Verifying Downloads

Verify Checksum Signature

# Download checksum file and signature bundle
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.0/kubefwd_checksums.txt
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.0/kubefwd_checksums.txt.sigstore.json

# Verify signature
cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Verify Docker Image

cosign verify txn2/kubefwd:v1.25.0 \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*"

---

Upgrade Notes

Upgrading from v1.24.x should be seamless. New features are opt-in.

Try the REST API

# Forward with API enabled
sudo -E kubefwd svc -n default --api

# Access interactive docs
open http://kubefwd.internal/docs

Try MCP with Claude Desktop

1. Install kubefwd v1.25.0
2. Add MCP configuration (see above)
3. Restart Claude Desktop
4. Chat: "Forward the default namespace and show me what services are available"

Try Idle Mode

# Start without namespaces
sudo -E kubefwd

# Add namespaces via API as needed
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -d '{"namespace": "default"}'

---

Full Changelog

See the commit history for the complete list of changes.

Changelog

• 8c5bc5c Add AI-focused analysis and status handlers
• 00bc8ad Add API adapters and handlers for fwdapi package
• 69bc443 Add API documentation handlers and unit tests
• 80835ac Add API response and metadata types for fwdapi package
• c9638ae Add HTTP client methods and controllers for MCP API integration
• 0008590 Add HTTP traffic inspection handlers for forwards and services
• f502482 Add HTTP-based MCP server integration and related API adapters
• feced12 Add HTTP-based providers for Analysis, Traffic, and History APIs
• 234ad96 Add KubernetesHandler for resource discovery and API integration
• f6eedd7 Add MCP command integration to kubefwd CLI
• 98d820a Add MCP mode and server integration with support for diagnostics, metrics, and service control
• [de810f2](https://redirect.github.com/txn2

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Enabled.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.