The MCP tools

Reference · generated · every tool `pms-mcp` registers, with its input schema, printed by the server itself

The server speaks JSON-RPC 2.0 over stdio. mesh_probe_pulse and mesh_reachability are registered only when PMS_MCP_ALLOW_PROBE=1 is set at launch.

`mesh_list_rings`

Enumerate POSIX SHM regions that look like Pulse Mesh rings. On Linux this scans /dev/shm/pms-*; on macOS POSIX shared-memory names are not enumerable via the filesystem, so this returns an empty list with a note field rather than failing.

Input	Type	Required	Notes

`mesh_ring_peek`

Read-only snapshot of an existing SHM-backed PulseRing. Returns capacity, write_count, cursor, and the most-recent N slot summaries. Give a hub name (e.g. default_hub) for the daemon’s ring or a raw POSIX SHM name starting with /; the ring’s header records its capacity and slot size, so none is passed. The reader attaches as a secondary reader — it does not advance the primary cursor.

Input	Type	Required	Notes
`count`	integer		Max number of recent slots to summarize.
`ring_name`	string	yes	Hub name (e.g. default_hub) or a raw POSIX SHM name starting with /.

`codec_roundtrip`

Canonically encode a PulseEnvelope spec, round-trip decode it, and return the canonical hex + BLAKE3 content hash + size. Proves the canonical codec works for the supplied input. The same canonical_hex output is byte-identical across Rust, Python, and Node implementations of the codec, which is the byte equality the standard is built on.

Input	Type	Required	Notes
`envelope_type`	integer	yes
`payload_hex`	string		Hex-encoded raw payload bytes (mutually exclusive with payload_utf8).
`payload_utf8`	string		UTF-8 payload bytes (mutually exclusive with payload_hex).
`type_name`	string

`mesh_envelope_describe`

Decode a canonical PulseEnvelope hex string and return a structural summary: envelope_type, content_hash, monotonic_nanos, flags, payload variant + size. Pure function — does not touch live mesh state.

Input	Type	Required	Notes
`canonical_hex`	string	yes	Canonical wire bytes, lowercase hex.

`modules_list`

List the M01..M12 optimization modules, optionally filtered to one developer profile (hft / ai / robotics / telemetry / dev). Each entry includes its M-id, crate name, one-line summary, and the profiles it is recommended for.

Input	Type	Required	Notes
`profile`	string		Optional profile filter. one of [“hft”,“ai”,“robotics”,“telemetry”,“dev”]

`modules_describe`

Describe one M01..M12 optimization module by its M-id: the crate or module that implements it, its one-line summary, and the developer profiles it is recommended for. The implementing crate’s rustdoc carries the full documentation.

Input	Type	Required	Notes
`id`	string	yes	Module id like ‘M04’.

`mesh_attach`

Register a process name in the mesh-hub registry. Returns the daemon’s assigned node_id. The connection is dropped at the end of the call; another call (or the dev-functions Rust crate) holds the name persistently if you need that.

Input	Type	Required	Notes
`name`	string	yes	Process-visible name to register under.

`mesh_send`

Publish an envelope to a channel on the mesh-hub daemon. Returns the daemon’s envelope_id.

Input	Type	Required	Notes
`as_name`	string		Name to attach under for this send. Defaults to ‘mcp-send’.
`channel`	string	yes	Routing key.
`payload`	string		UTF-8 payload (use payload_hex for binary).
`payload_hex`	string		Hex-encoded payload bytes; mutually exclusive with payload.
`type_name`	string		Optional type name for typed schemas.

`mesh_query`

Structured query against the daemon’s basket SQLite store. Returns rows or aggregations; never a firehose. Supply filters (channel, type, origin, time window) + optional aggregation (count, count_by_channel, time_bucket, distinct_channels, distinct_types). Replaces unbounded mesh_tap streaming.

Input	Type	Notes
`aggregate`	string	one of [“count”,“count_by_channel”,“time_bucket”,“distinct_channels”,“distinct_types”]
`basket_path`	string	Path to the basket DB. Defaults to $PMS_BASKET_DB or ~/.local/share/pms/basket.db.
`bucket_secs`	integer	Required when aggregate=time_bucket.
`channel`	string
`envelope_type`	integer
`limit`	integer	Max rows (default 50, capped at 200 for MCP).
`origin`	string
`since_unix_nanos`	integer	Time-window start (inclusive).
`type_name`	string
`until_unix_nanos`	integer	Time-window end (exclusive).

`mesh_health`

Report which names are attached to the daemon and basic liveness state. For v0 this returns a static snapshot (no heartbeat protocol yet); future revisions surface NodeState from mesh-health.

Input	Type	Required	Notes

`mesh_replay`

Replay envelopes from the basket back through the daemon. Useful for re-running a captured workload. WARNING: also reaches subscribers — confirm with the user before using on production-relevant channels.

Input	Type	Required	Notes
`as_name`	string		Name to attach under. Defaults to ‘mcp-replay’.
`channel`	string	yes	Source channel (basket query).
`limit`	integer		Max envelopes to replay (capped at 100).
`since_unix_nanos`	integer
`target_channel`	string		Where to replay. Defaults to source channel.
`until_unix_nanos`	integer

`mesh_probe_pulse`

Send a single pulse to a UDP target and return send-side duration. Bounded: exactly one frame per call. Does not echo / measure RTT — that requires a peer-side echo service not shipped by default. Use this for liveness checks and to surface kernel errors (destination unreachable, etc.). Gated on PMS_MCP_ALLOW_PROBE=1 at server launch.

Input	Type	Required	Notes
`instruction`	integer		Pulse instruction opcode (default: Heartbeat = 1).
`payload_hex`	string		Optional hex-encoded envelope payload. Empty if omitted.
`target`	string	yes	UDP destination, e.g. 127.0.0.1:9000.

`mesh_reachability`

Send a one-pulse Heartbeat probe to each target in turn and report whether the kernel accepted the send. UDP is connectionless so this is a send-success check, not an RTT measurement. Gated on PMS_MCP_ALLOW_PROBE=1.

Input	Type	Required	Notes
`targets`	array	yes	List of UDP destinations, e.g. [“127.0.0.1:9000”, “10.0.0.5:9001”].

Keyboard shortcuts

Pulse Mesh Daemon