Diagnostic Tools

Tools for health checks, readiness probes, and workflow guidance.

ping

Quick health check - returns immediately if server is responding.

Parameters

None.

Response


{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z"
}

Use Cases

Quick liveness check
Verify MCP connection
Debugging connectivity issues

get_server_health

Detailed health status of all server components.

Parameters

None.

Response


{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "components": {
    "database": {
      "status": "healthy",
      "details": {
        "codes_loaded": 2125,
        "index_terms": 20398,
        "cross_references": 1847
      }
    },
    "embeddings": {
      "status": "healthy",
      "details": {
        "model": "all-MiniLM-L6-v2",
        "dimensions": 384,
        "codes_embedded": 2125
      }
    },
    "search_engine": {
      "status": "healthy",
      "details": {
        "semantic_ready": true,
        "lexical_ready": true,
        "hybrid_available": true
      }
    },
    "workbook": {
      "status": "healthy",
      "details": {
        "entries": 47
      }
    }
  },
  "uptime_seconds": 3600,
  "version": "1.0.0"
}

Component Status Values

Status	Meaning
`healthy`	Component is fully operational
`degraded`	Component works but with limitations
`unhealthy`	Component is not functioning
`loading`	Component is initializing

Use Cases

Detailed diagnostics
Troubleshooting issues
Monitoring dashboards
Initial setup verification

check_readiness

Kubernetes-style readiness check. Returns whether the server is ready to accept requests.

Parameters

None.

Response

When ready:


{
  "ready": true,
  "checks": {
    "database": "pass",
    "embeddings": "pass",
    "search": "pass"
  }
}

When not ready:


{
  "ready": false,
  "checks": {
    "database": "pass",
    "embeddings": "loading",
    "search": "waiting"
  },
  "message": "Embeddings still loading, please wait"
}

Use Cases

Kubernetes readiness probes
Load balancer health checks
Startup verification
Automated testing

Readiness vs Liveness

Check	Tool	Purpose
Liveness	`ping`	Is the server responding?
Readiness	`check_readiness`	Is the server ready for traffic?

get_workflow_guide

Get guidance on classification workflows. Returns structured instructions for different scenarios.

Parameters

Parameter	Type	Required	Default	Description
`workflow`	string	No	`"standard"`	Workflow type

Workflow Types

Type	Description
`standard`	Basic classification workflow
`exploratory`	When unsure about the right code
`validation`	Verifying an existing classification
`batch`	Processing multiple descriptions
`audit`	Creating audit trails
`hierarchy`	Exploring NAICS structure
`comparison`	Comparing multiple codes

Response


{
  "workflow": "standard",
  "title": "Standard Classification Workflow",
  "description": "Use this workflow for straightforward business classification",
  "steps": [
    {
      "step": 1,
      "action": "classify_business",
      "description": "Get initial classification with reasoning",
      "parameters": {
        "description": "[business description]",
        "include_reasoning": true,
        "check_cross_refs": true
      }
    },
    {
      "step": 2,
      "action": "evaluate_confidence",
      "description": "Check confidence score",
      "conditions": [
        {
          "if": "confidence >= 0.75",
          "then": "Present recommendation to user"
        },
        {
          "if": "confidence < 0.75",
          "then": "Proceed to step 3"
        }
      ]
    },
    {
      "step": 3,
      "action": "get_alternatives",
      "description": "Get sibling codes for alternatives",
      "tools": ["get_siblings", "find_similar_industries"]
    },
    {
      "step": 4,
      "action": "present_options",
      "description": "Present top options with explanations"
    }
  ],
  "tips": [
    "Always check cross-references for exclusions",
    "Prefer 6-digit codes when available",
    "Ask clarifying questions for vague descriptions"
  ]
}

Example


{
  "workflow": "validation"
}

Response for Validation Workflow


{
  "workflow": "validation",
  "title": "Validation Workflow",
  "steps": [
    {
      "step": 1,
      "action": "validate_classification",
      "parameters": {
        "description": "[business description]",
        "proposed_code": "[code to validate]"
      }
    },
    {
      "step": 2,
      "action": "check_result",
      "conditions": [
        {
          "if": "valid == true",
          "then": "Confirm classification with any caveats"
        },
        {
          "if": "valid == false",
          "then": "Explain why and suggest alternatives"
        }
      ]
    },
    {
      "step": 3,
      "action": "get_cross_references",
      "description": "Check for edge cases and exclusions"
    }
  ]
}

HTTP Endpoints

In addition to MCP tools, the server exposes HTTP endpoints for infrastructure integration:

Endpoint	Purpose	Tool Equivalent
`GET /health`	Liveness probe	`ping`
`GET /ready`	Readiness probe	`check_readiness`
`GET /status`	Detailed status	`get_server_health`
`GET /metrics`	Prometheus metrics	—

Kubernetes Configuration


livenessProbe:
  httpGet:
    path: /health
    port: 9090
  initialDelaySeconds: 5
  periodSeconds: 10
 
readinessProbe:
  httpGet:
    path: /ready
    port: 9090
  initialDelaySeconds: 10
  periodSeconds: 5

Troubleshooting

Server Not Ready

If check_readiness returns ready: false:

Check which component is not ready
For embeddings: loading, wait for initialization (usually < 60 seconds)
For database: unhealthy, check data initialization
Check logs for error messages

Component Degraded

If get_server_health shows status: degraded:

Identify the degraded component
The server can still handle requests, but with limitations
Example: lexical search only if semantic search is degraded

Connection Issues

If ping fails:

Verify server is running
Check MCP client configuration
Verify network connectivity
Check for port conflicts