hermes_tools_mcp_server.py 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165
  1. """Hermes-tools-as-MCP server for the codex_app_server runtime.
  2. Codex owns the loop and tool list there, so a curated subset of Hermes tools is
  3. exposed over stdio MCP; codex registers it via ``~/.codex/config.toml
  4. [mcp_servers.hermes-tools]``. Run: ``python -m agent.transports.hermes_tools_mcp_server``.
  5. """
  6. from __future__ import annotations
  7. # First, like every entry point: stdio, import-path and environ-lifetime fixes (hermes_bootstrap).
  8. # Only as ``python -m``: codex_runtime & co. import this module for a constant, and the
  9. # bootstrap's scratch/TMPDIR exports must not fire in those library importers.
  10. if __name__ == "__main__":
  11. try:
  12. import hermes_bootstrap
  13. except ModuleNotFoundError:
  14. pass # a partial ``hermes update`` can leave the bootstrap unregistered
  15. import inspect
  16. import json
  17. import logging
  18. import os
  19. import sys
  20. from typing import Any, Optional
  21. logger = logging.getLogger(__name__)
  22. # The ``[mcp_servers.<name>]`` key under which the runtime migration registers this server. Every
  23. # codex-side reference to it (worker ``-c mcp_servers.<name>.env.*`` overrides, elicitation
  24. # auto-accept, display-name stripping) must use this constant: a drifted name materialises a
  25. # second env-only entry that codex rejects at bootstrap ("invalid transport").
  26. HERMES_TOOLS_MCP_SERVER_NAME = "hermes-tools"
  27. # JSON Schema type -> Python type mapping for signature generation
  28. _JSON_TO_PY = {"string": str, "integer": int, "number": float, "boolean": bool, "array": list, "object": dict}
  29. def _signature_from_schema(schema: dict | None) -> tuple[inspect.Signature, dict[str, type]]:
  30. """KEYWORD_ONLY signature + annotations from a JSON schema (optional params default to None)."""
  31. props = (schema or {}).get("properties") or {}
  32. required = set((schema or {}).get("required") or [])
  33. params, annots = [], {}
  34. for pname, pspec in props.items():
  35. if pname.startswith("_"):
  36. continue
  37. py = _JSON_TO_PY.get((pspec or {}).get("type"), Any)
  38. ann, default = (py, inspect.Parameter.empty) if pname in required else (Optional[py], None)
  39. annots[pname] = ann
  40. params.append(inspect.Parameter(pname, inspect.Parameter.KEYWORD_ONLY, annotation=ann, default=default))
  41. return inspect.Signature(params, return_annotation=str), annots
  42. # Each name MUST match a registered Hermes tool ``model_tools.handle_function_call()`` can dispatch.
  43. # NOT exposed: terminal/file/search/process/clarify (codex built-ins + its own approval UI);
  44. # delegate_task/memory/session_search/todo (need the running AIAgent context); browser_exec (runs
  45. # model-written Python on the Hermes host, outside codex's sandbox and approval UI).
  46. EXPOSED_TOOLS: tuple[str, ...] = (
  47. "web_search", "web_extract",
  48. "vision_analyze", "image_generate", "skill_view", "skills_list", "text_to_speech",
  49. # Kanban handoff tools: stateless (read HERMES_KANBAN_TASK, write kanban.db).
  50. # Without them a codex-runtime worker can't report completion and hangs.
  51. "kanban_complete", "kanban_block", "kanban_schedule", "kanban_request_review",
  52. "kanban_request_changes", "kanban_comment",
  53. "kanban_heartbeat", "kanban_show", "kanban_list",
  54. # Orchestrator-only (the kanban tool gates them on HERMES_KANBAN_TASK unset).
  55. "kanban_create", "kanban_unblock", "kanban_link",
  56. )
  57. def _build_server() -> Any:
  58. """Create the MCP server with Hermes tools attached (lazy imports: importable without ``mcp``)."""
  59. try:
  60. # mcp 2.0 renamed `mcp.server.fastmcp` to `mcp.server.MCPServer` (same surface).
  61. from mcp.server import MCPServer
  62. except ImportError as exc: # pragma: no cover - install hint
  63. raise ImportError(f"hermes-tools MCP server requires the 'mcp' package: {exc}") from exc
  64. from model_tools import get_tool_definitions, handle_function_call
  65. mcp = MCPServer(
  66. HERMES_TOOLS_MCP_SERVER_NAME,
  67. instructions=(
  68. "Hermes Agent's tool surface, exposed for use inside a Codex "
  69. "session. Use these for capabilities Codex's built-in toolset "
  70. "doesn't cover: web search/extract, "
  71. "subagent delegation, vision, image generation, persistent "
  72. "memory, skills, and cross-session search."
  73. ),
  74. )
  75. # Authoritative Hermes schemas so MCP clients see the same parameter docs the model does.
  76. all_defs = {
  77. td["function"]["name"]: td["function"]
  78. for td in (get_tool_definitions(quiet_mode=True) or [])
  79. if isinstance(td, dict) and td.get("type") == "function"
  80. }
  81. def _make_handler(tool_name: str, schema: dict | None, description: str):
  82. # The SDK derives the input schema from the callable's signature, so synthesize it from the JSON Schema.
  83. sig, annots = _signature_from_schema(schema)
  84. def _dispatch(**kwargs: Any) -> str:
  85. try:
  86. # Drop None so unset optionals aren't forwarded to the handler.
  87. return handle_function_call(tool_name, {k: v for k, v in kwargs.items() if v is not None})
  88. except Exception as exc:
  89. logger.exception("tool %s raised", tool_name)
  90. return json.dumps({"error": str(exc), "tool": tool_name})
  91. _dispatch.__name__ = tool_name
  92. _dispatch.__doc__ = description
  93. _dispatch.__signature__ = sig
  94. _dispatch.__annotations__ = {**annots, "return": str}
  95. return _dispatch
  96. exposed_count = 0
  97. for name in EXPOSED_TOOLS:
  98. spec = all_defs.get(name)
  99. if spec is None:
  100. logger.debug("skipping %s — not registered in this Hermes process", name)
  101. continue
  102. description = spec.get("description") or f"Hermes {name} tool"
  103. params_schema = spec.get("parameters") or {"type": "object", "properties": {}}
  104. try:
  105. mcp.add_tool(_make_handler(name, params_schema, description), name=name, description=description)
  106. except TypeError:
  107. # Older mcp SDK: decorator-style registration; __signature__ still drives schema.
  108. mcp.tool(name=name, description=description)(_make_handler(name, params_schema, description))
  109. exposed_count += 1
  110. logger.info("hermes-tools MCP server registered %d/%d tools", exposed_count, len(EXPOSED_TOOLS))
  111. return mcp
  112. def main(argv: Optional[list[str]] = None) -> int:
  113. """Entry point for `python -m agent.transports.hermes_tools_mcp_server`."""
  114. argv = argv or sys.argv[1:]
  115. verbose = "--verbose" in argv or "-v" in argv
  116. logging.basicConfig(
  117. level=logging.INFO if verbose else logging.WARNING,
  118. stream=sys.stderr, # MCP uses stdio for protocol — logs MUST go to stderr
  119. format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
  120. )
  121. # Keep Hermes' own banners off stdout (the MCP wire).
  122. os.environ.setdefault("HERMES_QUIET", "1")
  123. os.environ.setdefault("HERMES_REDACT_SECRETS", "true")
  124. try:
  125. server = _build_server()
  126. except ImportError as exc:
  127. sys.stderr.write(f"hermes-tools MCP server cannot start: {exc}\n")
  128. return 2
  129. try:
  130. server.run() # defaults to stdio transport, which codex spawns us on
  131. except KeyboardInterrupt:
  132. pass
  133. except Exception as exc:
  134. logger.exception("hermes-tools MCP server crashed")
  135. sys.stderr.write(f"hermes-tools MCP server error: {exc}\n")
  136. return 1
  137. return 0
  138. if __name__ == "__main__":
  139. sys.exit(main())