io.github.AImplifier/eeg-mcp

Permit hardware stimulation for a bounded window. Arming expires deliberately: an agent that stalls mid-protocol should not be able to resume and fire a stimulator minutes later without a fresh, explicit decision. Re-arm as needed, or disarm the moment a block ends.

Fold an external LSL marker stream into this session's event log. The reverse of attach_stim_backend(backend="lsl"): that publishes markers for other software to consume; this consumes markers *from* other software -- PsychoPy is the common case, but anything that timestamps its own events over LSL works the same way. Each marker lands with origin='marker' at the sample index nearest its own LSL timestamp in the raw buffer, the same "one event log, one clock" treatment a board's own marker channel gets. Only one marker stream can be attached per session; attaching again replaces the previous one.

Attach a processor to a session. A ``streaming`` processor runs inside the acquisition loop on every chunk, so it reacts within one poll interval without an agent round-trip -- that is how closed-loop logic gets fast. The cost is that slow code stalls acquisition; ``processor_status`` reports each one's mean and worst-case time so you can see whether yours is affordable. Non-streaming processors do nothing until you call ``run_processor``.

Bind a stimulation target to a session and open its transport. Start with backend='log' to rehearse a protocol with no output at all, then switch once the timing looks right.

Per-channel health check: amplitude, flat/railed detection, line noise. Call this before trusting any real-time feature, and definitely before driving stimulation from one. A flat or railed electrode poisons an average reference and a band-power threshold without changing anything you would notice in the feature value itself.

Empty the session's event log without stopping the stream. Useful between blocks of an experiment. The signal buffer is untouched.

Remove the filter chain; reads return raw signal again.

Stop listening for external markers on this session.

Remove a processor from a session and release its state.

Close and remove a stimulation backend from a session.

Revoke permission to stimulate. Takes effect immediately.

Write a full review page: traces, spectrum, quality, and the event log. The one artefact to keep from a session. Everything is inlined, so it opens on any machine, needs no internet, and still renders years from now.

Band power over the most recent window, per channel and averaged. The workhorse feature for neurofeedback and closed-loop triggering. Prefer the ``_rel`` (relative) values for thresholds: they are largely immune to impedance drift, so a threshold set at the start of a session still means the same thing an hour later.

List the channels a session is producing, with their buffer index.

Extract the signal window around an event that already occurred. Online epoching: use it to inspect the response to the most recent stimulus, or to verify that a stimulation artifact lands where you expect. The event must still be inside the ring buffer -- for a default 60 s buffer, that means within the last minute.

Read the session's event log. Everything lands here on one clock: board markers, annotations re-emitted by a replay, stimulation commands we dispatched, and manual notes. That is what makes a closed-loop run reconstructible afterwards without joining clocks.

Read a streaming processor's recent outputs.

Power spectral density over the most recent window. Use when band power is too coarse -- to find a peak alpha frequency, confirm a stimulation artifact, or check whether a notch actually removed the mains.

Read discrete tokens from a tokenizing processor. For feeding EEG into sequence models. Returns both the grouped tokens (one group per window) and a flat sequence, plus the vocabulary size and the channel/band layout each position corresponds to. Works with any attached processor exposing ``token_history`` -- the built-in ``band_tokenizer`` is a starting point, and your own tokenizer plugs in the same way.

Open a recording and describe it without starting playback. Use this before start_replay to see how long the file is, what channels it has, and which annotations will be re-emitted as events during replay.

List every board BrainFlow can acquire from, with ids and sampling rates. Start here when you do not know what hardware is available. Two entries need no hardware at all: ``SYNTHETIC_BOARD`` generates a signal for development, and ``PLAYBACK_FILE_BOARD`` replays a BrainFlow CSV.

List live monitors currently serving, with their URLs.

List real-time processors available to attach, and where they came from. Built-ins are always present. Your own appear here once the **server** environment points at them -- via the ``eeg_mcp.processors`` entry point, ``EEG_MCP_PLUGINS``, or ``EEG_MCP_PLUGIN_DIR``. They cannot be loaded from a tool call, because importing a module executes it and that would make arbitrary code execution reachable from a model.

List all events present in a replay session's source file. Distinct from get_events: this is the *complete* event list from the file, including events that have not been reached yet. get_events returns only what has actually been emitted so far.

List recordings in eeg-mcp's own metadata store, newest first. This store belongs to eeg-mcp alone. Analysis tools read from it -- the schema is compatible with neuro-mcp's, so it can open this database and understand every row -- but nothing else writes to it.

List all active stream and replay sessions with a one-line summary each.

List stimulation targets, their options, and which ones drive hardware. Software backends ('log', 'lsl', 'brainflow_marker') are always available. Hardware backends ('serial_ttl', 'tms', 'tes', 'template_serial') require the server to have been started with EEG_MCP_ALLOW_HARDWARE_STIM=1, and must be armed before each session of use.

Record an event against the stream's clock. For anything the server did not generate itself: a task onset, a subject report, an experimenter note. Stimulation commands are logged automatically by send_stim_event, so do not log those by hand.

Render the power spectrum and band composition as a standalone HTML file.

Render the recent signal as a standalone HTML file and return its path. A frozen snapshot, unlike start_monitor -- use it to keep a record, attach to a note, or share. The file inlines everything and needs no internet.

Report attached processors, their health, and their cost. ``mean_ms`` and ``max_ms`` are the numbers to watch for a streaming processor: if ``max_ms`` approaches the poll interval (50 ms by default) it is starving acquisition, which shows up as ``throughput_ratio`` below 1.0 in stream_status. A processor that raises 10 times is disabled automatically rather than being retried forever inside the producer loop.

Read the most recent samples from the buffer. Returns filtered signal when a filter chain is set (see set_filters), otherwise raw. Long windows are decimated to ``max_samples`` per channel so the response stays readable -- for numeric work prefer get_band_power or get_psd, which compute on the full-resolution data.

Report whether a session is recording, and how much has been written.

Finish a recording whose process died before it could be closed. Samples are appended to disk as they arrive and the header is written up front, precisely so an interrupted session is not lost. Point this at the orphaned ``.eegmcp.json`` header to convert what was captured into a ``.fif``. Events are not recoverable -- they lived in memory -- so the resulting file carries signal without annotations.

Pause, resume, seek, or change the speed of a replay session.

Clear accumulated processor state and outputs, without detaching them. Useful between experimental blocks, and after a replay seek, so a rolling window does not straddle the discontinuity.

Run a processor once on the most recent window, on demand. Works for both modes: for a non-streaming processor this is the only way to execute it, and for a streaming one it is a way to get an answer right now rather than waiting for its next scheduled output.

Deliver one stimulation command, and log it against the EEG clock. The event is written to the session log whether the transport succeeds or fails -- a failed stimulation attempt matters just as much to the record. When the acquisition source supports markers, the same event is also punched into the stream itself so the recording is self-describing.

Deliver a regular train of pulses, blocking until it completes. For rTMS bursts and repeated cues. The call holds until the train finishes, so it is capped at 1000 pulses and 60 seconds total; build longer protocols from several calls so there are decision points in between. Every pulse is logged individually, so the event log reconstructs the exact delivered timing rather than the intended timing.

Install a stateful online filter chain on a running stream. The chain filters continuously in the background as samples arrive, carrying filter state across chunk boundaries. This matters: filtering each query window independently would inject a transient at every boundary and corrupt any phase-sensitive measure. Filtered output goes to a second buffer, so raw signal remains available via read_window(filtered=False). These are causal filters -- there is no zero-phase option, because that needs future samples. Check ``group_delay_sec`` in the response to know how far behind real time your filtered features are.

Open a live browser view of a running session and return its URL. Serves a rolling traces view with event markers, band power and per-channel quality, refreshing continuously. This is the tool for "let me watch the recording" -- a static plot cannot answer whether the signal is good *now*. With ``allow_control`` (the default) the page also carries transport buttons: play/pause, restart, skip, speed, stop, mark an event, and save a report. Pass ``allow_control=false`` for a strictly read-only view, e.g. when showing the screen to someone who should not be able to alter the run. The page is bound to 127.0.0.1 only and requires a random per-monitor token, so it is not reachable from the network. It is still unencrypted: do not expose it through a tunnel or reverse proxy.

Begin writing the live signal to disk, continuously. Call this as soon as the session starts if you intend to keep the data. The ring buffer only holds the last minute or so, so anything not recorded is gone -- a session streamed for an hour without recording leaves nothing but whatever reports you exported. The raw, unfiltered signal is written. Filter settings are stored alongside it so a filtered view is reproducible; the amplifier's actual output is not reconstructible from anything else.

Replay a recording against a wall clock, re-emitting its events. This is the safe way to build a real-time pipeline: the session behaves exactly like a live stream -- same buffering, same chunked delivery, same tools -- so code developed here runs unchanged against hardware. The recording's annotations arrive in the event log at their original timings.

Open a board and begin buffering EEG in the background. Data flows into a ring buffer from a background thread as soon as this returns, so a subsequent read_window will have samples waiting. The session keeps running until stop_stream is called.

Report attached stimulation backends, arming state, and dispatch counts.

Close a session's live monitor and free its port.

Finish the recording, write the ``.fif``, and register it for analysis. The event log becomes annotations inside the file, and -- unless you pass ``register=false`` -- a row is inserted into the metadata store with the subject, task, run and provenance, so neuro-mcp can find and open it.

Stop a stream and release the board, serial ports, and LSL outlets. Always call this when finished. A board left prepared can block the next process from acquiring the device.

Health and timing report for a session. The fields that matter for closed-loop work: ``throughput_ratio`` below 1.0 means the producer is not keeping up and samples are being dropped; ``filters.group_delay_sec`` is how far behind real time a filtered feature is; ``last_error`` explains a stopped producer. For an LSL session, ``connection`` reports whether the underlying BLE bridge is currently attached, and how many times it has silently reconnected -- check ``get_events(origin="annotation")`` for the ``source_reconnected`` records, which carry each gap's length.