Asfw MCP Control Plane

ASFW MCP Control Plane

Use the bundled client instead of reconstructing MCP HTTP/SSE sessions or pasting large tool schemas into the conversation.

Default workflow

Run these commands from the ASFireWire repository root.

1. Confirm the app-hosted MCP server is enabled. The default local endpoint is http://127.0.0.1:8766/mcp, which is also the client's built-in DEFAULT_ENDPOINT, so no export is needed in the normal case.

   The port is user-configurable in the app's MCP Control Plane settings. On Connection refused, read the port shown in that panel and set the endpoint explicitly rather than assuming the server is down:

   export ASFW_MCP_ENDPOINT=http://127.0.0.1:<port>/mcp

2. Ask the versioned health resource whether deeper reads are trustworthy:

   python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py health

   ready permits targeted read-only diagnostics. degraded permits only high-level inspection until its reasons are resolved. unavailable means do not infer driver state. Preserve expectedGeneration for any follow-up bus request.

3. Run the compact read-only summary when node or protocol detail is needed:

   python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py summary

4. Use tools or resources only when the summary lacks the needed detail.

5. Call a read tool with typed JSON arguments only after checking its schema:

   python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py tools
   python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_read_quadlet '{"nodeId":0,"generation":9,"addressHigh":65535,"addressLow":4026532864}'

Running driver build

Before comparing live behavior with the checkout, read the commit embedded in the running dext. This uses the driver user client's version method and issues no FireWire transaction, so it is safe during active audio:

python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_get_driver_version '{}'

Use gitCommitFull, gitBranch, gitDirty, and buildTimestamp from the response. The checkout's DriverVersion.hpp describes a build artifact and does not prove which dext is currently running.

Pass --endpoint or set ASFW_MCP_ENDPOINT when the server uses a non-default loopback port.

M-Audio 1814 Virtual UART diagnostics

The 1814 shell can report its own isochronous counters, sync state, routing, and peak meters. Use the current physical nodeId and expectedGeneration from summary. These tools send FireWire mailbox writes even though the shell commands only read diagnostic state. They are gated as developerWrite, so do not call them without authorization for live device control.

python3 tools/1814/bebob_shell.py --node <nodeId> --gen <expectedGeneration> \
  'sys stat' 'sys avstat all' 'fw show' 'fw mix show' 'fw vol peak'

The MCP tool asfw_bebob_shell_execute accepts any single printable ASCII shell command and checks the 1814 identity and bus generation before each transaction. Commands may change device settings, so treat each call as a developer write. The five convenience tools asfw_bebob_get_streaming_stats, asfw_bebob_get_silicon_status, asfw_bebob_get_sync_state, asfw_bebob_get_mixer_routing, and asfw_bebob_get_meter_peaks use the same guarded path. fw mix show is routing readback; it does not change routing.

Config-ROM explorer

asfw_get_config_rom is a read-only projection of the driver's discovery cache. It never starts a ROM fetch and never issues a FireWire transaction. First obtain the current nodeId and generation from summary; after any bus reset, refresh them before asking for another view.

The default summary view is deliberately compact: cache/generation status, GUID, vendor/model/unit identity, parser diagnostics, and two reminders that avoid common false conclusions. Use it before requesting the more detailed views:

# Compact normal entry point: summary is default.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py rom 0 17

# BIB bitfields, each with bit position, decoded value, and a short meaning.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py rom 0 17 --view bib

# Parsed IEEE 1212 directory tree (default 64 entries; raw leaf bytes omitted).
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py rom 0 17 --view tree

# Big-endian cached quadlets; bounded to 64 per response and page by index.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py rom 0 17 --view raw --start-quadlet 0 --max-quadlets 32

Equivalent direct calls are useful when another MCP client does not use the bundled script:

python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_get_config_rom \
  '{"nodeId":0,"generation":17,"view":"bib"}'

Interpret the annotated BIB carefully:

• IRMC, BMC, CMC, and ISC are the device's Config-ROM capability claims. They do not establish physical root, designated IRM, or Bus Manager ownership.
• generation in the BIB is the device's four-bit ROM field; it can differ from the current host topology generation supplied to the tool.
• max_rec describes an asynchronous payload code. It is not an isochronous audio packet size.
• A tree leaf reported as not fetched from partial cache is not evidence of a malformed ROM. The discovery cache may contain only a prefix. Likewise, a cached result from another generation is useful only as stale description, never as a target for a follow-up transaction.

DICE registers by name

asfw_dice_read_register accepts a symbolic register instead of a raw address. It resolves against the device's own section table, so no section base is ever assumed:

# How many PCM channels does the device's playback (host->device) stream carry?
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_dice_read_register \
  '{"nodeId":0,"generation":17,"register":"RX_NUMBER_AUDIO","streamIndex":0}'

# Clock source and rate, decoded.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_dice_read_register \
  '{"nodeId":0,"generation":17,"register":"GLOBAL_CLOCK_SELECT","decode":true}'

The response carries resolvedAddress, sectionOffsetBytes and (for per-stream registers) streamConfigSizeBytes, so the derivation is auditable rather than trusted. Omitting register falls back to the raw-address behaviour unchanged.

TX and RX are the device's directions, not the host's. DICE TX is what the device transmits — the host's capture. DICE RX is what the device receives — the host's playback. ASFW's own profile fields use the opposite convention (TxChannelCount is playback), so never transcribe one onto the other. The offsets differ too: TX_NUMBER_AUDIO is at 0x0C while RX_NUMBER_AUDIO is at 0x10, because RX inserts SEQ_START ahead of it.

Registers with no defined decoding return the raw value only; decode: true never invents an interpretation. asfw_dice_decode_status decodes a value you already hold, without touching the bus:

python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_dice_decode_status \
  '{"register":"GLOBAL_EXTENDED_STATUS","value":64}'

GLOBAL_EXTENDED_STATUS splits into locked and slipping; arx1..arx4 are the device's receive streams, so arx1 reflects the host-to-device transmit.

These reads are readOnly but not idempotent — each issues a real FireWire transaction against a live generation. Do not run them during an active audio endurance run; prefer asfw_get_audio_stream_health, which reads driver-held counters and touches no bus.

Tool visibility is not device capability

tools lists a filtered view, never the full catalog. Two independent filters apply (ASFW/MCP/ASFWMCPCore.swift, listTools):

1. Visibility tier vs runtime mode — always, readOnly, developerWrite, and rawDeveloper are admitted according to the server's current mode.
2. Protocol-hint prefilter — evaluated before the tier check, against the union of protocolHints across all currently discovered nodes.

The hint prefilter is any-of, not all-of: a tool is listed when it declares no hints, or when at least one of its declared hints is present. A tool declaring ["bebob", "cmp"] is therefore listed on a cmp-only bus.

Two consequences:

• An absent tool means "not listed for this generation's hints and mode". It is not evidence that the driver lacks the capability or that the device lacks the protocol. Check ASFWMCPToolCatalog for the defined set and ask asfw_explain_capability for the specific reason.
• Visibility does not follow the read-only/destructive gradient. Observed with only an Apogee Duet attached (avc, cmp): asfw_phase88_start_48k and asfw_phase88_stop are listed because they declare cmp, while every read-only BeBoB diagnostic (asfw_bebob_get_unit_plug_info, asfw_bebob_get_clock_topology, asfw_phase88_get_clock, …) is hidden because it declares bebob alone. The destructive lifecycle tools are reachable while the state queries that would justify using them are not. Never infer device state from which tools appear; re-list after any generation change.

Ring-first diagnostic workflow

The driver-owned log ring is the primary diagnostic source. Do not begin with log stream or add ASFW_LOG calls to interrupt/isochronous hot paths merely to investigate an incident. Query a small, relevant slice and preserve the returned nextSequence cursor for follow-up requests.

1. Run health, then record expectedGeneration from summary.
2. Read asfw_log_stats once to establish capacity, oldest/latest sequence, and drop count. A non-zero drop count makes an absence-of-evidence result weaker; report it.
3. Query one subsystem/category at a time with maxRecords no larger than 200 and, where possible, contains. Use nextSequence as the exclusive cursor on the next query. An empty sparse page may still advance the cursor.
4. Prefer a structured MCP read for current state and the ring for chronology. If an advertised read-only tool returns capabilityUnavailable/ notImplemented, report that adapter gap; do not fabricate the state or fall back to a mutation.

Useful incident queries:

# Was a reset requested locally, and which node's accepted Self-ID attributed it?
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_log_query '{"categories":["BusReset"],"contains":"Reset ","maxRecords":100}'

# Compare the physical topology role with Config-ROM capability claims.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_log_query '{"categories":["ConfigROM"],"contains":"[RoleEvidence]","maxRecords":50}'

# Inspect only CMP/FCP activity while audio is stopped or running.
python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_log_query '{"categories":["CMP","FCP"],"maxLevel":"debug","maxRecords":200}'

Active audio-run rule

During an active audio endurance or fault-reproduction run, do not call health, summary, discovery, or any control tool unless the user explicitly requests it. They can perturb the app/control plane while the issue is being timed. A small, targeted driver-ring query is permitted only when requested; it is read-only and never changes stream state. Do not run broad or parallel queries while audio is playing.

For a live TX-content incident, query the retained DirectAudio lines. The [TxPrep] heartbeat carries the fill's health (missedFinality: frames that reached their packet too late and went out silent; sOutMinPk: the smallest margin, in packets, between a filled packet and the first packet the fill may still write, which is the projected hardware position plus 2). [TxPrepRange] is the refill-hole evidence (a producer pass that stopped below the descriptor floor):

python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_log_query \
  '{"categories":["DirectAudio"],"contains":"[TxPrep","maxLevel":"debug","maxRecords":20}'

[TxPrepFrame] and [TxExposure] no longer exist (milestone 6, documentation/TX_OWNERSHIP.md); an older log that has them came from a driver before the audio-side fill.

These lines are ring-only (ASFW_LOG_RING_ONLY), so read them through the driver log ring as above rather than log show. A healthy run shows only the periodic [TxPrep] heartbeat.

The former [PayloadWriter] record was retired in FW-171: it was recorded from the real-time IO callback into the shared control block and drained on the receive path, and its query string ([PayloadWriter] anomaly) never matched an emitted line.

Stream will not start: attribute it before theorising

When a device enumerates but audio never flows, ask asfw_get_audio_stream_health first. It is a read-only projection of driver-held counters — no FireWire transaction, safe during an active run — and it separates three failures that otherwise present identically as silence.

python3 skills/asfw-mcp-control-plane/scripts/asfw_mcp.py call asfw_get_audio_stream_health '{}'

Each endpoint carries a verdict and the raw counters behind it:

Read deviceSendsOnlyNoData precisely: it states what the device sent, not what the device is waiting for. It is not evidence that the device requires host timestamps first — the TCAT and Linux DICE stacks both withhold host SYT until the device has already sent valid ones, so a NO-DATA stall does not by itself imply a host-side handshake obligation. Report the counters; do not infer intent.

packetsSeen counts every packet the master stream decoded, so packetsSeen == noDataPackets is the only sound basis for "the device is sending only NO-DATA". A non-zero reject counter with packetsSeen > 0 means the device did send us something we threw away.