io.github.dappros/ethora-mcp-cli

Upload documents (PDF, text, etc.) into an app's RAG sources so the app's AI bot can answer from them (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-delete` (remove), `ethora-sources-site-crawl` (ingest a URL instead). For app-token / B2B flows use `ethora-sources-docs-upload-v2`.

Upload documents (PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-sources-docs-upload`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: stores each document and starts a parse + embedding job; content becomes queryable RAG context once indexing finishes (not synchronous). Idempotent: no — re-uploading the same document creates another source record. Input design: files are base64 so the MCP server never reads your local filesystem. Client-side guardrail rejects any single file over 50MB; the server enforces its own limits too. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; 413 if too large; 422 on an unsupported document type. Per-call limit: 1–5 files. Related: `ethora-sources-docs-list-v2` (see results), `ethora-sources-docs-delete-v2` (remove), `ethora-sources-docs-tags-update-v2` (tag).

Crawl a website URL and ingest its content into an app's RAG sources, so the app's AI bot can answer from it (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a crawl + embedding job on the server; pages become queryable RAG context once indexing finishes (not synchronous). With `followLink: true` the crawler also follows in-domain links, which can ingest many pages. Idempotent: no — re-crawling the same URL adds/updates source records; combined with `followLink` it can fan out broadly. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-reindex` (refresh), `ethora-sources-site-delete-url` (remove), `ethora-sources-docs-upload` (ingest documents instead of a URL). For app-token / B2B flows use `ethora-sources-site-crawl-v2`.

Crawl a website URL and ingest its content into an app's RAG sources (app-token / B2B variant of `ethora-sources-site-crawl`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a crawl + embedding job; pages become queryable RAG context once indexing finishes (not synchronous — this returns once the job is accepted). With `followLink: true` the crawler also follows in-domain links and can ingest many pages. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 404 if `appId` is invalid. Related: `ethora-sources-site-crawl-v2-wait` (block until done), `ethora-sources-site-list-v2` (see results), `ethora-sources-site-reindex-v2` (refresh), `ethora-sources-site-delete-url-v2` (remove).

Crawl a website URL and block until the server finishes the request — a single-call, long-timeout variant of `ethora-sources-site-crawl-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-crawl-v2` (crawl + embed into RAG sources), but this MCP call blocks for up to `timeoutMs` waiting for the server's response instead of returning as soon as the job is accepted. Idempotent: no — re-crawling adds/updates source records. Failure modes: 401/403 on missing/wrong auth; 400 if `url` is malformed; 504/timeout if the crawl takes longer than `timeoutMs` (the job may still complete server-side — check with `ethora-sources-site-list-v2`). Returns: `{ done: true, durationMs, result }`. Use the non-wait `ethora-sources-site-crawl-v2` if you'd rather not block.

Bulk-remove crawled URLs from an app's RAG sources in one call, matched by exact url strings (legacy owner/admin user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes each matching source record and its embeddings. Not reversible. Idempotent: yes — URLs not present are skipped. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` is invalid. Per-call limit: 1–100 URLs. When to use: cleaning up many pages at once. For the single-URL variant use `ethora-sources-site-delete-url`; for app-token / B2B flows use `ethora-sources-site-delete-url-v2-batch`.

Remove a single crawled URL from an app's RAG sources, matched by its exact url string (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: deletes the source record and its embeddings; the app's bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if the exact `url` string isn't a crawled source. Note: matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several at once use `ethora-sources-site-delete-records-v1`.

Remove a single crawled URL from an app's RAG sources, matched by its exact url string (app-token / B2B variant of `ethora-sources-site-delete-url`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: deletes the source record and its embeddings; the bot can no longer answer from that page. Not reversible (re-add via `ethora-sources-site-crawl-v2`). Idempotent: yes — deleting an already-removed URL is a no-op / 404. Failure modes: 401/403 on missing/wrong auth; 404 if the exact `url` isn't a crawled source. Matches on the exact URL string — get the stored value from `ethora-sources-site-list-v2`. To delete several by id use `ethora-sources-site-delete-url-v2-batch`.

List an app's crawled website sources, including each source's id, URL, and current RAG tags. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` is invalid; returns an empty list if nothing has been crawled. Returns: site source records. Their ids feed `ethora-sources-site-tags-update-v2`, `ethora-sources-site-delete-url-v2-batch`, and `ethora-sources-site-reindex-v2` (`urlId`).

Re-crawl and re-embed a previously crawled URL by its `urlId`, refreshing the RAG content for that page (legacy user-auth route). Auth: user-auth mode with an active user session; the user must own the app. Side effects: starts a refresh job on the server; the page's existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes the same record again. Failure modes: 401 if not logged in; 403 if the user doesn't own the app; 404 if `appId` or `urlId` is unknown. When to use: the source page changed and you want the bot to pick up the new content. Get `urlId` values from `ethora-sources-site-list-v2`. For app-token / B2B flows use `ethora-sources-site-reindex-v2`.

Re-crawl and re-embed a previously crawled URL by its `urlId`, refreshing its RAG content (app-token / B2B variant of `ethora-sources-site-reindex`). Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: starts a refresh job; the existing source record is updated in place once indexing finishes (not synchronous). Idempotent: effectively yes — re-running just refreshes again. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown. Get `urlId` values from `ethora-sources-site-list-v2`. Use `ethora-sources-site-reindex-v2-wait` to block until done.

Re-crawl and re-embed a previously crawled URL and block until the server finishes — a single-call, long-timeout variant of `ethora-sources-site-reindex-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: same as `ethora-sources-site-reindex-v2` (refresh the source record's RAG content), but this MCP call blocks for up to `timeoutMs`. Idempotent: effectively yes. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `urlId` is unknown; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side). Returns: `{ done: true, durationMs, result }`. Get `urlId` values from `ethora-sources-site-list-v2`.

Set the RAG retrieval tags on a crawled website source. Tags let the bot's `ragTags` setting narrow which sources it retrieves from. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`) OR B2B mode with an explicit `appId`. Side effects: **replaces** the source's tag set with the provided `tags` array (it is not additive — pass the full desired set, or an empty array to clear all tags). Idempotent: yes — re-sending the same tags is a no-op. Failure modes: 401/403 on missing/wrong auth; 404 if `appId` or `sourceId` is unknown. Get `sourceId` values from `ethora-sources-site-list-v2`. The doc equivalent is `ethora-sources-docs-tags-update-v2`.

Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present, and the currently selected appId/agentId. Auth: none required. Side effects: none — read-only. Idempotent: yes. Failure modes: effectively none. Returns: a state object with booleans like `hasAppJwt` / `hasB2BToken` / `hasUserToken` (credential *values* are never echoed back). Use it to decide which `ethora-auth-use-*` tool to call next, or run `ethora-doctor` for an active connectivity check.

Authenticate as an existing Ethora user with email + password. Auth: user-auth mode (call `ethora-auth-use-user` first) and a configured `appJwt` (env or `ethora-configure`). Side effects: stores the resulting user session token in this MCP session; unlocks user-auth tools (`ethora-app-list`, `ethora-app-create`, `ethora-files-*`, `ethora-wallet-*`). Idempotent: yes — safe to retry on transport failures. Failure modes: 401/403 on bad credentials; 404 if the email isn't registered; 429 if the Ethora server's per-IP login rate limit is hit (retry with backoff). Related: `ethora-user-register` (create account first), `ethora-auth-use-user` (switch mode), `ethora-status` (verify session).

Register a new Ethora end-user account by email + first/last name. Auth: user-auth mode and a configured `appJwt` (env or `ethora-configure`) — the JWT tells the server which app the new user belongs to. Side effects: creates a pending user record on the Ethora server and triggers a verification email to the address; the user must click the link in that email before `ethora-user-login` will succeed. Idempotent: safe to retry on transport failures (server deduplicates by email within an app). Calling twice with a fresh email creates one account; calling with an already-registered email returns 422. Failure modes: 422 with a validation error if the email is already registered, if names violate server rules, or if the configured `appJwt` is invalid; 401 if no `appJwt` is configured. When to use: end-user self-serve sign-up flows. For bulk B2B user provisioning prefer `ethora-users-batch-create-v2`.

Provision many Ethora users in one asynchronous batch job — the bulk equivalent of `ethora-user-register`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: enqueues a background job (server responds HTTP 202) — users are **not** created synchronously. Each user is created under the B2B tenant's app. With `bypassEmailConfirmation: true` users are usable immediately; otherwise each receives a verification email. Idempotent: no — re-running re-attempts creation; the job itself reports per-user conflicts (already-registered emails) rather than failing the whole batch. Failure modes: 401/403 if not in B2B mode; 422 if the `usersList` fails validation. Per-call limit: 1–100 users. Returns: `{ jobId, statusUrl }`. Track it with `ethora-users-batch-job-v2` (one-shot) or `ethora-wait-users-batch-job-v2` (poll to completion).

Fetch the current status and per-user results of a users batch job by `jobId` (one-shot, no polling). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none — read-only. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: the job object including its `state` (`pending` / `running` / `completed` / `failed`) and per-user outcomes (created / conflict / error). For a blocking wait-until-done, use `ethora-wait-users-batch-job-v2`.

Block until a broadcast job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-chats-broadcast-job-v2` calls. Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 on missing/wrong auth; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when the job finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-chats-broadcast-job-v2`).

Block until a users batch job reaches a terminal state (`completed` or `failed`), or until a timeout — a convenience wrapper around repeated `ethora-users-batch-job-v2` calls. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in B2B mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` if `timeoutMs` elapsed first (the job may still finish later — re-check with `ethora-users-batch-job-v2`).

Read the on-chain wallet balance for the currently authenticated user, across the ERC-20 token(s) the Ethora backend tracks for them. Auth: user-auth mode and an active user session (call `ethora-user-login` first). Side effects: none — read-only, no gas consumed. Idempotent: yes — safe to call repeatedly. Failure modes: 401 if not logged in; 503 if the wallet RPC is temporarily unreachable (safe to retry on 503 with backoff). Returns: balances in the units the Ethora backend reports (typically whole-token integers — confirm with your deployment). Pair with `ethora-wallet-erc20-transfer` to spend.

Dot-namespaced alias for `ethora-b2b-app-bootstrap-ai` — one-call B2B orchestrator: create an app, index RAG sources, then configure and enable its AI bot. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: runs multiple real operations in sequence (app create, source ingest, bot configure/enable); source ingestion and bot activation are best-effort, so the app is still created even if a later step fails. Not idempotent — each call creates a new app. Failure modes: aborts with the partial step log if app creation fails; previous auth mode restored best-effort on error. Returns: a per-step result log including the new `appId`. Provided for agents that prefer dotted names; behavior matches `ethora-b2b-app-bootstrap-ai`.

Dot-namespaced alias for `ethora-b2b-app-create` — create a new Ethora app server-side. Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: provisions a new app record owned by the B2B tenant and allocates a fresh `appId`. Not idempotent — each call creates a new app. Failure modes: 401/403 if not in B2B mode; 422 on an invalid `displayName`. Provided for agents that prefer dotted names. Prefer `ethora-b2b-app-create` in new integrations.

Dot-namespaced alias for `ethora-auth-use-b2b` — switches the session's active auth mode to B2B (`x-custom-token`). Auth: requires a `b2bToken` to already be configured. Side effects: session state only; no API call. Idempotent: yes. Provided to reduce auth-mode mistakes for agents that prefer dotted names; behavior is identical to `ethora-auth-use-b2b`.

Dot-namespaced alias for `ethora-b2b-bot-enable` — turn on the AI bot for an app (sets `botStatus: "on"`). Auth: B2B mode (`ethora.b2b.auth.use` / `ethora-auth-use-b2b` + a configured `b2bToken`). Side effects: flips the app's bot status to on; the backend then makes a best-effort activation. The bot only responds if a prompt + LLM are configured and the backend has an AI service set up. Idempotent: yes — enabling an already-on bot is a no-op. Failure modes: 401/403 if not in B2B mode; 404 if `appId` is invalid; 400 if no `appId` is given and none is selected. Provided for agents that prefer dotted names. Prefer `ethora-b2b-bot-enable` in new integrations.

Dot-namespaced sibling of `ethora-wait-broadcast-job-v2` — block until a broadcast job reaches a terminal state (`completed` / `failed`) or until a timeout. Auth: app-token mode (despite the `b2b` in the name, this variant uses app-token auth — `ethora-app-select` + `ethora-auth-use-app`). Use `ethora-wait-broadcast-job-v2` if you need the B2B-with-explicit-appId path. Side effects: none server-side — read-only polling. Blocks this MCP call for up to `timeoutMs`. Idempotent: yes. Failure modes: 401/403 if not in app-token mode; 404 if the `jobId` is unknown. Returns: `{ done: true, state, job }` when finished, or `{ done: false, reason: "timeout", job }` on timeout.