Ask these specs

This catalog is written to be read, and the same specs behind it are also written to be asked. Connect an MCP client to them and you can question sysspec demo in plain language, from what a service is for to what an event carries, how something is meant to behave, and who breaks if it changes.

The answers come from the specs of record. They are versioned, gated, and the same surface implementations are held to, rather than anyone's memory of how the system works or code that may have drifted. That makes this useful well beyond building, for product and delivery people, analysts, support, architects and new joiners alike. Agents use exactly the same tools to build against the specs, which is why the answers agree.

Connect in one line

These specs are served live at https://demo.sysspec.dev/mcp. Point a client at that URL, with nothing to install and nothing to clone:

claude mcp add sysspec-demo --scope project \
  --transport http https://demo.sysspec.dev/mcp

Prefer a local process, or working from a checkout of the spec repo? That works too:

claude mcp add sysspec-demo --scope project \
  --env SPECS_DIR=/path/to/checkout/specs \
  -- npx -y sysspec-mcp

Any MCP client works. In Claude Code, confirm with /mcpand open with list_services(); the sysspec plugin (/plugin marketplace add hungovercoders/sysspec) adds the same tools plus the skills that drive implementing and consuming.

Questions worth asking

Drawn from these specs, so they are answerable right now:

Already answered, in the specs themselves

Authored in the data contracts as verified statements, versioned and gated like everything else here, and served over MCP with the answer attached.

• How many orders were placed on a given day?Count rows in order_placed_events where placed_at falls in the day, in the placed_at timezone. The table is deduplicated on event_id, so no DISTINCT is needed.
• What proportion of orders are cancelled, and why?Join order_cancelled_events to order_placed_events on order_id and group by reason. reason is a closed vocabulary of three values.
• What is the value of an order?total_pence, an integer number of pence covering the whole order. There is no per-line breakdown in this record.
• What settled yesterday?The rows in yesterday's settled_at partition - but that partition is not final until D+3, so a figure quoted before then can move.
• How does this differ from the payment event history?Same settlements, shaped for finance close: one row per payment with no CloudEvents envelope columns. The event history is the record it derives from.
• How much settled on a given day?Sum amount_pence over rows whose settled_at falls in the day. That is processor settlement time, not order time.

Understand the domain

• What does Orders do, and where does its responsibility stop?Summary, owner and version, straight from the manifest.
• Which services make up sysspec demo, and who owns each one?The service list, without reading a single file.
• Explain the rule behind “A valid order is accepted and its event is guaranteed” in business terms.The acceptance criteria are the behaviour of record.

Get to the detail

• What information does OrderPlaced carry, and which parts are required?One message schema, the cheapest question there is.
• What can placeOrder return, and what does each response mean?The API contract, rendered as answers rather than YAML.
• What is in the Order events history data product, and what are its guarantees?Data contracts read the same way as the rest of the suite.

Test a change before proposing it

• Who consumes orders.placed.v2?The blast radius of a change, before anyone writes it.
• If we dropped a field from OrderPlaced, who would break and would it need a major version?The versioning rules, applied to a real proposal.
• Where is the idea of a customer defined, and is it consistent across services?Search across every contract, scenario and data product at once.

What answers, and what it will not do

Twelve read-only tools serve the answers. There is no write tool: a conversation can never amend a contract, because changing one is a deliberate, versioned act with gates of its own. Reads are confined to artifacts a service manifest declares, so nothing is exposed by accident.

Tool	The question it answers
get_system()	What is this system, and what domain is it in?
list_services()	What is in this system?
get_service(name)	What does one service own, publish and depend on?
get_message_schema(service, message)	What is on this event?
get_operation(service, operation_id)	What does this API call take and return?
get_data_contract(service, table)	What is in this table, and how should I read it?
get_acceptance_criteria(service)	How is it supposed to behave?
get_artifact(service, path)	Show me the contract itself.
trace_channel(address)	Who publishes and who listens on this channel?
impact(service, message)	Who do I break if I change this?
validate_payload(service, message, payload)	Does this event meet the contract?
search_specs(query)	Where is this idea defined?

One boundary worth stating: these are specs of intent. They say what the system is meant to do, not what a running instance did last Tuesday. There is no traffic, no incidents and no data. If an implementation disagrees with an answer here, that is a bug in the implementation, and its gates should already be red.

Building rather than asking? The same tools carry the implementation and consumer loops.