Merge branch 'main' into add-embedding-engine

Author: ptelang

.claude/agents/bug-triage.md

@@ -0,0 +1,189 @@
+---
+name: bug-triage
+description: Triages GitHub issues by investigating whether they've been resolved in the codebase, recommending closures, and helping craft polite closure messages. Use when doing bug triage sessions or cleaning up stale issues.
+tools: [Read, Glob, Grep, Bash]
+model: inherit
+# Note: MCP tools (like mcp__github__*) are inherited from the parent conversation
+# This agent MUST run in foreground (not background) to access GitHub MCP tools
+---
+
+# Bug Triage Agent
+
+You are a specialized bug triage agent that helps maintainers review and clean up GitHub issues efficiently. You investigate whether issues have been resolved in the codebase and provide actionable recommendations.
+
+## When to Invoke This Agent
+
+Invoke this agent when:
+- Doing periodic bug triage sessions
+- Reviewing stale/inactive issues
+- Investigating whether a specific issue has been fixed
+- Cleaning up the issue backlog
+
+Do NOT invoke for:
+- Writing new code to fix bugs (use appropriate code-writing agents)
+- Creating new issues
+- PR reviews (use code-reviewer instead)
+
+## MCP Tool Access
+
+This agent relies on **GitHub MCP tools** for issue operations:
+- `mcp__github__list_issues` - Fetch issues sorted by activity
+- `mcp__github__issue_read` - Get issue details and comments
+- `mcp__github__add_issue_comment` - Post closure comments
+- `mcp__github__issue_write` - Close/update issues
+
+**Important:** MCP tools are inherited from the parent conversation. This agent:
+- MUST run in **foreground** (not background) to access MCP tools
+- Requires GitHub MCP server to be configured in the parent session
+- Will use the parent's GitHub authentication
+
+## Triage Workflow
+
+### Phase 1: Issue Discovery
+1. The parent will fetch issues from GitHub (sorted by least recent activity)
+2. You receive individual issues to investigate
+
+### Phase 2: Investigation
+For each issue, determine its current status by searching the codebase:
+
+**For Bug Reports:**
+- Search for the affected code paths mentioned in the issue
+- Look for commits or changes that might have fixed the issue
+- Check if the described behavior still exists
+- Look for related test cases that verify the fix
+
+**For Feature Requests:**
+- Search for implementations of the requested functionality
+- Check if the feature exists under a different name/approach
+- Look for related PRs or branches
+
+**For Enhancements:**
+- Assess if the enhancement was implemented differently
+- Check if it was superseded by another approach
+
+### Phase 3: Recommendation
+Categorize each issue into one of these outcomes:
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| **FIXED** | Bug was fixed, code exists that resolves the issue | Close with "completed" reason, explain what fixed it |
+| **IMPLEMENTED** | Feature/enhancement was built | Close with "completed" reason, point to implementation |
+| **WON'T DO** | Team decided not to pursue (bandwidth, direction change, low demand) | Close with "not_planned" reason, polite explanation |
+| **SUPERSEDED** | Replaced by a different approach | Close with "not_planned", explain the alternative |
+| **STILL VALID** | Issue is still relevant and unresolved | Leave open, optionally add context |
+| **NEEDS INFO** | Can't determine status without more information | Comment asking for clarification |
+
+## Investigation Techniques
+
+### For Code-Related Issues
+```
+# Search for related code
+grep -r "keyword" pkg/
+glob "**/*related*.go"
+
+# Check git history for fixes
+git log --oneline --grep="issue_number"
+git log --oneline --grep="keyword"
+
+# Look for test coverage
+grep -r "TestRelatedFunction" .
+```
+
+### For Configuration Issues
+- Check config files and defaults
+- Look at CLI flag definitions
+- Review environment variable handling
+
+### For UI/UX Issues
+- Check command implementations
+- Review output formatting code
+- Look at error message handling
+
+## Output Format
+
+For each investigated issue, provide:
+
+```markdown
+## Issue #NNN: [Title]
+
+**Status:** [FIXED | IMPLEMENTED | WON'T DO | SUPERSEDED | STILL VALID | NEEDS INFO]
+
+**Evidence:**
+- [What you found in the codebase]
+- [Relevant file paths and line numbers]
+- [Related commits if applicable]
+
+**Recommendation:** [Specific action to take]
+
+**Suggested Comment:** [Draft closure/update comment if applicable]
+```
+
+## Writing Closure Comments
+
+When recommending closure, provide a draft comment that is:
+- **Friendly and genuine** - not corporate-sounding
+- **Honest about reasoning** - explain the "why"
+- **Appreciative** - thank the reporter
+- **Open to revisiting** - leave door open if appropriate for "won't do" closures
+
+### Comment Templates
+
+**For FIXED issues:**
+```
+This has been fixed! [Brief explanation of what was changed]
+
+[Technical details if helpful]
+
+Closing this one out. Thanks for reporting!
+```
+
+**For WON'T DO (bandwidth/signals):**
+```
+Hey, thanks for [bringing this up / the suggestion]!
+
+We've been thinking about this, and unfortunately we don't have the bandwidth
+to take this on right now. We've also been watching for community signals,
+and honestly haven't seen [enough demand / many requests] for this.
+
+That said, if [condition for revisiting], we'd be open to reconsidering.
+[Or: if someone wants to contribute this, we'd review a PR!]
+
+For now, we're closing this out. Thanks again for [thinking of the project /
+your interest in ToolHive]!
+```
+
+**For SUPERSEDED:**
+```
+Wanted to give an update on this one.
+
+[Explanation of how direction changed or what replaced it]
+
+With that in mind, we're closing this out. If [condition], feel free to
+open a new issue!
+```
+
+## Tone Guidelines
+
+All communications should be **kind, helpful, and polite**. Remember that issue reporters took time to contribute feedback, and closure messages should reflect appreciation for their effort, even when declining requests.
+
+## Batch Triage Tips
+
+When triaging multiple issues:
+1. Group similar issues together (same component, same type)
+2. Investigate related issues in parallel when possible
+3. Note patterns (e.g., "all container networking issues seem fixed")
+4. Flag issues that might be duplicates
+
+## Example Investigation
+
+**Issue #362: "MacOS firewall dialog appearing frequently"**
+
+Investigation steps:
+1. Search for proxy binding code: `grep -r "Listen" pkg/transport/`
+2. Check default host configuration: look for `0.0.0.0` vs `127.0.0.1`
+3. Find the specific file mentioned in issue: `pkg/transport/proxy/httpsse/http_proxy.go`
+4. Verify current binding behavior
+
+Finding: Proxy now defaults to `127.0.0.1` (localhost) instead of `0.0.0.0`
+
+**Recommendation:** FIXED - Close with explanation of the fix and mention the `--host` flag for customization.

.github/workflows/claude.yml

@@ -41,6 +41,6 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@2316a9a8dbe4e7ac26008088f966f8c290e9a2e1 # v1
+        uses: anthropics/claude-code-action@8341a564b0c1693e9fa29c681852ee3714980098 # v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/test-e2e-lifecycle.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     env:
-      YARDSTICK_IMAGE: ghcr.io/stackloklabs/yardstick/yardstick-server:0.0.2
+      YARDSTICK_IMAGE: ghcr.io/stackloklabs/yardstick/yardstick-server:1.1.1
     defaults:
       run:
         shell: bash

cmd/thv-operator/api/v1alpha1/mcpexternalauthconfig_types.go

@@ -15,6 +15,10 @@ const (
 	// ExternalAuthTypeHeaderInjection is the type for custom header injection
 	ExternalAuthTypeHeaderInjection ExternalAuthType = "headerInjection"
 
+	// ExternalAuthTypeBearerToken is the type for bearer token authentication
+	// This allows authenticating to remote MCP servers using bearer tokens stored in Kubernetes Secrets
+	ExternalAuthTypeBearerToken ExternalAuthType = "bearerToken"
+
 	// ExternalAuthTypeUnauthenticated is the type for no authentication
 	// This should only be used for backends on trusted networks (e.g., localhost, VPC)
 	// or when authentication is handled by network-level security
@@ -29,7 +33,7 @@ type ExternalAuthType string
 // MCPServer resources in the same namespace.
 type MCPExternalAuthConfigSpec struct {
 	// Type is the type of external authentication to configure
-	// +kubebuilder:validation:Enum=tokenExchange;headerInjection;unauthenticated
+	// +kubebuilder:validation:Enum=tokenExchange;headerInjection;bearerToken;unauthenticated
 	// +kubebuilder:validation:Required
 	Type ExternalAuthType `json:"type"`
 
@@ -42,6 +46,11 @@ type MCPExternalAuthConfigSpec struct {
 	// Only used when Type is "headerInjection"
 	// +optional
 	HeaderInjection *HeaderInjectionConfig `json:"headerInjection,omitempty"`
+
+	// BearerToken configures bearer token authentication
+	// Only used when Type is "bearerToken"
+	// +optional
+	BearerToken *BearerTokenConfig `json:"bearerToken,omitempty"`
 }
 
 // TokenExchangeConfig holds configuration for RFC-8693 OAuth 2.0 Token Exchange.
@@ -102,6 +111,15 @@ type HeaderInjectionConfig struct {
 	ValueSecretRef *SecretKeyRef `json:"valueSecretRef"`
 }
 
+// BearerTokenConfig holds configuration for bearer token authentication.
+// This allows authenticating to remote MCP servers using bearer tokens stored in Kubernetes Secrets.
+// For security reasons, only secret references are supported (no plaintext values).
+type BearerTokenConfig struct {
+	// TokenSecretRef references a Kubernetes Secret containing the bearer token
+	// +kubebuilder:validation:Required
+	TokenSecretRef *SecretKeyRef `json:"tokenSecretRef"`
+}
+
 // SecretKeyRef is a reference to a key within a Secret
 type SecretKeyRef struct {
 	// Name is the name of the secret

cmd/thv-operator/api/v1alpha1/mcpexternalauthconfig_webhook.go

@@ -59,32 +59,70 @@ func (*MCPExternalAuthConfig) ValidateDelete(_ context.Context, _ runtime.Object
 func (r *MCPExternalAuthConfig) validate() error {
 	switch r.Spec.Type {
 	case ExternalAuthTypeTokenExchange:
-		if r.Spec.TokenExchange == nil {
-			return fmt.Errorf("tokenExchange configuration is required when type is 'tokenExchange'")
-		}
-		if r.Spec.HeaderInjection != nil {
-			return fmt.Errorf("headerInjection must not be set when type is 'tokenExchange'")
-		}
-
+		return r.validateTokenExchange()
 	case ExternalAuthTypeHeaderInjection:
-		if r.Spec.HeaderInjection == nil {
-			return fmt.Errorf("headerInjection configuration is required when type is 'headerInjection'")
-		}
-		if r.Spec.TokenExchange != nil {
-			return fmt.Errorf("tokenExchange must not be set when type is 'headerInjection'")
-		}
-
+		return r.validateHeaderInjection()
+	case ExternalAuthTypeBearerToken:
+		return r.validateBearerToken()
 	case ExternalAuthTypeUnauthenticated:
-		if r.Spec.TokenExchange != nil {
-			return fmt.Errorf("tokenExchange must not be set when type is 'unauthenticated'")
-		}
-		if r.Spec.HeaderInjection != nil {
-			return fmt.Errorf("headerInjection must not be set when type is 'unauthenticated'")
-		}
-
+		return r.validateUnauthenticated()
 	default:
 		return fmt.Errorf("unsupported auth type: %s", r.Spec.Type)
 	}
+}
 
+// validateTokenExchange validates tokenExchange type configuration
+func (r *MCPExternalAuthConfig) validateTokenExchange() error {
+	if r.Spec.TokenExchange == nil {
+		return fmt.Errorf("tokenExchange configuration is required when type is 'tokenExchange'")
+	}
+	if r.Spec.HeaderInjection != nil {
+		return fmt.Errorf("headerInjection must not be set when type is 'tokenExchange'")
+	}
+	if r.Spec.BearerToken != nil {
+		return fmt.Errorf("bearerToken must not be set when type is 'tokenExchange'")
+	}
+	return nil
+}
+
+// validateHeaderInjection validates headerInjection type configuration
+func (r *MCPExternalAuthConfig) validateHeaderInjection() error {
+	if r.Spec.HeaderInjection == nil {
+		return fmt.Errorf("headerInjection configuration is required when type is 'headerInjection'")
+	}
+	if r.Spec.TokenExchange != nil {
+		return fmt.Errorf("tokenExchange must not be set when type is 'headerInjection'")
+	}
+	if r.Spec.BearerToken != nil {
+		return fmt.Errorf("bearerToken must not be set when type is 'headerInjection'")
+	}
+	return nil
+}
+
+// validateBearerToken validates bearerToken type configuration
+func (r *MCPExternalAuthConfig) validateBearerToken() error {
+	if r.Spec.BearerToken == nil {
+		return fmt.Errorf("bearerToken configuration is required when type is 'bearerToken'")
+	}
+	if r.Spec.TokenExchange != nil {
+		return fmt.Errorf("tokenExchange must not be set when type is 'bearerToken'")
+	}
+	if r.Spec.HeaderInjection != nil {
+		return fmt.Errorf("headerInjection must not be set when type is 'bearerToken'")
+	}
+	return nil
+}
+
+// validateUnauthenticated validates unauthenticated type configuration
+func (r *MCPExternalAuthConfig) validateUnauthenticated() error {
+	if r.Spec.TokenExchange != nil {
+		return fmt.Errorf("tokenExchange must not be set when type is 'unauthenticated'")
+	}
+	if r.Spec.HeaderInjection != nil {
+		return fmt.Errorf("headerInjection must not be set when type is 'unauthenticated'")
+	}
+	if r.Spec.BearerToken != nil {
+		return fmt.Errorf("bearerToken must not be set when type is 'unauthenticated'")
+	}
 	return nil
 }