05 · MCP
Procedures are most useful when an agent can call them by name. Jazari ships a transport-neutral handler for embedded hosts and an on-demand MCP stdio server for its standalone SQLite database.
require "jazari"
require "jazari/mcp/handler" # opt-in: not loaded by `require "jazari"`
Jazari::Mcp::Handler.new.call(action: "get", target: target)
# => { ok: true, state: "default", topic: "...", progress: {...}, last_run: {...} }
The MCP layer is optional
Nothing requires you to use it. The gem has no MCP dependency, and the dispatcher is not even loaded by default:
require "jazari/mcp/handler" # only if you want the ready-made dispatcher
If you already have an MCP surface with its own envelope, naming, and permissions, absorb the actions into your own tool instead — see below.
Absorbing jazari into your own tool
Jazari::Mcp::Actions declares every action as data, so you can build your own
schema and keep your own dispatch:
frag = Jazari::Mcp::Actions.schema_fragment # or scope: :read
MY_TOOL[:input_schema][:properties][:action][:enum] += frag[:enum]
MY_TOOL[:input_schema][:properties].merge!(frag[:properties])
Then dispatch to Jazari.* yourself. No handler, no coupling to this gem's
reply shape.
Each descriptor carries what a host needs to annotate correctly:
a = Jazari::Mcp::Actions.fetch("reset")
a.effect # => :destructive
a.confirm? # => true
a.summary # => "Discard this subject's override and reveal the current canon."
effect is one of :read, :additive, :overwrite, :destructive — enough
to decide how cautiously your clients should treat each action without reading
this gem's source.
Jazari::Mcp::Actions.summaries gives a ready line-per-action list for a tool
description or a paired skill.
These descriptors are the single source of truth. The shipped handler validates and scopes against the same list, and a test asserts it can dispatch every declared action — so the schema you publish and the behaviour the gem implements cannot drift apart.
Embedded hosts own their tool
Tool identity is product identity. Your tool has your name, your subject
vocabulary, and your permissions — myapp_runbook, not jazari_runbook. Two
apps sharing this handler still present two different tools.
Standalone mode is the deliberate exception: jazari mcp stdio --database PATH
exposes one generic jazari tool over the process's stdin/stdout. It opens no
network listener and exits when the client closes stdin. Use --recipes PATH
to seed recipe files without overwriting rows an operator already changed.
The handler never sees an actor object. You authorize, construct the target,
and pass an opaque actor_ref, then call. That ordering is the whole security
model. Evidence may carry a different explicit actor_ref; if omitted, it
inherits the run actor.
def call(input)
target = authorized_target(input) or return not_found # you
reply = Jazari::Mcp::Handler.new.call( # gem
action: input["action"], target: target, arguments: input
)
reply[:ok] ? ok(reply) : fail(reply[:error]) # you
end
Actions
Read: get, last_run
Write: set, add_item, remove_item, check_item, reset
Runs: start, tick, evidence, finish
Jazari::Mcp::Handler.actions_for("read") # => ["get", "last_run"]
Advertise only what the granted scope may call. A read-scoped connection should not see mutations in its tool list at all — offering them and then refusing is a worse experience than not offering them.
One flat tool, not one per verb
Keep a single action-enum tool. Agents deal badly with a dozen near-identical
tools, and a flat enum keeps the whole surface legible in one schema.
Put the operating guidance in a paired skill rather than the input schema — when to open a run versus just read, what evidence to attach, that queues are advisory.
Errors cross as codes
{ "ok": false, "error": "revision_conflict" }
Never a message. A message can disclose a record, a query, or whether a target
exists. target_not_found covers unknown, unauthorized, and deleted alike, so
guessing reveals nothing.
The closed domain set is target_not_found, invalid_runbook,
revision_conflict, item_not_found, item_not_in_snapshot,
read_only_target, and run_closed. The standalone JSON envelope additionally
uses invalid_request, storage_busy, and storage_failure at its transport
and storage boundary.
Two things worth annotating
reset is destructive and requires confirm: true — it discards an operator's
customisation. set may overwrite; annotate it conservatively.
Everything else is either read-only or an additive write.