# MCP tools

> All 54 tools firenook mcp gives a coding agent, by group, with what each does and the parameters it takes.

`firenook mcp` serves these 54 tools to a coding agent, in this order. The
list is what the server answers to `tools/list` in 0.2.0. To connect
an agent, see [Connect your coding agent](https://firenook.dev/docs/tools/mcp).

Two marks recur below:

- **needs the console**: the tool goes through the engine's Console API,
  which the suite serves on the UI port. While the UI is off
  (`emulators.ui.enabled: false`), the tool answers with an error that
  says so. The other tools talk to the emulators' own ports.
- **destructive**: the tool deletes emulator data.

Each group says the name `--only` takes for it, so
`npx firenook mcp --only firestore,auth` serves the status tools and those
two groups. Firestore values are plain JSON, with `{"$timestamp"}`,
`{"$ref"}`, `{"$geo"}` and `{"$bytes"}` for the types JSON lacks, so a
document read back can be written again unchanged. A call with a missing or
unknown parameter fails before it reaches the emulators, with the reason.

## Status

Always served, whatever `--only` says.

- `firenook_status`: The running Firenook suite: how the project was found, hub locator, hub status, the emulators listing (host and port per service) and the CLI version; with no project, the suites whose locators answer.
- `emulators_export`: Export the running Firestore, Auth and Storage data to a directory outside the project (firenook emulators:export).
  - `path` (required), string: Destination directory
  - `force`, boolean: Overwrite a non-empty foreign directory

## Firestore

Served with `--only firestore`.

- `firestore_get`: Read one Firestore document by path (collection/document[/subcollection/document]); returns its fields as plain JSON or exists:false.
  - `path` (required), string: Document path, e.g. users/alice
  - `database`, string: Firestore database id; default (default)
- `firestore_query`: Run a structured query over one collection, or with collectionGroup over every collection with that id (Firestore runQuery): optional where filters, ordering and limit; returns matching documents as plain JSON.
  - `collection` (required), string: Collection path, e.g. users or users/alice/posts; with collectionGroup a collection id (posts) or a path whose parent bounds it
  - `database`, string: Firestore database id; default (default)
  - `where`, array: Filters combined with AND
  - `orderBy`, array: Sort keys
  - `limit`, integer: Maximum documents; default 50
  - `collectionGroup`, boolean: Collection-group query: every collection with the last segment's id at any depth under the parent (the database root for a bare id, e.g. posts; users/alice/posts for one document's descendants)
- `firestore_count`: Count the documents of a collection, or with collectionGroup of every collection with that id, that match optional where filters (a COUNT aggregation; no documents are read back).
  - `collection` (required), string: Collection path, or a collection id with collectionGroup
  - `database`, string: Firestore database id; default (default)
  - `where`, array: Filters combined with AND
  - `collectionGroup`, boolean: Collection-group query: every collection with the last segment's id at any depth under the parent (the database root for a bare id, e.g. posts; users/alice/posts for one document's descendants)
- `firestore_set`: Write a Firestore document from plain JSON: replaces it, or with merge:true updates only the given top-level fields.
  - `path` (required), string: Document path
  - `data` (required), object: Fields as plain JSON
  - `merge`, boolean: Merge into the existing document
  - `database`, string: Firestore database id; default (default)
- `firestore_delete`: Delete a document (recursive:true also its subcollections) or a collection (its documents; recursive:true everything beneath) through the emulator delete route.
  - `path` (required), string: Document or collection path
  - `recursive`, boolean: Also delete nested collections
  - `database`, string: Firestore database id; default (default)
- `firestore_list_collections`: List collection ids at the database root or under a document (listCollectionIds).
  - `path`, string: Document path; omit for the root collections
  - `database`, string: Firestore database id; default (default)

## Authentication

Served with `--only auth`.

- `auth_list_users`: List Auth emulator accounts (accounts:batchGet) with uid, email, phone, display name, claims and provider data.
  - `maxResults`, integer: Page size; default 100
  - `pageToken`, string: Continue a previous listing
- `auth_get_user`: Look up one Auth account by uid, email or phone number (accounts:lookup).
  - `uid`, string: Account id (localId)
  - `email`, string: Email address
  - `phoneNumber`, string: Phone number in E.164 form
- `auth_create_user`: Create an Auth emulator account with a synthetic email/password, phone number or display name (never real credentials).
  - `uid`, string: Account id to assign
  - `email`, string: Email
  - `password`, string: Password
  - `phoneNumber`, string: Phone number
  - `displayName`, string: Display name
  - `photoUrl`, string: Photo URL
  - `emailVerified`, boolean: Mark the email verified
  - `disabled`, boolean: Create the account disabled
- `auth_delete_user`: Delete one Auth emulator account by uid (accounts:delete).
  - `uid` (required), string: Account id
- `auth_oob_codes`: The pending out-of-band codes (email verification, password reset, sign-in links) the Auth emulator holds instead of sending email.
- `auth_verification_codes`: The pending phone verification codes the Auth emulator holds instead of sending SMS.
- `auth_mint_token`: Mint a Firebase ID token (valid one hour) and refresh token for an existing Auth emulator user, so an agent can call a function or the REST API as that user; claims replace the custom claims for this token only.
  - `uid` (required), string: Account id
  - `tenant`, string: Tenant id; omit for a project-level user
  - `claims`, object: Custom claims for this token only (nothing is stored); omit for the user's own
  - `provider`, string: Sign-in provider the token names, e.g. password or phone; default the user's first
- `auth_set_claims`: Set an Auth emulator user's custom claims: replace them (as the Admin SDK's setCustomUserClaims does) or with mode merge change only the given keys (a null value removes that key).
  - `uid`, string: Account id
  - `uids`, array: Several account ids (instead of uid)
  - `tenant`, string: Tenant id; omit for a project-level user
  - `claims` (required), object: Custom claims as JSON
  - `mode`, string: Default replace
- `auth_remove_claims`: Remove the named custom claim keys from an Auth emulator user, keeping its other claims.
  - `uid`, string: Account id
  - `uids`, array: Several account ids (instead of uid)
  - `tenant`, string: Tenant id; omit for a project-level user
  - `keys` (required), array: Claim names to remove
- `auth_disable_user`: Disable an Auth emulator account: its sign-ins and token refreshes fail until it is enabled again.
  - `uid`, string: Account id
  - `uids`, array: Several account ids (instead of uid)
  - `tenant`, string: Tenant id; omit for a project-level user
- `auth_enable_user`: Enable a disabled Auth emulator account again.
  - `uid`, string: Account id
  - `uids`, array: Several account ids (instead of uid)
  - `tenant`, string: Tenant id; omit for a project-level user
- `auth_revoke_tokens`: Revoke an Auth emulator user's refresh tokens (validSince moves to now), so its existing sessions must sign in again.
  - `uid`, string: Account id
  - `uids`, array: Several account ids (instead of uid)
  - `tenant`, string: Tenant id; omit for a project-level user
- `auth_list_tenants`: List the Auth emulator's tenants (multi-tenancy) with their user counts and sign-in settings.
  - `q`, string: Match tenant id or display name (substring)
  - `limit`, integer: At most this many; default 500

## Cloud Storage

Served with `--only storage`.

- `storage_list`: List Storage objects and folder prefixes under a prefix (one level, like listAll).
  - `bucket`, string: Storage bucket; default <project>.appspot.com
  - `prefix`, string: Folder prefix, e.g. uploads/ (a trailing slash is added)
  - `maxResults`, integer: Page size; default 100
  - `pageToken`, string: Continue a previous listing
- `storage_get_metadata`: The metadata of one Storage object (content type, size, timestamps, custom metadata, download tokens) or exists:false.
  - `bucket`, string: Storage bucket; default <project>.appspot.com
  - `path` (required), string: Object path, e.g. uploads/photo.png
- `storage_read`: Read a Storage object's content: text inline (text, JSON, XML, SVG...), anything else as base64; at most maxBytes are returned and truncated says whether there is more.
  - `bucket`, string: Storage bucket; default the suite's default bucket
  - `path` (required), string: Object path, e.g. products/shoe.png
  - `maxBytes`, integer: Most bytes to return; default 65536, at most 1048576
  - `encoding`, string: auto (default) picks text for textual content types
- `storage_upload`: Upload (create or replace) a Storage object from text or base64 bytes with a content type and custom metadata, as the Admin SDK would (rules skipped; finalize triggers run).
  - `bucket`, string: Storage bucket; default the suite's default bucket
  - `path` (required), string: Object path, e.g. products/shoe.png
  - `text`, string: Content as text (sent as UTF-8)
  - `base64`, string: Content as base64 bytes (instead of text)
  - `contentType`, string: Content type; default text/plain for text, application/octet-stream for base64
  - `customMetadata`, object: String metadata
  - `cacheControl`, string: Cache-Control
  - `ifNotExists`, boolean: Refuse to replace an existing object
- `storage_delete`: DESTRUCTIVE: delete one Storage object, or with a path ending in / every object under that folder.
  - `bucket`, string: Storage bucket; default the suite's default bucket
  - `path` (required), string: Object path, or a folder ending in /
- `storage_copy`: Copy a Storage object (or a folder, a path ending in /) to a new path, in the same or another bucket; refuses to overwrite unless overwrite is true.
  - `bucket`, string: Storage bucket; default the suite's default bucket
  - `path` (required), string: Source object path, or a folder ending in /
  - `to` (required), string: Destination path (a folder ends in /)
  - `toBucket`, string: Destination bucket; default the source bucket
  - `overwrite`, boolean: Replace an existing destination
- `storage_move`: Move (rename) a Storage object or a folder (a path ending in /), in the same or another bucket; refuses to overwrite unless overwrite is true.
  - `bucket`, string: Storage bucket; default the suite's default bucket
  - `path` (required), string: Source object path, or a folder ending in /
  - `to` (required), string: Destination path (a folder ends in /)
  - `toBucket`, string: Destination bucket; default the source bucket
  - `overwrite`, boolean: Replace an existing destination

## Cloud Functions

Served with `--only functions`.

- `functions_list`: The functions loaded by the running suite: name, region, generation, trigger kind, event type or schedule, and the HTTPS URL of request/callable functions.
- `functions_invoke`: Invoke a loaded function: an HTTPS/callable request with data, or with eventData a background event (Firestore before/after, Storage object, Pub/Sub message, Auth user, schedule, Eventarc custom event, task queue payload) shaped as the official functions shell sends it.
  - `name` (required), string: Function name
  - `region`, string: Region when the name is deployed in several
  - `data`: Callable payload (sent as {"data": ...})
  - `eventData`: Background event payload; its shape depends on the trigger
  - `resource`, string: Firestore document path or the legacy resource name
  - `params`, object: Wildcard values for the trigger pattern
  - `auth`, object: {"uid","token"} or {"admin":true} for first-generation events
  - `eventType`, string: Override the CloudEvent type for Eventarc custom events
  - `method`, string: HTTP method for plain HTTPS functions; default POST
- `functions_list_calls`: Recent function calls, newest first: trigger kind and cause, outcome (succeeded, failed, timedOut, crashed...), HTTP status, duration and the first line of the error.
  - `function`, string: Only this function: its name or <region>-<name> id
  - `kind`, string: Only this trigger kind
  - `outcome`, string: Only calls that ended this way
  - `q`, string: Extra filter terms, e.g. took:>200ms status:>=500 is:cold
  - `limit`, integer: At most this many; default 20
  - `cursor`, string: nextCursor of a previous listing
- `functions_get_call`: One function call in full: its cause, request (method, path, headers, body), response (status, body), event payload, the error with its stack trace, the call's console output and timings.
  - `id` (required), string: Call id from functions_list_calls
  - `maxBodyChars`, integer: Cut each body at this many characters; default 16384
- `functions_replay_call`: Run a recorded function call again with the same request or event (after a fix, say) and report the new call: outcome, status, response body and its id for functions_get_call.
  - `id` (required), string: Call id from functions_list_calls
  - `maxBodyChars`, integer: Cut the response body at this many characters; default 16384

## Logs

Served with `--only logs`.

- `logs_search`: Search the suite's log (every emulator and every function's console output) by service, level, function, call, text and time; returns the newest matching lines, oldest first.
  - `service`, array: Only these services (any of)
  - `level`, array: Only these levels (any of), e.g. ["warn","error"]
  - `function`, string: Only this function's lines: its name or <region>-<name> id
  - `execution`, string: Only one function call's lines: the call id from functions_list_calls
  - `text`, string: Case-insensitive text the message or payload contains
  - `q`, string: Extra filter terms in the console's grammar, e.g. kind:rules.denied payload.orderId:o1 -level:debug
  - `from`, string: Lines at or after: RFC 3339, YYYY-MM-DD, today, reload (since the last Functions reload) or relative like -15m
  - `to`, string: Lines at or before, in the same forms
  - `limit`, integer: At most this many lines; default 50
  - `before`, string: The older cursor of a previous search, for the lines before it
- `logs_facets`: Count the log lines matching a filter by level, service, function, codebase, extension instance and kind, to see where errors and warnings come from before reading them.
  - `service`, array: Only these services (any of)
  - `level`, array: Only these levels (any of), e.g. ["warn","error"]
  - `function`, string: Only this function's lines: its name or <region>-<name> id
  - `execution`, string: Only one function call's lines: the call id from functions_list_calls
  - `text`, string: Case-insensitive text the message or payload contains
  - `q`, string: Extra filter terms in the console's grammar, e.g. kind:rules.denied payload.orderId:o1 -level:debug
  - `from`, string: Lines at or after: RFC 3339, YYYY-MM-DD, today, reload (since the last Functions reload) or relative like -15m
  - `to`, string: Lines at or before, in the same forms

## Security Rules

Served with `--only rules`.

- `rules_get`: The Security Rules in force: the Firestore rules of a database and the Storage rules of a bucket (source, whether they are enforced, the file and its problems).
  - `service`, string: Only firestore or storage; default both
  - `database`, string: Firestore database id; default (default)
  - `bucket`, string: Storage bucket; default the default bucket
- `rules_evaluate`: Ask the rules in force (or a draft) whether a request would be allowed: get, list, create, update or delete on a Firestore path or Storage object as a given user or unauthenticated; returns the verdict, the rule line that decided it and each evaluated expression's value. Nothing is written.
  - `service`, string: Which rules: firestore (default) or storage
  - `method` (required), string: The operation
  - `path` (required), string: Firestore document path (a collection path for list), or the Storage object name (a folder ending in / for list)
  - `uid`, string: Act as this signed-in user; omit for an unauthenticated request
  - `claims`, object: request.auth.token: custom claims and token fields (email, firebase.sign_in_provider...)
  - `idToken`, string: Act as the user of this emulator ID token (from auth_mint_token) instead of uid/claims
  - `data`, object: Firestore create/update: the written fields as plain JSON (update: the fields set over the existing document)
  - `existing`, object | null: Firestore: the document before the request as plain JSON, or null for none; default the stored document
  - `where`, array: Filters combined with AND
  - `orderBy`, array: Sort keys
  - `limit`, integer: Firestore list: the query limit
  - `collectionGroup`, boolean: Firestore list: a collection-group query on the path's last collection id
  - `object`, object: Storage create/update: the proposed object
  - `time`, string: request.time as RFC 3339; default now
  - `source`, string: Evaluate this draft rules source instead of the rules in force
  - `database`, string: Firestore database id; default (default)
  - `bucket`, string: Storage bucket; default the default bucket
- `rules_list_denials`: Recent requests the Security Rules denied (app clients only; admin and owner requests skip the rules), newest last; with explain, the rule lines that denied each one.
  - `service`, string: Only firestore or storage; default both
  - `path`, string: Only paths starting with this
  - `uid`, string: Only this user's requests
  - `from`, string: Denials at or after: RFC 3339, today or relative like -15m
  - `limit`, integer: At most this many; default 20
  - `explain`, boolean: Fetch the deciding rule lines of each denial (at most 20)

## Pub/Sub

Served with `--only pubsub`.

- `pubsub_publish`: Publish a message to a Pub/Sub emulator topic: string data as given, other JSON as its text (base64-encoded on the wire), plus attributes.
  - `topic` (required), string: Topic name (or projects/<p>/topics/<name>)
  - `data`: Message data
  - `attributes`, object: String attributes
  - `orderingKey`, string: Ordering key
- `pubsub_list_topics`: The Pub/Sub emulator's topics with their published counts, subscriptions and the functions they trigger (schedule topics included).
- `pubsub_list_subscriptions`: Every Pub/Sub subscription (of every topic, and detached ones) with its delivery type, filter, dead-letter topic and backlog.
  - `topic`, string: Only this topic's subscriptions (id or full name)
- `pubsub_peek`: Peek at a subscription's backlog in delivery order without pulling, leasing or acking anything: each message's state, attempts, attributes and data.
  - `subscription` (required), string: Subscription id or full name
  - `state`, string: Only messages in this state; default every state
  - `limit`, integer: At most this many; default 20
  - `full`, boolean: Return each message's whole data instead of a 256-character preview
  - `cursor`, string: nextCursor of a previous peek

## Cloud Tasks

Served with `--only tasks`.

- `tasks_stats`: Queue statistics of the Cloud Tasks emulator (queueStats).
- `tasks_list`: The Cloud Tasks queues (with their pending and running counts) and the tasks waiting in them; with queue, only that queue's tasks, optionally in one state.
  - `queue`, string: Queue id, key (queue:<project>-<location>-<id>) or its function name
  - `state`, string: Only tasks in this state
  - `limit`, integer: Tasks per queue; default 20
- `tasks_run`: Dispatch one waiting Cloud Tasks task now instead of at its schedule time (it is sent on the next tick).
  - `queue` (required), string: Queue id, key or its function name
  - `id` (required), string: Task id from tasks_list

## Schedules

Served with `--only schedules`.

- `schedules_list`: The scheduled functions (onSchedule, pubsub.schedule): expression, time zone, next runs, paused state and the latest runs with their delivery.
- `schedules_run`: Run a scheduled function now: publish one tick to its schedule topic, as Cloud Scheduler would, and report the run.
  - `function` (required), string: Function name or its region-qualified id, e.g. nightlyReport or us-central1-nightlyReport

## Eventarc

Served with `--only eventarc`.

- `eventarc_publish`: Publish a custom CloudEvent to an Eventarc channel (default the project's Firebase channel), as getEventarc().channel().publish() does, and report which functions received it and how each call ended.
  - `type` (required), string: CloudEvent type, e.g. com.example.order.shipped
  - `data`: Event data as JSON
  - `text`, string: Event data as plain text (instead of data)
  - `source`, string: CloudEvent source; default firenook-mcp
  - `subject`, string: CloudEvent subject
  - `channel`, string: Full channel name or google; default projects/<project>/locations/us-central1/channels/firebase
  - `attributes`, object: Extension attributes (lowercase names, string values)
- `eventarc_list_events`: The Eventarc events the suite received, newest first (custom events, replays and the Firebase services' own), with how many functions matched, received or failed each.
  - `channel`, string: Full channel name or google; default every channel
  - `q`, string: Filter, e.g. type:com.example.* or delivery:failed
  - `limit`, integer: At most this many; default 20
  - `cursor`, string: nextCursor of a previous listing
- `eventarc_get_event`: One Eventarc event with its attributes, data and every function delivery (outcome, duration, invocation id for functions_get_call).
  - `id` (required), string: The event id from eventarc_list_events (<nonce>-<seq>), not the CloudEvent id
- `eventarc_replay_event`: Deliver a received Eventarc event again to the functions it matches (a new event, origin replay) and report the new deliveries.
  - `id` (required), string: The event id from eventarc_list_events (<nonce>-<seq>), not the CloudEvent id
  - `keepId`, boolean: Keep the original CloudEvent id; default a new one

## Extensions

Served with `--only extensions`.

- `extensions_list`: The Firebase Extensions instances the suite runs: reference and version, state (running, loading, failed) with the load error, and their function count.
- `extensions_reload`: Reload one Extensions instance (re-read its .env parameters and source, restart its functions) and report its state and functions afterwards.
  - `instance` (required), string: Instance id, e.g. resize-images

## Reset

Served with `--only reset`. Clearing one service needs nothing more.
Clearing two or more is refused unless `confirmProject` names the project
id. The refusal says what to pass, and the engine checks the same rule
again:

```text
Clearing 2 services (firestore, auth) deletes all their data; to confirm, pass confirmProject: "demo-shop" (the project id)
```

- `emulators_clear`: DESTRUCTIVE: delete all data of the chosen services (every Firestore document, every Auth user and tenant, every Storage object, every Pub/Sub topic, subscription, schema and message, every Cloud Tasks task and its history). Clearing more than one service needs confirmProject set to the project id.
  - `sections` (required), array: Services to clear
  - `confirmProject`, string: The project id, required when clearing more than one service (the console's safeguard)
  - `runTriggers`, boolean: Firestore only: run the delete triggers of the cleared documents; default false

## Next

[Connect your coding agent](https://firenook.dev/docs/tools/mcp) sets the server up, and
[the MCP page](https://firenook.dev/mcp) shows an agent using it.