diff --git a/plugins/mercator/skills/mercator-setup/SKILL.md b/plugins/mercator/skills/mercator-setup/SKILL.md new file mode 100644 index 0000000..b3816e8 --- /dev/null +++ b/plugins/mercator/skills/mercator-setup/SKILL.md @@ -0,0 +1,69 @@ +--- +name: mercator-setup +description: Install, connect, or troubleshoot Mercator in agent clients. Use for plugin setup, OAuth authorization, missing tools, connection diagnostics, and wallet funding readiness. For discovery and paid API execution on a working connection, use mercator. +license: MIT +--- + +# Mercator setup + +Connect the user's chosen agent client to Mercator and verify transport, discovery, and payment +readiness separately. Setup itself does not require a paid job or a local wallet. + +## Choose the setup path + +- **Plugin already installed:** inspect the client's MCP connection and complete its native + **Authorize** action. Reload the plugin or start a new session if tools are missing. Do not + install a second copy merely because authorization is incomplete. +- **Local client, CLI available:** run `mercator status`, then `mercator setup` for installation + or repair. Honor the user's client choice with `--client`; inspect `mercator setup --help` + for supported values. Interactive setup selects detected clients; preserve unrelated clients. +- **Local client, CLI absent:** use the canonical standalone installer below. It installs the CLI + and starts setup without requiring Node.js. Pass `--client` when the user chose a client. +- **Managed or cloud host:** use its native plugin and OAuth controls. Installing a CLI in an + agent container does not configure the user's desktop client. +- **Other MCP client:** `mercator setup --manual` prints configuration guidance without modifying + integrations. Configure Streamable HTTP at `https://mercator.sh/mcp/auth` and finish + OAuth in that client. If client registration is required, read + [Mercator authentication](https://mercator.sh/auth.md). + +```bash +curl -fsSL https://mercator.sh/install.sh | sh +``` + +For a selected client, append setup arguments with `sh -s -- --client `. +Grok CLI authorization is handled by `mercator setup --client grok`; it uses browser OAuth with +loopback PKCE. Use `--force` only when the registration needs replacing. OpenClaw and Hermes use +runtime-native MPP wallets and the legacy `/mcp` endpoint; retain their setup-managed configuration. + +## Verify without spending + +1. Inspect native MCP status. If the CLI is available, run `mercator doctor`. A valid OAuth + challenge proves transport availability, not successful authorization or paid readiness. +2. Complete browser authorization if needed. The user chooses wallet access limits and expiry; + never request a wallet key or copy OAuth tokens into chat or commands. +3. On the connected server, call the free `search_services` tool with a simple data lookup to + verify discovery. Do not submit a job as a connection test. +4. Call `get_connection_status` to inspect hosted authorization, token balances, access-key + expiry/status, and remaining limits. Unavailable chain reads mean unknown, not zero. A `ready` + key can make its first payment using its signed grant ceiling before live limits activate. + `oauthAuthenticated: false` identifies the legacy payment-challenge path, not a hosted grant. + +Report what was verified and what still needs user action. Zero funding or zero spending authority +can coexist with successful connection and discovery. Once connected, use the `mercator` skill for +requested research or API execution. + +## Troubleshoot the failed layer + +| Symptom | Next action | +| --- | --- | +| Plugin or server missing | Check the selected client's registration with native controls or `mercator status`; rerun targeted setup when absent. | +| Tools missing after install | Reload the plugin or start a fresh session; inspect the client's MCP status. | +| HTTP 401 or authorization pending | Complete native browser authorization; for Grok CLI, rerun its targeted setup. | +| Discovery not verified | Resolve transport or OAuth first, then retry the free search probe. | +| Search works, paid execution unavailable | Inspect connection status for funding, expiry, revocation, and token limits. | +| Unfunded authorized token | Open `https://mercator.sh/account` or use `fund_wallet` when available; the user chooses the funding amount. | +| Expired/revoked key or insufficient authority | Manage the grant in Account and reconnect through OAuth for user-selected limits. | +| Setup failure persists | Run `mercator setup --client --verbose` for the affected client and inspect its bounded diagnostics. | + +Do not install or create a local payment wallet to repair hosted OAuth. Never include credentials, +OAuth codes, payment material, or raw provider data in diagnostics shared with others. diff --git a/plugins/mercator/skills/mercator-setup/agents/openai.yaml b/plugins/mercator/skills/mercator-setup/agents/openai.yaml new file mode 100644 index 0000000..5c0a8d4 --- /dev/null +++ b/plugins/mercator/skills/mercator-setup/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Mercator setup" + short_description: "Connect and troubleshoot Mercator clients" + default_prompt: "Use $mercator-setup to connect Mercator and verify readiness without spending." diff --git a/plugins/mercator/skills/mercator/SKILL.md b/plugins/mercator/skills/mercator/SKILL.md index 0ff28bc..776c07e 100644 --- a/plugins/mercator/skills/mercator/SKILL.md +++ b/plugins/mercator/skills/mercator/SKILL.md @@ -1,6 +1,6 @@ --- name: mercator -description: Use Mercator to discover, quote, and run fresh external research or API actions across extraction, enrichment, social, maps, travel, communications, media, financial, and on-chain data. Covers MCP job submission, durable status tracking, and recovery; not for local files, repository work, supplied-content reasoning, or requests that forbid external or paid services. +description: Use Mercator to discover, quote, and run fresh external research or API actions across extraction, enrichment, social, maps, travel, communications, media, financial, and on-chain data. Covers MCP job submission, durable status tracking, and recovery; not for installation or connection troubleshooting (mercator-setup), local files, repository work, supplied-content reasoning, or requests that forbid external or paid services. license: MIT --- @@ -11,6 +11,9 @@ outcome needs external capabilities, especially when it spans providers or domai direct tool clearly covers the complete outcome with less overhead, use it. Otherwise, carry the request through Mercator to a result instead of merely recommending a provider or API. +For installation, OAuth connection, missing tools, or readiness troubleshooting, use the +`mercator-setup` skill when available. Setup uses free diagnostics; it does not require a paid job. + ## Decide quickly Use Mercator when all are true: @@ -28,40 +31,53 @@ fastest way to determine whether Mercator can complete the request. ## Default workflow -`search_services` -> optional `describe_service` -> `quote_plan` -> approval -> `create_job` -> +`search_services` -> optional `describe_service` -> `quote_plan` -> `create_job` -> `get_job` +If payment capability is uncertain, or `create_job` unexpectedly requests payment, call +`get_connection_status`. `oauthAuthenticated: true` means the current request has a valid hosted +wallet OAuth grant. The response includes its public wallet address, payment-token balances, +access-key expiry and status, grant ceilings, and live remaining limits. A `ready` access key can +make its first payment; use its signed grant ceiling even if its live remaining limit is zero before +activation. Treat `unavailable` reads as unknown, not zero. `oauthAuthenticated: false` means the +client is using the legacy MCP payment-challenge path and has no inspectable hosted account. Never +request or expose credentials. + 1. **Search for the outcome.** Give `search_services` the user's complete intended outcome, constraints, and deliverable. Use static resolution unless current provider availability matters. -2. **Make the smallest complete plan.** Follow `nextTool`. Call `describe_service` only when an exact +2. **Make the smallest complete plan.** Plans contain 1-10 nodes. Follow `nextTool`. Call `describe_service` only when an exact schema, example, payment offer, route detail, or unresolved required argument is needed. Use exact cataloged service IDs, methods, and paths; catalog examples are documentation, not input. 3. **Quote before execution.** Call `quote_plan` on the complete plan. Discovery, descriptions, and quoting are free. If the plan changes, quote it again. -4. **Confirm scope and cost.** Before submitting the job, briefly state what will run and show - `totalAmount`. Proceed only when the requested actions are authorized and either the user accepts - the quote or a previously supplied budget covers it. A budget authorizes cost, not extra actions. +4. **Respect scope and spending limits.** With hosted OAuth, the connected access key authorizes + Mercator spending within its signed limits; do not ask for per-job spend approval. Respect any explicit user budget + and execute only the requested actions. Legacy `mcp_challenge` clients have no hosted grant: + get quote approval or use a sufficient explicit budget before paid execution, including REST fallback. 5. **Submit once.** Generate one stable 8-200 character idempotency key and call `create_job` with - the unchanged quoted plan and the accepted `totalAmount` as `approved_total`. If the refreshed - quote differs, no charge is made: quote again and ask the user to accept the new total. In an - OAuth-connected host, Mercator charges the browser-authorized, policy-bounded wallet capability - and returns the job directly. Connecting that wallet is standing authorization for autonomous - charges within its signed limits; no per-job wallet or browser confirmation follows. Continue - immediately; do not wait for the user to send a second "approved" message. The agent host receives - no wallet private key. Other clients complete payment challenges through MCP metadata. If MCP - submission and one retry both fail, a host that already + the unchanged quoted plan and `totalAmount` as `approved_total`. If the refreshed quote differs, + no charge is made: quote again and proceed within the access-key limits and any explicit user + budget. Legacy clients need approval of the new total unless an explicit budget covers it. + In an OAuth-connected host, Mercator charges the bounded wallet capability and returns + the job directly. The agent host receives no wallet private key. Other clients complete payment + challenges through MCP metadata. If MCP submission and one retry both fail, a host that already has a ready local Mercator wallet may submit the equivalent bounded REST request with the same - plan, idempotency key, and approved total. Never install, create, or connect a wallet for fallback. + plan, idempotency key, and approved total. That separate local wallet needs quote approval or a + sufficient explicit budget; a hosted grant does not authorize it. Never install, create, or connect + a wallet for fallback. 6. **Listen for completion.** Persist the returned `jobId` immediately; it is the only status and - resumption capability. Poll `get_job` with bounded backoff. `ready:false` means the durable job is - still pending or running. `ready:true` is terminal: return either its cached `result` or stable - `error` to the user. A client timeout or disconnect does not cancel the job. Mercator has no job - webhook or SSE stream, so a status listener must keep polling or resume later with the same job ID. + resumption capability. Poll `get_job` with bounded backoff. Its default inline mode preserves the + complete cached result. For potentially large jobs, request summary mode and call + `get_job_details` with both `job_id` and `node_id` for each needed ID in `result_node_ids`; use `result_pointer` to retrieve one field + from a large node payload. `ready:false` means the durable job is still + pending or running. `ready:true` is terminal: return either its cached results or stable `error` + to the user. A client timeout or disconnect does not cancel the job. Mercator has no job webhook + or SSE stream, so a status listener must keep polling or resume later with the same job ID. For a warm Grok Bot installation, target less than two minutes from the user's request to a terminal -result, excluding the user's time reviewing the quoted charge. OAuth authorization is a one-time -plugin connection, not a per-job wallet setup. Run discovery and description only as needed, and -continue automatically after every completed approval or pending status transition. +result. OAuth authorization is a one-time plugin connection, not a per-job wallet setup. Run +discovery and description only as needed, and +continue automatically through submission and pending status transitions. ## Hard boundaries @@ -85,9 +101,20 @@ continue automatically after every completed approval or pending status transiti - If status polling is interrupted, resume `get_job` with the job ID. Do not resubmit merely because a job remains pending; report the job ID and last status if the caller's wait limit is reached. - Use `create_job_review` only when the user wants to review a completed job. Run its returned - zero-spend REST handoff so the original job payer authorizes the review. Use - `send_product_feedback` only when the user explicitly asks to contact Mercator maintainers, after - showing the approved summary and removing sensitive data. - -Read [examples](references/examples.md) for compound research, external actions, approval language, + zero-spend REST handoff so the original job payer authorizes the review. +- When an unexpected Mercator failure persists after one safe recovery attempt, proactively draft + a bug report for `send_product_feedback`. Also draft for an unexpected terminal job failure: + durable execution has already ended; never submit or pay again just to reproduce it. Return the + failure and any partial results to the user. Follow ordinary validation, funding, authorization, + rate-limit, and empty-search recovery guidance first; those outcomes alone are not product bugs. +- Include the tool name, safe error code, reproduction steps, and expected/actual behavior. Provide + the related Mercator job ID in `job_id` when one exists; omit it if no job was created or its ID + is unknown. Never invent an ID or create a job just to report an issue. The job ID grants result + access and is shared with maintainers for diagnosis. Exclude secrets, credentials, payment + material, personal data, and raw tool inputs or outputs. + Show the draft and ask to send unless the user already authorized reporting this issue. Wallet + authorization is not feedback consent. Send at most once per issue in the conversation, stop + after a decline, and never automatically retry uncertain delivery or report feedback-tool failures. + +Read [examples](references/examples.md) for compound research, external actions, spending limits, MCP submission, status listening, and recovery patterns. diff --git a/plugins/mercator/skills/mercator/agents/openai.yaml b/plugins/mercator/skills/mercator/agents/openai.yaml index f481b3b..24ff097 100644 --- a/plugins/mercator/skills/mercator/agents/openai.yaml +++ b/plugins/mercator/skills/mercator/agents/openai.yaml @@ -8,6 +8,6 @@ dependencies: value: "mercator" description: "Mercator service discovery and durable job execution" transport: "streamable_http" - url: "https://mercator.tempo.xyz/mcp/auth" + url: "https://mercator.sh/mcp/auth" policy: allow_implicit_invocation: true diff --git a/plugins/mercator/skills/mercator/references/examples.md b/plugins/mercator/skills/mercator/references/examples.md index ddc313d..9d00d24 100644 --- a/plugins/mercator/skills/mercator/references/examples.md +++ b/plugins/mercator/skills/mercator/references/examples.md @@ -1,6 +1,6 @@ # Mercator examples -These examples show routing, scope, and approval decisions. Use live tool schemas; never copy +These examples show routing, scope, and spending decisions. Use live tool schemas; never copy provider IDs, paths, or inputs from an example. ## Current data @@ -51,8 +51,9 @@ Before submission, a useful confirmation is: > I found a five-source research plan covering flows, holders, price, news, and regulation. The > Mercator quote is $3.80, within your $5 budget. I’ll run it and return the requested sourced chart. -Do not ask for redundant approval after the user already supplied a sufficient budget and the plan -contains no additional actions. +With hosted OAuth, the connected access key authorizes spending within its signed limits. Do not ask for per-job spend +approval; respect the explicit $5 budget and the requested scope. Legacy challenge clients can also +proceed within that explicit budget; without one, show the quote and obtain approval before paying. ## Research versus action @@ -63,13 +64,13 @@ Search and quote a research plan. Do not book a flight: the user asked to find o **Request:** “Book the best refundable replacement under $1,200 and email me the itinerary.” The requested workflow may include booking and email actions. Before execution, show the selected -plan and Mercator quote. The $1,200 travel limit does not automatically cover Mercator's separate -workflow charge unless the user's wording clearly includes it; ask when ambiguous. +plan and Mercator quote. Keep the fare within the $1,200 travel limit and Mercator's separate workflow +charge within the connected access-key limits and any explicit workflow budget. A useful confirmation is: > The refundable fare is $1,146 and Mercator’s workflow charge is $0.42. The plan will purchase the -> ticket and email the itinerary. Shall I execute it? +> ticket and email the itinerary. I’ll run it using the connected wallet. ## Missing required input @@ -82,9 +83,10 @@ Ask for that address; do not invent it or quietly remove the email step. ## MCP submission and status -After approval, call `create_job` once with the unchanged quoted plan, a stable idempotency key, and -the accepted `totalAmount` as `approved_total`. OAuth-connected hosts charge the bounded wallet -inside Mercator. Other clients complete any payment challenge through MCP metadata. Never install a +After quoting, call `create_job` once with the unchanged quoted plan, a stable idempotency key, and +the quoted `totalAmount` as `approved_total`. OAuth-connected hosts charge the bounded wallet +inside Mercator. Legacy challenge clients require quote approval or a sufficient explicit budget +before completing payment through MCP metadata, including after a price change. Never install a CLI or translate MCP submission into a REST request. A successful submission returns either a terminal job or a pending response: @@ -105,21 +107,32 @@ Persist the job ID and start a status listener with: - Request timeout or lost response: call `create_job` with the identical plan and idempotency key to recover the job, then listen on its returned job ID. +In summary mode (`"result_mode":"summary"`), an empty `job.result` means payloads were omitted. +Use each returned `result_node_ids` value with `get_job_details`: + +```json +{"job_id":"4d9ea616-4223-4b9d-bd19-2d3f74c9fa4c","node_id":"search1"} +``` + +Use the actual returned node ID. Alternatively, call `get_job` with `result_mode: "inline"`. +Both reads use cached outputs and do not charge again. Failed jobs may retain successful outputs. + Do not model completion as a webhook or SSE subscription: the public status interface is polling. ## Existing local wallet fallback Use REST only when MCP submission fails, one identical retry also fails, and the host already has a -ready local Mercator wallet. Submit the same plan to `POST https://mercator.tempo.xyz/v1/jobs` with +ready local Mercator wallet. Submit the same plan to `POST https://mercator.sh/v1/jobs` with the same idempotency key and a maximum spend equal to `approved_total`. Never install, create, or -connect a wallet for fallback. Resume job polling through MCP `get_job` with the returned job ID. +connect a wallet for fallback. A local fallback wallet needs quote approval or a sufficient explicit +budget; the hosted OAuth grant does not authorize a separate local wallet. Resume job polling through MCP `get_job` with the returned job ID. ## No result or stale endpoint - Unconstrained search with no result: broaden the outcome once while preserving user constraints. - Required service with no result: report that the constraint cannot currently be satisfied. - Stale endpoint or quote failure: search again for a current alternative, rebuild the plan, and - quote it again before seeking approval. + quote it again before submitting within the access-key limits and any explicit user budget. ## Do not activate