Package com.tnsai.agents.validation.validators

Class MCPServerReachabilityValidator

java.lang.Object
com.tnsai.agents.validation.validators.MCPServerReachabilityValidator
All Implemented Interfaces:
ReachabilityValidator, Validator
public final class MCPServerReachabilityValidator extends Object implements ReachabilityValidator
AGENT-V011 — opt-in reachability probe for every MCP server URL referenced by an @MCPTool action across the agent's roles.

Runs only when AgentBuilder.withReachabilityChecks(true) is set. Catches the case where the agent builds fine, the LLM decides to call an MCP tool, and the first dispatch hangs because the server URL was a typo, the firewall blocks the route, or the MCP server isn't running.

Architecture: cross-module via SPI

The MCP initialize handshake lives in tnsai-mcp, which depends on tnsai-core (not the other way round). This validator inverts the dependency through the McpClientFactory SPI: tnsai-mcp ships an implementation under META-INF/services/com.tnsai.spi.McpClientFactory, this validator discovers it through SpiLoader at probe time, and adapts each URL to a Healthcheckable that runs the MCP handshake.

Behaviour matrix

Probe outcomes
StateOutcome
No role declares an MCP_TOOL action Silent — nothing to probe
MCP_TOOL actions present but no McpClientFactory on the classpath (consumer hasn't pulled tnsai-mcp) Silent — graceful degradation; the consumer is presumably resolving MCP URLs by some out-of-band mechanism
All probes return reachable=true Silent
One or more probes return reachable=false One WARNING per unreachable URL with the server-supplied error and observed latency
Factory throws while building the probe, or probe throws (contract violation) WARNING for that URL; never propagates the exception

Severity is WARNING under the soft-launch convention shared by V005/V010 — networks blip, the user opted in, a transient failure shouldn't block the build. Suppress with .relaxValidation("AGENT-V011") when probe-time and runtime MCP servers legitimately diverge (e.g. CI builds against staging, runtime against production).

Since:
0.8.5 (issue #237)

  • Constructor Details

    • MCPServerReachabilityValidator

      public MCPServerReachabilityValidator()
      Production constructor. Discovery is deferred until validation reaches an MCP URL so disabled reachability checks do not initialize optional providers.

  • Method Details

    • id

      public String id()
      Description copied from interface: Validator
      Short, stable id for logging and test assertions (e.g. "llm-presence").
      Specified by:
      id in interface Validator

    • validate

      public List<ValidationIssue> validate(ValidationContext ctx)
      Description copied from interface: Validator
      Inspect the agent configuration and return any issues detected. Returning an empty list means "no problems found by this validator".
      Specified by:
      validate in interface Validator
      Parameters:
      ctx - frozen view of the agent under construction
      Returns:
      zero-or-more issues; never null