JSON-RPC Server & Event System
Relevant source files
The following files were used as context for generating this wiki page:
- optional-skills/creative/unreal-mcp/SKILL.md
- agent/learn_prompt.py
- optional-skills/software-development/code-wiki/SKILL.md
- optional-skills/creative/system-atlas/SKILL.md
- website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md
The JSON-RPC Server and Event System provides the communication backbone for the Hermes Agent, enabling standardized tool discovery, remote execution, and automated task scheduling. It leverages the Model Context Protocol (MCP) and specialized worker architectures to bridge the agent's core logic with external environments, such as game engines and cloud-hosted scripts.
The system facilitates bidirectional communication where the agent acts as a client to various JSON-RPC servers (like Unreal Engine MCP) while simultaneously managing an internal event loop for delegated tasks and scheduled cronjobs.
System Architecture
The architecture consists of three primary layers: the Discovery Layer for tool registration, the Dispatch Layer for handling JSON-RPC requests, and the Execution Layer for running logic in local or remote environments.
Component Overview
| Component | Description | Source |
|---|---|---|
| MCP Server | Runs inside target processes (e.g., Unreal Editor) to expose functionality via JSON-RPC. | unreal-mcp/SKILL.md |
| Tool Dispatcher | Routes calls like mcp_unreal_engine_call_tool to the appropriate qualified toolset. | unreal-mcp/SKILL.md |
| Skill Manager | Handles the lifecycle of skill execution and internal tool framing. | learn_prompt.py |
| Event Scheduler | Manages asynchronous executions via cronjob and delegate_task. | learn_prompt.py |
System Data Flow Diagram
The following diagram shows how a request moves from the Agent through the JSON-RPC interface to an external system.
Model Context Protocol (MCP) Integration
The system uses MCP as a standardized JSON-RPC implementation to expose editor and application functionality. The server advertises its capabilities through a discovery walk, allowing the agent to interact with unfamiliar environments without pre-coded endpoint logic.
Discovery Protocol
The JSON-RPC server operates in a "tool-search" mode to minimize token usage by only advertising meta-tools for discovery.
- List Toolsets: The agent calls
list_toolsetsto retrieve qualified names likeeditor_toolset.toolsets.scene.SceneTools. - Describe Toolset: The agent retrieves full JSON schemas for specific capabilities.
- Call Tool: The agent invokes the short tool name with arguments matching the schema.
Sources: optional-skills/creative/unreal-mcp/SKILL.md:95-120
Connection and Configuration
The system binds to local or remote addresses (default http://127.0.0.1:8000/mcp) and requires an explicit connection probe during the installation phase.
mcp_servers:
unreal-engine:
url: "http://127.0.0.1:8000/mcp"
timeout: 120
Sources: optional-skills/creative/unreal-mcp/SKILL.md:66-75
Event Dispatching & Automation
The system manages automated behaviors through the Skill system and specialized event tools. These tools allow the agent to persist logic beyond the current conversation context.
Event Tools
delegate_task: Hand-offs long-running or complex tasks to sub-agents or background workers.cronjob: Schedules recurring JSON-RPC calls or shell scripts.skill_manage: Authors and patches the reusable logic that defines how events are handled.
Sources: agent/learn_prompt.py:65-75
Skill Execution Sequence
The following sequence diagram illustrates the lifecycle of a skill-based event execution.
Implementation Standards
Every JSON-RPC interaction and event-driven skill must adhere to specific validation rules to ensure system stability.
Validation Constraints
- Frontmatter Requirements: Skills must start with a
---YAML block containingnameanddescription. - Size Limits: Individual skill content is capped at 100,000 characters to prevent context overflow.
- Serialization: Data blocks inside system atlases and data packets must remain JSON-serializable for transport.
Sources: website/.../hermes-agent-skill-authoring.md:27-45, optional-skills/creative/system-atlas/SKILL.md:105-110
Error Handling
The system differentiates between protocol-level exceptions and application-level failures. Many JSON-RPC responses (e.g., Blueprint compiles) report success/failure within the response body rather than using HTTP error codes. The dispatcher is responsible for reading every result and diagnosing non-explicit successes.
Sources: optional-skills/creative/unreal-mcp/SKILL.md:135-145
Summary
The JSON-RPC Server & Event System enables the Hermes Agent to function as a versatile controller for external applications. By utilizing the Model Context Protocol for tool discovery and an internal event loop for task delegation, the system ensures that automated workflows are both scalable and observable. Components like the Tool Dispatcher and Skill Manager ensure that all interactions remain documented, validated, and traceable across different execution environments.