mcp_tool_schema.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. """MCP tool schema conversion and naming: JSON-schema normalisation for provider
  2. compatibility, mcp__server__tool naming, utility-tool schemas, include/exclude filters and
  3. description injection scanning."""
  4. import logging
  5. import hashlib
  6. import fnmatch
  7. import re
  8. from typing import Any, List
  9. from tools.ansi_strip import strip_unicode_tags
  10. from tools.mcp_tool_common import mcp_field
  11. logger = logging.getLogger("tools.mcp_tool")
  12. # Prompt-injection indicators in MCP tool descriptions. WARNING-level only: log but never
  13. # block, since false positives would break legitimate servers.
  14. _MCP_INJECTION_PATTERNS = [
  15. (re.compile(pattern, re.IGNORECASE), reason)
  16. for pattern, reason in (
  17. (r"ignore\s+(all\s+)?previous\s+instructions", "prompt override attempt ('ignore previous instructions')"),
  18. (r"you\s+are\s+now\s+a", "identity override attempt ('you are now a...')"),
  19. (r"your\s+new\s+(task|role|instructions?)\s+(is|are)", "task override attempt"),
  20. (r"system\s*:\s*", "system prompt injection attempt"),
  21. (r"<\s*(system|human|assistant)\s*>", "role tag injection attempt"),
  22. (r"do\s+not\s+(tell|inform|mention|reveal)", "concealment instruction"),
  23. (r"(curl|wget|fetch)\s+https?://", "network command in description"),
  24. (r"base64\.(b64decode|decodebytes)", "base64 decode reference"),
  25. (r"exec\s*\(|eval\s*\(", "code execution reference"),
  26. (r"import\s+(subprocess|os|shutil|socket)", "dangerous import reference"))]
  27. def _scan_mcp_description(server_name: str, tool_name: str, description: str) -> list[str]:
  28. """Scan a tool description for injection patterns; returns finding strings (empty =
  29. clean) and logs a warning when any match."""
  30. if not description:
  31. return []
  32. findings = [reason for pattern, reason in _MCP_INJECTION_PATTERNS if pattern.search(description)]
  33. if findings:
  34. logger.warning("MCP server '%s' tool '%s': suspicious description content — %s. Description: %.200s",
  35. server_name, tool_name, "; ".join(findings), description)
  36. return findings
  37. _EMPTY_OBJECT_SCHEMA = {"type": "object", "properties": {}}
  38. def _rewrite_local_refs(node):
  39. """Promote legacy ``definitions`` to ``$defs`` (Moonshot rejects the draft-07 form) — ONLY
  40. where it is a JSON Schema meta-keyword, never as a property NAME inside
  41. ``properties``/``patternProperties``: a parameter legitimately named ``definitions``
  42. rewritten to ``$defs`` would 400 the whole tool array (Anthropic/OpenAI forbid ``$`` in
  43. property names)."""
  44. if isinstance(node, list):
  45. return [_rewrite_local_refs(item) for item in node]
  46. if not isinstance(node, dict):
  47. return node
  48. normalized = {}
  49. for key, value in node.items():
  50. if key in ("properties", "patternProperties") and isinstance(value, dict):
  51. normalized[key] = {name: _rewrite_local_refs(schema) for name, schema in value.items()}
  52. else:
  53. normalized["$defs" if key == "definitions" else key] = _rewrite_local_refs(value)
  54. ref = normalized.get("$ref")
  55. if isinstance(ref, str) and ref.startswith("#/definitions/"):
  56. normalized["$ref"] = "#/$defs/" + ref[len("#/definitions/"):]
  57. return normalized
  58. # Mapping-valued JSON Schema keywords: the value maps entry NAMES to schemas and is never a
  59. # schema node itself. Repair must recurse into the map's values only (#110530).
  60. _SCHEMA_MAP_KEYS = ("properties", "patternProperties", "$defs", "definitions", "dependentSchemas")
  61. def _repair_object_shape(node, *, _object_root=False):
  62. """Recursively fill a missing object ``type``, ensure ``properties`` (so ``required``
  63. can't dangle) and prune ``required`` to names present in ``properties`` (Gemini 400s
  64. otherwise).
  65. A dict carrying ``required`` but declaring no ``properties`` and no ``type`` is NOT an
  66. object declaration — it is a *constraint fragment*, the JSON Schema idiom for "at least
  67. one of these keys must be present" (``allOf``/``oneOf``/``anyOf``/``if`` branches).
  68. Synthesising ``properties: {}`` for it prunes every name out of ``required``, so sibling
  69. branches collapse into identical always-true schemas; the enclosing ``oneOf`` then has
  70. two matches and can never be satisfied, making the tool permanently un-dispatchable while
  71. the server-side tool itself is fine. Only the parameters-schema ROOT still gets the
  72. dangling-``required`` repair (``_object_root``), because that is the single node handed
  73. to providers as the function's argument object.
  74. """
  75. if isinstance(node, list):
  76. return [_repair_object_shape(item) for item in node]
  77. if not isinstance(node, dict):
  78. return node
  79. repaired = {}
  80. for key, value in node.items():
  81. if key in _SCHEMA_MAP_KEYS and isinstance(value, dict):
  82. # A schema map (entry name -> schema), never a schema node itself: recursing over
  83. # the whole map would inject a bogus ``"type": "object"`` *entry* when one of its
  84. # keys is literally named ``properties``/``required`` (#110530).
  85. repaired[key] = {name: _repair_object_shape(schema) for name, schema in value.items()}
  86. else:
  87. repaired[key] = _repair_object_shape(value)
  88. # Constraint fragments are returned untouched: repairing them is what destroys them.
  89. if _object_root or "properties" in repaired or "type" in node:
  90. if not repaired.get("type") and ("properties" in repaired or "required" in repaired):
  91. repaired["type"] = "object"
  92. if repaired.get("type") == "object":
  93. if not isinstance(repaired.get("properties"), dict):
  94. repaired["properties"] = {}
  95. # Always a list: a missing/non-list ``required`` reads as ``null`` on strict
  96. # OpenAI-compatible backends (#56123); ``[]`` is valid everywhere (Gemini included).
  97. required = repaired.get("required")
  98. props = repaired.get("properties") or {}
  99. repaired["required"] = ([r for r in required if isinstance(r, str) and r in props]
  100. if isinstance(required, list) else [])
  101. return repaired
  102. # Lazy (schema-cache registered) servers are available: the first real call spawns/connects them (#56832).
  103. def _normalize_mcp_input_schema(schema: dict | None) -> dict:
  104. """Normalize MCP input schemas so one form is valid on OpenAI, Anthropic, Gemini and
  105. Moonshot. Order matters: ``definitions`` -> ``$defs``; nullable ``anyOf`` unions collapsed
  106. to the non-null branch (Anthropic rejects nullable branches; optionality lives in the
  107. parent's ``required``; the ``nullable: true`` hint is kept so runtime coercion can map a
  108. model-emitted ``"null"`` string to ``None``); same-typed const unions -> enum (AFTER the
  109. nullable strip); then object-shape repair.
  110. * Missing or ``null`` ``type`` on an object-shaped node is coerced to ``"object"`` (some servers omit
  111. it). See PR #4897. * When an ``object`` node lacks ``properties``, an empty ``properties`` dict is added
  112. so ``required`` entries don't dangle. * ``required`` arrays are pruned to only names that exist in
  113. ``properties``; otherwise Google AI Studio / Gemini 400s with ``property is not defined``. See PR #4651.
  114. * MCP/Pydantic optional fields commonly arrive as ``anyOf: [{...}, {"type": "null"}], default: null``.
  115. """
  116. if not schema:
  117. return dict(_EMPTY_OBJECT_SCHEMA)
  118. from tools.schema_sanitizer import collapse_const_unions, strip_nullable_unions
  119. normalized = _rewrite_local_refs(schema)
  120. normalized = strip_nullable_unions(normalized, keep_nullable_hint=True)
  121. normalized = collapse_const_unions(normalized)
  122. normalized = _repair_object_shape(normalized, _object_root=True)
  123. if not isinstance(normalized, dict):
  124. return dict(_EMPTY_OBJECT_SCHEMA)
  125. if normalized.get("type") == "object" and "properties" not in normalized:
  126. normalized = {**normalized, "properties": {}}
  127. return normalized
  128. def sanitize_mcp_name_component(value: str) -> str:
  129. """Replace every char outside ``[A-Za-z0-9_]`` with ``_`` (hyphens included, the
  130. historical behavior) so generated names pass provider validation."""
  131. return re.sub(r"[^A-Za-z0-9_]", "_", str(value or ""))
  132. # ``mcp__<server>__<tool>``: the convention shared by Claude Code, Codex and OpenCode. The
  133. # double underscore disambiguates the server/tool boundary even when either contains
  134. # underscores, and matches the Anthropic-OAuth wire form.
  135. # Native MCP tool-name prefix. It also aligns native registration with the Anthropic-OAuth wire form
  136. # (``_MCP_TOOL_PREFIX`` in anthropic_adapter.py), removing the single->double rewrite that path previously
  137. # had to perform. See #33533.
  138. MCP_TOOL_NAME_PREFIX = "mcp__"
  139. # OpenAI-compatible providers validate function names against ``^[a-zA-Z0-9_-]{1,64}$`` and 400 the
  140. # whole request when one generated name is longer. Portable plugin server keys fold the plugin name in
  141. # several times, so ``mcp__<server>__<tool>`` routinely passes 64 chars there (#81331). Clamp with a
  142. # deterministic hash suffix (same idea as ``schema_sanitizer.sanitize_property_key``); dispatch is
  143. # unaffected because handlers close over the original unprefixed tool name.
  144. _MCP_TOOL_NAME_MAX_LENGTH = 64
  145. _MCP_TOOL_NAME_HASH_LENGTH = 8
  146. _clamped_names_warned: set[str] = set()
  147. def mcp_prefixed_tool_name(server_name: str, tool_name: str) -> str:
  148. """Registry/wire name: ``mcp__<sanitizedServer>__<sanitizedTool>``, clamped to 64 chars with a
  149. stable hash suffix when the natural name is longer."""
  150. full_name = f"{MCP_TOOL_NAME_PREFIX}{sanitize_mcp_name_component(server_name)}__{sanitize_mcp_name_component(tool_name)}"
  151. if len(full_name) <= _MCP_TOOL_NAME_MAX_LENGTH:
  152. return full_name
  153. suffix = "_" + hashlib.sha256(full_name.encode("utf-8")).hexdigest()[:_MCP_TOOL_NAME_HASH_LENGTH]
  154. if full_name not in _clamped_names_warned: # recomputed on every health refresh; warn once
  155. _clamped_names_warned.add(full_name)
  156. logger.warning("MCP tool name %r (%d chars) exceeds the %d-char provider limit; shortened to a "
  157. "deterministic hash-suffixed name", full_name, len(full_name), _MCP_TOOL_NAME_MAX_LENGTH)
  158. return full_name[:_MCP_TOOL_NAME_MAX_LENGTH - len(suffix)] + suffix
  159. def _convert_mcp_schema(server_name: str, mcp_tool) -> dict:
  160. """Convert an MCP ``Tool`` (``.input_schema``, or ``.inputSchema`` before mcp 2.0) to a
  161. ``registry.register(schema=...)`` dict."""
  162. return {
  163. "name": mcp_prefixed_tool_name(server_name, mcp_tool.name),
  164. "description": strip_unicode_tags(mcp_tool.description or f"MCP tool {mcp_tool.name} from {server_name}"),
  165. "parameters": _normalize_mcp_input_schema(mcp_field(mcp_tool, "input_schema", "inputSchema")),
  166. }
  167. # Utility tools generated per server: handler_key -> (description template, parameter
  168. # properties, required names). Schemas are FROZEN wire bytes — the key order emitted by
  169. # ``_build_utility_schemas`` must not change.
  170. _UTILITY_TOOL_SPECS = (
  171. ("list_resources", "List available resources from MCP server '{server}'", {}, None),
  172. ("read_resource", "Read a resource by URI from MCP server '{server}'",
  173. {"uri": {"type": "string", "description": "URI of the resource to read"}}, ["uri"]),
  174. ("list_prompts", "List available prompts from MCP server '{server}'", {}, None),
  175. ("get_prompt", "Get a prompt by name from MCP server '{server}'",
  176. {
  177. "name": {"type": "string", "description": "Name of the prompt to retrieve"},
  178. "arguments": {
  179. "type": "object",
  180. "description": "Optional arguments to pass to the prompt",
  181. "properties": {},
  182. "additionalProperties": True},
  183. }, ["name"]),
  184. ("list_event_types", "List the event types MCP server '{server}' can notify about, and your active "
  185. "subscriptions to them", {}, None),
  186. ("subscribe_event", "Subscribe to an event from MCP server '{server}': each occurrence starts a new "
  187. "agent run with your instructions and delivers its result to the chosen target",
  188. {
  189. "name": {"type": "string", "description": "Event type name from list_event_types"},
  190. "arguments": {
  191. "type": "object",
  192. "description": "Subscription arguments matching the event's inputSchema",
  193. "properties": {},
  194. "additionalProperties": True},
  195. "instructions": {"type": "string",
  196. "description": "What to do each time the event arrives (up to 2000 characters)"},
  197. "deliver": {"type": "string",
  198. "description": "Where each run's result goes: log, telegram, discord, slack, ..."},
  199. "deliver_chat_id": {"type": "string", "description": "Optional chat id on the deliver platform"},
  200. }, ["name"]),
  201. ("unsubscribe_event", "Cancel a subscription to an event from MCP server '{server}'",
  202. {
  203. "name": {"type": "string", "description": "Event type name"},
  204. "arguments": {
  205. "type": "object",
  206. "description": "The same arguments the subscription was made with",
  207. "properties": {},
  208. "additionalProperties": True},
  209. }, ["name"]))
  210. def _build_utility_schemas(server_name: str) -> list[dict]:
  211. """Schemas for the resource/prompt utility tools as ``{schema, handler_key}`` dicts."""
  212. out = []
  213. for handler_key, description, properties, required in _UTILITY_TOOL_SPECS:
  214. parameters = {"type": "object", "properties": {k: dict(v) for k, v in properties.items()}}
  215. if required is not None:
  216. parameters["required"] = list(required)
  217. out.append({
  218. "schema": {
  219. "name": mcp_prefixed_tool_name(server_name, handler_key),
  220. "description": description.format(server=server_name),
  221. "parameters": parameters},
  222. "handler_key": handler_key})
  223. return out
  224. def _normalize_name_filter(value: Any, label: str) -> set[str]:
  225. """Normalize include/exclude config to a set of exact names or fnmatch globs."""
  226. if value is None:
  227. return set()
  228. if isinstance(value, str):
  229. return {value}
  230. if isinstance(value, (list, tuple, set)):
  231. return {str(item) for item in value}
  232. logger.warning("MCP config %s must be a string or list of strings; ignoring %r", label, value)
  233. return set()
  234. def matches_name_filter(tool_name: str, patterns: set[str]) -> bool:
  235. """True if ``tool_name`` matches any entry: exact names literally, entries with
  236. ``*``/``?``/``[`` as case-sensitive globs (same semantics as ``approvals.deny``). Exact
  237. membership is checked first so big lists stay O(1)."""
  238. if not patterns:
  239. return False
  240. if tool_name in patterns:
  241. return True
  242. return any(fnmatch.fnmatchcase(tool_name, p) for p in patterns if "*" in p or "?" in p or "[" in p)
  243. # Utility handler -> capability key that must be non-None on the server's ``initialize``
  244. # response for the handler to be registered. Without this gate a tools-only server got all
  245. # four stubs and every call returned JSON-RPC -32601, making the model conclude the server
  246. # was broken.
  247. # Source of truth: MCP spec — capabilities.resources / capabilities.prompts are present on the response only
  248. # when the server actually implements those request families. Context7 @upstash/context7-mcp, which
  249. # advertises only ``tools``) had all four utility stubs registered and every model call to them came back
  250. # with JSON-RPC ``-32601 Method not found``, which made the model conclude the server was broken even when
  251. # the real tools worked. See #18051.
  252. _UTILITY_CAPABILITY_ATTRS = {
  253. "list_resources": "resources", "read_resource": "resources",
  254. "list_prompts": "prompts", "get_prompt": "prompts",
  255. "list_event_types": "events", "subscribe_event": "events", "unsubscribe_event": "events"}