Muscles JSON-RPC

JSON-RPC protocol projection for Muscles actions.

This package makes Muscles action-first applications callable over JSON-RPC while preserving the same schemas, rules, dispatcher, and context used by other projections.

Related Repositories

• muscles - core action contracts, dispatcher and inspect contract.
• muscles-cli - CLI action inspection and execution over the same contracts.
• muscles-mcp - MCP projection over the same action model.
• muscles-sse - streaming projection for action output.
• muscles-benchmarks - protocol projection regression checks.

Concept Guardrails

• JSON-RPC is a protocol projection, not a new framework layer.
• Methods must be discovered from inspect_application(app).
• Validation and error normalization must reuse Muscles core schema/rules/errors.
• Auth/rules must run through ActionDispatcher.
• The same use case must be callable from CLI, HTTP, MCP, and JSON-RPC without duplicating implementation.
• JSON-RPC state is scoped to the application instance; no mutable module-level method registry is the source of truth.

Implemented Features

Implemented JSON-RPC 2.0 projection:

• request validation (jsonrpc, method, params);
• method discovery from inspect_application(app);
• dispatch through ActionDispatcher(..., transport="jsonrpc");
• notification calls;
• batch calls;
• core stream projection with stable result.stream envelopes;
• deterministic error mapping:
  • -32600 invalid request;
  • -32601 method not found;
  • -32602 invalid params;
  • -32001 permission denied;
  • -32603 internal error.

Quick Start

Create the adapter from the existing application and pass JSON-RPC requests to handle. The adapter discovers actions through the Muscles application contract and dispatches them through the shared action dispatcher:

from muscles.jsonrpc import JsonRpcAdapter

rpc = JsonRpcAdapter.from_application(app)
response = rpc.handle({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "bookings.echo",
    "params": {"title": "Planning"},
})

The application must register the action and expose it to the jsonrpc transport. HTTP request parsing and returning the JSON response belong to the selected web runtime or application integration.

Stream actions expose core progress, log, result, and error events in a JSON-serializable envelope. Non-stream list and tuple results keep ordinary JSON-RPC semantics.

Run tests

python -m pytest -q

When testing against local core changes:

PYTHONPATH=../muscles/src:src python -m pytest -q

User docs:

• English: docs/jsonrpc-projection.en.md
• Русский: docs/jsonrpc-projection.ru.md