mcp_schema_cache.py 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  1. """Persistent MCP tool-schema cache for lazy server startup: per-server tool manifests on
  2. disk so Hermes can register MCP tools into the agent snapshot without spawning the stdio
  3. child at idle dashboard startup. Entries are keyed by server name + a fingerprint of the
  4. connection config (command/args/url/tools filters)."""
  5. from __future__ import annotations
  6. import hashlib
  7. import json
  8. import logging
  9. import threading
  10. import time
  11. from pathlib import Path
  12. from typing import Any, Dict, List, Optional
  13. logger = logging.getLogger(__name__)
  14. _CACHE_FILENAME = "mcp_schema_cache.json"
  15. _cache_lock = threading.Lock()
  16. def _cache_path() -> Path:
  17. from hermes_constants import get_hermes_home
  18. return get_hermes_home() / "cache" / _CACHE_FILENAME
  19. def config_fingerprint(config: dict) -> str:
  20. """Stable hash of the connection-defining parts of an MCP server config."""
  21. tools_filter = config.get("tools") or {}
  22. payload = {
  23. "command": config.get("command"),
  24. "args": config.get("args") or [],
  25. "url": config.get("url"),
  26. "transport": config.get("transport"),
  27. "tools_include": sorted(tools_filter.get("include") or []),
  28. "tools_exclude": sorted(tools_filter.get("exclude") or [])}
  29. raw = json.dumps(payload, sort_keys=True, separators=(",", ":"))
  30. return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
  31. def _load_all() -> dict[str, Any]:
  32. path = _cache_path()
  33. if not path.exists():
  34. return {}
  35. try:
  36. data = json.loads(path.read_text(encoding="utf-8-sig"))
  37. return data if isinstance(data, dict) else {}
  38. except Exception as exc:
  39. logger.debug("Could not read MCP schema cache %s: %s", path, exc)
  40. return {}
  41. def _save_all(data: dict[str, Any]) -> None:
  42. from utils import atomic_json_write
  43. # 0o600: the cache file is trusted input on the lazy registration path, keep it user-only.
  44. atomic_json_write(_cache_path(), data, mode=0o600)
  45. def get_cached_entry(server_name: str, fingerprint: str) -> Optional[dict]:
  46. """Return cached entry when fingerprint matches (and TTL holds), else None. ``tools/list``
  47. results may carry ``ttlMs`` (SEP-2549); an entry older than a recorded TTL is a miss so the
  48. next startup re-probes instead of serving a stale manifest forever. Entries without a TTL
  49. never expire. ``cacheScope`` is irrelevant: this cache is per-user local disk."""
  50. with _cache_lock:
  51. entry = _load_all().get(server_name)
  52. if not isinstance(entry, dict) or entry.get("fingerprint") != fingerprint:
  53. return None
  54. ttl_ms = entry.get("ttl_ms")
  55. written_at = entry.get("written_at")
  56. expired = (isinstance(ttl_ms, (int, float)) and isinstance(written_at, (int, float))
  57. and (time.time() - written_at) * 1000.0 >= float(ttl_ms))
  58. return None if expired else entry
  59. def write_cache_entry(server_name: str, fingerprint: str, *, tools: list[dict],
  60. utility_tools: Optional[list[dict]] = None, ttl_ms: Optional[float] = None,
  61. cache_scope: Optional[str] = None) -> None:
  62. """Persist tool schemas after a successful live connect. ``ttl_ms`` / ``cache_scope`` are
  63. the server's ``tools/list`` SEP-2549 hints; ``written_at`` anchors TTL expiry."""
  64. entry = {"fingerprint": fingerprint, "tools": tools, "utility_tools": utility_tools or []}
  65. if isinstance(ttl_ms, (int, float)):
  66. entry["ttl_ms"] = ttl_ms
  67. entry["written_at"] = time.time()
  68. if cache_scope:
  69. entry["cache_scope"] = cache_scope
  70. with _cache_lock:
  71. data = _load_all()
  72. # Write-through fires on every registration (reconnects, list_changed); skip the
  73. # rewrite when the entry is byte-identical on disk. TTL'd entries always rewrite:
  74. # written_at must advance or the entry would expire at its ORIGINAL write time.
  75. if "written_at" not in entry and data.get(server_name) == entry:
  76. return
  77. data[server_name] = entry
  78. _save_all(data)
  79. def _list_field(entry: dict, key: str) -> list[dict]:
  80. value = entry.get(key)
  81. return list(value) if isinstance(value, list) else []
  82. def tools_from_cache_entry(entry: dict) -> list[dict]:
  83. """Return cached MCP tool dicts (name, description, inputSchema)."""
  84. return _list_field(entry, "tools")
  85. def utility_tools_from_cache_entry(entry: dict) -> list[dict]:
  86. """Return cached ``{schema, handler_key}`` utility rows."""
  87. return _list_field(entry, "utility_tools")