verify fixes are working

Signed-off-by: Huamin Chen <[email protected]>

Author: rootfs

examples/mcp-classifier-server/README.md

@@ -62,11 +62,41 @@ default_model: openai/gpt-oss-20b
 
 **Tool Auto-Discovery:**
 The router automatically discovers classification tools from the MCP server by:
+
 1. Listing available tools on connection
 2. Looking for common names: `classify_text`, `classify`, `categorize`, `categorize_text`
 3. Pattern matching for tools containing "classif" in name/description
 4. Optionally specify `tool_name` to use a specific tool
 
+## Protocol API
+
+This server implements the MCP classification protocol defined in:
+
+```
+github.com/vllm-project/semantic-router/src/semantic-router/pkg/connectivity/mcp/api
+```
+
+**Required Tools:**
+
+1. **`list_categories`** - Returns `ListCategoriesResponse`:
+
+   ```json
+   {"categories": ["math", "science", "technology", ...]}
+   ```
+
+2. **`classify_text`** - Returns `ClassifyResponse`:
+
+   ```json
+   {
+     "class": 1,
+     "confidence": 0.85,
+     "model": "openai/gpt-oss-20b",
+     "use_reasoning": true
+   }
+   ```
+
+See the `api` package for full type definitions and documentation.
+
 ## How It Works
 
 **Intelligent Routing Rules:**
@@ -77,17 +107,6 @@ The router automatically discovers classification tools from the MCP server by:
 - Low confidence (<0.6) → `use_reasoning: true`
 - Default → `use_reasoning: true`
 
-**Response Format:**
-
-```json
-{
-  "class": 1,
-  "confidence": 0.85,
-  "model": "openai/gpt-oss-20b",
-  "use_reasoning": true
-}
-```
-
 ## Customization
 
 Edit `CATEGORIES` to add categories:

examples/mcp-classifier-server/server.py

@@ -530,7 +530,7 @@ async def health_check(request):
     parser.add_argument(
         "--http", action="store_true", help="Run in HTTP mode instead of stdio"
     )
-    parser.add_argument("--port", type=int, default=8090, help="HTTP port")
+    parser.add_argument("--port", type=int, default=8090, help="HTTP port to listen on")
     args = parser.parse_args()
 
     if args.http:

src/semantic-router/pkg/services/classification.go

@@ -85,9 +85,9 @@ func createLegacyClassifier(config *config.RouterConfig) (*classification.Classi
 	var categoryMapping *classification.CategoryMapping
 
 	// Check if we should load categories from MCP server
+	// Note: tool_name is optional and will be auto-discovered if not specified
 	useMCPCategories := config.Classifier.CategoryModel.ModelID == "" &&
-		config.Classifier.MCPCategoryModel.Enabled &&
-		config.Classifier.MCPCategoryModel.ToolName != ""
+		config.Classifier.MCPCategoryModel.Enabled
 
 	if useMCPCategories {
 		// Categories will be loaded from MCP server during initialization

src/semantic-router/pkg/utils/classification/mcp_classifier.go

@@ -11,6 +11,7 @@ import (
 	candle_binding "github.com/vllm-project/semantic-router/candle-binding"
 	"github.com/vllm-project/semantic-router/src/semantic-router/pkg/config"
 	mcpclient "github.com/vllm-project/semantic-router/src/semantic-router/pkg/connectivity/mcp"
+	"github.com/vllm-project/semantic-router/src/semantic-router/pkg/connectivity/mcp/api"
 	"github.com/vllm-project/semantic-router/src/semantic-router/pkg/metrics"
 	"github.com/vllm-project/semantic-router/src/semantic-router/pkg/observability"
 	"github.com/vllm-project/semantic-router/src/semantic-router/pkg/utils/entropy"
@@ -45,7 +46,21 @@ type MCPCategoryInference interface {
 	ListCategories(ctx context.Context) (*CategoryMapping, error)
 }
 
-// MCPCategoryClassifier implements both MCPCategoryInitializer and MCPCategoryInference
+// MCPCategoryClassifier implements both MCPCategoryInitializer and MCPCategoryInference.
+//
+// Protocol Contract:
+// This client relies on the MCP server to respect the protocol defined in the
+// github.com/vllm-project/semantic-router/src/semantic-router/pkg/connectivity/mcp/api package.
+//
+// The MCP server must implement these tools:
+//  1. list_categories - Returns api.ListCategoriesResponse
+//  2. classify_text - Returns api.ClassifyResponse or api.ClassifyWithProbabilitiesResponse
+//
+// The MCP server controls both classification AND routing decisions. When the server returns
+// "model" and "use_reasoning" in the classification response, the router will use those values.
+// If not provided, the router falls back to the default_model configuration.
+//
+// For detailed type definitions and examples, see the api package documentation.
 type MCPCategoryClassifier struct {
 	client   mcpclient.MCPClient
 	toolName string
@@ -202,13 +217,8 @@ func (m *MCPCategoryClassifier) Classify(ctx context.Context, text string) (cand
 		return candle_binding.ClassResult{}, fmt.Errorf("MCP tool returned non-text content")
 	}
 
-	// Parse JSON response: {"class": int, "confidence": float, "model": str, "use_reasoning": bool}
-	var response struct {
-		Class        int     `json:"class"`
-		Confidence   float32 `json:"confidence"`
-		Model        string  `json:"model,omitempty"`
-		UseReasoning *bool   `json:"use_reasoning,omitempty"`
-	}
+	// Parse JSON response using the API type
+	var response api.ClassifyResponse
 	if err := json.Unmarshal([]byte(responseText), &response); err != nil {
 		return candle_binding.ClassResult{}, fmt.Errorf("failed to parse MCP response: %w", err)
 	}
@@ -256,14 +266,8 @@ func (m *MCPCategoryClassifier) ClassifyWithProbabilities(ctx context.Context, t
 		return candle_binding.ClassResultWithProbs{}, fmt.Errorf("MCP tool returned non-text content")
 	}
 
-	// Parse JSON response: {"class": int, "confidence": float, "probabilities": []float, "model": str, "use_reasoning": bool}
-	var response struct {
-		Class         int       `json:"class"`
-		Confidence    float32   `json:"confidence"`
-		Probabilities []float32 `json:"probabilities"`
-		Model         string    `json:"model,omitempty"`
-		UseReasoning  *bool     `json:"use_reasoning,omitempty"`
-	}
+	// Parse JSON response using the API type
+	var response api.ClassifyWithProbabilitiesResponse
 	if err := json.Unmarshal([]byte(responseText), &response); err != nil {
 		return candle_binding.ClassResultWithProbs{}, fmt.Errorf("failed to parse MCP response: %w", err)
 	}
@@ -306,10 +310,8 @@ func (m *MCPCategoryClassifier) ListCategories(ctx context.Context) (*CategoryMa
 		return nil, fmt.Errorf("MCP tool returned non-text content")
 	}
 
-	// Parse JSON response: {"categories": ["cat1", "cat2", ...]}
-	var response struct {
-		Categories []string `json:"categories"`
-	}
+	// Parse JSON response using the API type
+	var response api.ListCategoriesResponse
 	if err := json.Unmarshal([]byte(responseText), &response); err != nil {
 		return nil, fmt.Errorf("failed to parse MCP categories response: %w", err)
 	}
@@ -342,10 +344,10 @@ func createMCPCategoryInference(initializer MCPCategoryInitializer) MCPCategoryI
 	return nil
 }
 
-// IsMCPCategoryEnabled checks if MCP-based category classification is properly configured
+// IsMCPCategoryEnabled checks if MCP-based category classification is properly configured.
+// Note: tool_name is optional and will be auto-discovered during initialization if not specified.
 func (c *Classifier) IsMCPCategoryEnabled() bool {
-	return c.Config.Classifier.MCPCategoryModel.Enabled &&
-		c.Config.Classifier.MCPCategoryModel.ToolName != ""
+	return c.Config.Classifier.MCPCategoryModel.Enabled
 }
 
 // initializeMCPCategoryClassifier initializes the MCP category classification model
@@ -455,13 +457,8 @@ func (c *Classifier) classifyCategoryMCPWithRouting(text string) (*MCPClassifica
 		return nil, fmt.Errorf("MCP tool returned non-text content")
 	}
 
-	// Parse JSON response with routing information
-	var response struct {
-		Class        int     `json:"class"`
-		Confidence   float32 `json:"confidence"`
-		Model        string  `json:"model,omitempty"`
-		UseReasoning *bool   `json:"use_reasoning,omitempty"`
-	}
+	// Parse JSON response with routing information using the API type
+	var response api.ClassifyResponse
 	if err := json.Unmarshal([]byte(responseText), &response); err != nil {
 		return nil, fmt.Errorf("failed to parse MCP response: %w", err)
 	}

src/semantic-router/pkg/utils/classification/mcp_classifier_test.go

@@ -431,14 +431,10 @@ var _ = Describe("Classifier MCP Methods", func() {
 			Expect(classifier.IsMCPCategoryEnabled()).To(BeFalse())
 		})
 
-		It("should return false when tool name is empty", func() {
-			classifier.Config.Classifier.MCPCategoryModel.ToolName = ""
-			Expect(classifier.IsMCPCategoryEnabled()).To(BeFalse())
-		})
-
-		// Note: IsMCPCategoryEnabled now only checks configuration, not runtime state.
-		// Runtime checks (like initializer != nil) are handled separately in the actual
-		// classification methods to maintain separation of concerns.
+		// Note: tool_name is now optional and will be auto-discovered if not specified.
+		// IsMCPCategoryEnabled only checks if MCP is enabled, not specific configuration details.
+		// Runtime checks (like initializer != nil or successful connection) are handled
+		// separately in the actual initialization and classification methods.
 	})
 
 	Describe("classifyCategoryMCP", func() {