///|
/// Case-sensitive, fail-closed routing from MCP tool names to input schemas.
/// Registration validates the same schema subset as [validate] and copies each
/// definition, so changing the input JSON later does not change the guard.
pub struct ToolSchemaRegistry {
priv schemas : Map[String, Json]
}
///|
/// Start with an empty registry. Tools are denied until explicitly registered.
pub fn ToolSchemaRegistry::new() -> ToolSchemaRegistry {
{ schemas: Map([]), }
}
///|
/// Register one nonempty tool name and a valid input schema. A duplicate name
/// returns an error and keeps the existing route.
pub fn ToolSchemaRegistry::register(
self : ToolSchemaRegistry,
name : String,
schema : JsonValue,
) -> Result[Unit, ValidationError] {
let path = schema_key_path("$schema", name)
if name.is_empty() {
return Err({
path,
keyword: "name",
message: "expected a nonempty tool name",
})
}
if self.schemas.contains(name) {
return Err({
path,
keyword: "duplicate",
message: "tool already registered",
})
}
let errors = []
check_schema(schema, path, 0, errors)
if errors.get(0) is Some(error) {
return Err(error)
}
self.schemas[name] = clone_patch_value(schema)
Ok(())
}
///|
/// Build a registry from a JSON object keyed by tool name. For example,
/// {"write_file":{"type":"object","required":["path"]}} registers one tool.
/// An invalid definition rejects the entire map.
pub fn ToolSchemaRegistry::from_json(
schemas : JsonValue,
) -> Result[ToolSchemaRegistry, ValidationError] {
guard schemas is Object(fields) else {
return Err({
path: "$schema",
keyword: "type",
message: "expected an object mapping tool names to input schemas",
})
}
let registry = ToolSchemaRegistry::new()
let names = fields.keys().collect()
names.sort_by(String::lexical_compare)
for name in names {
if registry.register(name, fields[name]) is Err(error) {
return Err(error)
}
}
Ok(registry)
}
///|
/// Counts of edits to the incoming frame, repairs inside stringified
/// arguments, and optional schema-directed coercions, respectively.
#derive(Eq, Debug, ToJson)
pub struct McpGuardAudit {
envelope_edits : Int32
argument_edits : Int32
coercions : Int32
}
///|
/// Routing decision for one JSON-RPC frame. With [forward] true, send [frame]
/// to the server. Otherwise, route any [frame] back to the requesting client.
/// A rejected notification has an [error_code] but no wire reply.
/// [tool] is set when the frame identifies a tool by name.
#derive(Eq, Debug, ToJson)
pub struct McpGuardResult {
forward : Bool
frame : String?
tool : String?
audit : McpGuardAudit
error_code : Int32?
}
///|
let mcp_argument_path : String = "$.params.arguments"
///|
fn mcp_error_frame(
code : Int32,
message : String,
id : Json?,
tool : String?,
issues : Array[ValidationError],
retry : String,
audit : McpGuardAudit,
) -> McpGuardResult {
let frame = id.map(id => {
let count = issues.length().min(retry_issue_limit)
let visible = Array::makei(count, index => @json.to_json(issues[index]))
let details : Map[String, Json] = {
"issues": Json::array(visible),
"retry_prompt": Json::string(retry),
}
if count < issues.length() {
details["remaining"] = Json::number((issues.length() - count).to_double())
}
let error : Json = {
"code": Json::number(code.to_double()),
"message": Json::string(message),
"data": Json::object(details),
}
let response : Json = { "jsonrpc": "2.0", "id": id, "error": error }
response.stringify()
})
{ forward: false, frame, tool, audit, error_code: Some(code), }
}
///|
fn mcp_structure_error(
code : Int32,
id : Json?,
path : String,
keyword : String,
detail : String,
audit : McpGuardAudit,
tool~ : String? = None,
) -> McpGuardResult {
let message = match code {
-32700 => "Parse error"
-32600 => "Invalid Request"
_ => "Invalid params"
}
let issue : ValidationError = { path, keyword, message: detail, }
mcp_error_frame(
code,
message,
id,
tool,
[issue],
"Fix \{path}: \{detail}",
audit,
)
}
///|
fn is_mcp_id(id : Json) -> Bool {
id is String(_) || schema_matches_type(id, "integer")
}
///|
fn is_mcp_error(error : Json) -> Bool {
guard error is Object(fields) else { return false }
guard fields.get("message") is Some(String(_)) &&
fields.get("code") is Some(code) else {
return false
}
schema_matches_type(code, "integer")
}
///|
fn is_mcp_response(fields : Map[String, Json], id : Json?) -> Bool {
match (fields.get("result"), fields.get("error")) {
(Some(Object(_)), None) => id is Some(reply_id) && is_mcp_id(reply_id)
(None, Some(error)) =>
(
id is (None | Some(Null)) ||
(id is Some(reply_id) && is_mcp_id(reply_id))
) &&
is_mcp_error(error)
_ => false
}
}
///|
fn mcp_wire_text(source : String, report : RepairReport) -> String {
// Keep valid one-line input untouched, including numeric and string lexemes.
// Compact physical line breaks to preserve stdio's one-message-per-line rule.
if report.edits.is_empty() && !source.contains("\n") && !source.contains("\r") {
source
} else {
report.json
}
}
///|
fn mcp_forward(
frame : String,
audit : McpGuardAudit,
tool~ : String? = None,
) -> McpGuardResult {
{ forward: true, frame: Some(frame), tool, audit, error_code: None, }
}
///|
fn guard_mcp_arguments(
raw : Json,
id : Json?,
tool : String,
policy : RepairPolicy,
audit : McpGuardAudit,
) -> Result[(Json, Bool, McpGuardAudit), McpGuardResult] {
let (value, unwrapped, audit) = match raw {
String(embedded) =>
match repair_with_policy(embedded, policy) {
Ok(report) =>
(
report.value,
true,
{ ..audit, argument_edits: report.edits.length(), },
)
Err(error) =>
return Err(
mcp_structure_error(
-32602,
id,
mcp_argument_path,
error.kind.code(),
"expected an encoded JSON object",
audit,
tool=Some(tool),
),
)
}
_ => (raw, false, audit)
}
guard value is Object(_) else {
return Err(
mcp_structure_error(
-32602,
id,
mcp_argument_path,
"type",
"expected an arguments object",
audit,
tool=Some(tool),
),
)
}
Ok((value, unwrapped, audit))
}
///|
fn guard_mcp_invocation(
fields : Map[String, Json],
id : Json?,
registry : ToolSchemaRegistry,
policy : RepairPolicy,
coerce : Bool,
wire : String,
audit : McpGuardAudit,
) -> McpGuardResult {
guard id is Some(_) else {
return mcp_structure_error(
-32602,
None,
"$.id",
"required",
"tools/call requires an id",
audit,
)
}
guard fields.get("params") is Some(Object(parameters)) else {
return mcp_structure_error(
-32602, id, "$.params", "type", "expected a params object", audit,
)
}
guard parameters.get("name") is Some(String(tool)) && !tool.is_empty() else {
return mcp_structure_error(
-32602, id, "$.params.name", "type", "expected a nonempty tool name", audit,
)
}
guard registry.schemas.get(tool) is Some(schema) else {
return mcp_structure_error(
-32602,
id,
"$.params.name",
"registered",
"expected a registered tool name",
audit,
tool=Some(tool),
)
}
let raw = parameters.get("arguments").unwrap_or(Json::empty_object())
let (value, unwrapped, audit) = match
guard_mcp_arguments(raw, id, tool, policy, audit) {
Ok(decoded) => decoded
Err(result) => return result
}
let (value, errors, audit) = if coerce {
let report = coerce_with_schema(value, schema)
(
report.value,
report.errors,
{ ..audit, coercions: report.edits.length(), },
)
} else {
(value, validate(value, schema), audit)
}
if !errors.is_empty() {
let issues = errors.map(error => {
let suffix = error.path[:].exact_view(start=1)
{ ..error, path: mcp_argument_path + suffix.to_owned(), }
})
return mcp_error_frame(
-32602,
"Invalid params",
id,
Some(tool),
issues,
format_retry_prompt(value, schema),
audit,
)
}
if !unwrapped && audit.coercions == 0 {
return mcp_forward(wire, audit, tool=Some(tool))
}
let next_parameters = parameters.copy()
next_parameters["arguments"] = value
let next_fields = fields.copy()
next_fields["params"] = Json::object(next_parameters)
mcp_forward(Json::object(next_fields).stringify(), audit, tool=Some(tool))
}
///|
/// Repair and route a single inbound MCP JSON-RPC 2.0 frame. Known tools must
/// pass their registered input schema. Stringified arguments are repaired and
/// unwrapped once. Enable [coerce] to apply explicit schema-directed type
/// conversions. Successful unchanged one-line frames retain their wire bytes.
///
/// Irreparable JSON returns -32700, invalid envelopes return -32600, and
/// rejected tool parameters return -32602. Notifications cannot receive
/// replies. The guard never spawns a transport or authorizes tool execution.
pub fn guard_mcp_tool_call(
source : String,
registry : ToolSchemaRegistry,
policy~ : RepairPolicy = RepairPolicy::default(),
coerce~ : Bool = false,
) -> McpGuardResult {
let audit = { envelope_edits: 0, argument_edits: 0, coercions: 0, }
let report = match repair_with_policy(source, policy) {
Ok(report) => report
Err(error) =>
return mcp_structure_error(
-32700,
Some(Json::null()),
"$",
error.kind.code(),
"expected one repairable JSON-RPC object",
audit,
)
}
let audit = { ..audit, envelope_edits: report.edits.length(), }
let unknown = Some(Json::null())
guard report.value is Object(fields) else {
return mcp_structure_error(
-32600, unknown, "$", "type", "expected one JSON-RPC object", audit,
)
}
guard fields.get("jsonrpc") is Some(String("2.0")) else {
return mcp_structure_error(
-32600, unknown, "$.jsonrpc", "version", "expected JSON-RPC 2.0", audit,
)
}
let wire = mcp_wire_text(source, report)
let id = fields.get("id")
let procedure = fields.get("method")
// Valid replies can travel through this filter in the reverse direction.
if procedure is None && is_mcp_response(fields, id) {
return mcp_forward(wire, audit)
}
guard procedure is Some(String(name)) &&
!name.is_empty() &&
!fields.contains("result") &&
!fields.contains("error") else {
return mcp_structure_error(
-32600, unknown, "$.method", "type", "expected a JSON-RPC method", audit,
)
}
if id is Some(request_id) && !is_mcp_id(request_id) {
return mcp_structure_error(
-32600, unknown, "$.id", "type", "expected a string or integer id", audit,
)
}
if name == "tools/call" {
return guard_mcp_invocation(
fields, id, registry, policy, coerce, wire, audit,
)
}
if fields.get("params") is Some(parameters) && !(parameters is Object(_)) {
return mcp_structure_error(
-32602, id, "$.params", "type", "expected a params object", audit,
)
}
mcp_forward(wire, audit)
}