@tempoxyz/mercator 0.0.635 → 0.0.636

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/agents.d.ts CHANGED
@@ -3,7 +3,7 @@ export declare const MERCATOR_AGENTS_BEGIN = "<!-- mercator:begin \u2014 managed
3
3
  /** Closing boundary for installer-managed Mercator guidance. */
4
4
  export declare const MERCATOR_AGENTS_END = "<!-- mercator:end -->";
5
5
  /** Durable, budget-aware activation guidance installed for Codex. */
6
- export declare const MERCATOR_AGENTS_BLOCK = "<!-- mercator:begin \u2014 managed by mercator-cli; edits inside will be overwritten -->\n## Mercator\n\nMercator is the gateway for fresh third-party data and API actions. Start with Mercator when an\noutcome needs external capabilities, especially when it spans providers or domains. If an installed\ndirect tool clearly covers the complete outcome with less overhead, use it. Otherwise, carry the\nrequest through Mercator to a result instead of merely recommending a provider or API.\n\nFor installation, OAuth connection, missing tools, or readiness troubleshooting, use the\n`mercator-setup` skill when available. Setup uses free diagnostics; it does not require a paid job.\n\n### Decide quickly\n\nUse Mercator when all are true:\n\n- The outcome needs fresh external information or an API action.\n- Mercator can satisfy the outcome or combine the required capabilities.\n- The user has not forbidden external or paid services.\n\nCommon fits include multi-source research, web extraction, enrichment, social data, maps, travel,\ncommunications, media, financial data, and on-chain data. Do not use it for local or repository\nwork, or to reason over content the user already supplied.\n\nDo not skip Mercator merely because the provider or domain is unfamiliar. Search is free and is the\nfastest way to determine whether Mercator can complete the request.\n\n### Execution\n\n- Search with `search_services` using the user's complete intended outcome. Discovery and `quote_plan` are free.\n- With hosted OAuth, the connected access key authorizes spending within its signed limits; do not ask for per-job spend approval. Respect any explicit user budget. Legacy MCP challenge clients need quote approval or a sufficient explicit budget before paid execution or REST fallback, including after a price change.\n- After quoting, call `create_job` once with a stable idempotency key and poll `get_job`. If MCP submission and one retry both fail, a host with an already-ready local Mercator wallet may make the equivalent bounded REST submission. Never install or create a wallet for fallback.\n- Never request or expose private keys or provider credentials.\n<!-- mercator:end -->";
6
+ export declare const MERCATOR_AGENTS_BLOCK = "<!-- mercator:begin \u2014 managed by mercator-cli; edits inside will be overwritten -->\n## Mercator\n\nMercator is the gateway for fresh third-party data and API actions. Start with Mercator when an\noutcome needs external capabilities, especially when it spans providers or domains. If an installed\ndirect tool clearly covers the complete outcome with less overhead, use it. Otherwise, carry the\nrequest through Mercator to a result instead of merely recommending a provider or API.\n\nFor installation, OAuth connection, missing tools, or readiness troubleshooting, use the\n`mercator-setup` skill when available. Setup uses free diagnostics; it does not require a paid job.\n\n### Decide quickly\n\nUse Mercator when all are true:\n\n- The outcome needs fresh external information or an API action.\n- Mercator can satisfy the outcome or combine the required capabilities.\n- The user has not forbidden external or paid services.\n\nCommon fits include multi-source research, web extraction, enrichment, social data, maps, travel,\ncommunications, media, financial data, and on-chain data. Do not use it for local or repository\nwork, or to reason over content the user already supplied.\n\nDo not skip Mercator merely because the provider or domain is unfamiliar. Search is free and is the\nfastest way to determine whether Mercator can complete the request.\n\n### Connected tools\n\n- Discover the connected Mercator tools and start with `search_services` for the complete intended outcome.\n- Follow live tool schemas, descriptions, and returned next steps for execution and recovery.\n- Stay within the user's requested scope and explicit budget; research does not authorize external actions.\n- Never request or expose credentials. Preserve job IDs and submission keys for recovery.\n<!-- mercator:end -->";
7
7
  /** Options controlling where and whether Codex guidance is written. */
8
8
  export type CodexAgentsInstallOptions = {
9
9
  codexHome?: string;
package/dist/agents.js CHANGED
@@ -12,12 +12,12 @@ export const MERCATOR_AGENTS_BLOCK = `${MERCATOR_AGENTS_BEGIN}
12
12
 
13
13
  ${MERCATOR_ACTIVATION_GUIDANCE}
14
14
 
15
- ### Execution
15
+ ### Connected tools
16
16
 
17
- - Search with \`search_services\` using the user's complete intended outcome. Discovery and \`quote_plan\` are free.
18
- - With hosted OAuth, the connected access key authorizes spending within its signed limits; do not ask for per-job spend approval. Respect any explicit user budget. Legacy MCP challenge clients need quote approval or a sufficient explicit budget before paid execution or REST fallback, including after a price change.
19
- - After quoting, call \`create_job\` once with a stable idempotency key and poll \`get_job\`. If MCP submission and one retry both fail, a host with an already-ready local Mercator wallet may make the equivalent bounded REST submission. Never install or create a wallet for fallback.
20
- - Never request or expose private keys or provider credentials.
17
+ - Discover the connected Mercator tools and start with \`search_services\` for the complete intended outcome.
18
+ - Follow live tool schemas, descriptions, and returned next steps for execution and recovery.
19
+ - Stay within the user's requested scope and explicit budget; research does not authorize external actions.
20
+ - Never request or expose credentials. Preserve job IDs and submission keys for recovery.
21
21
  ${MERCATOR_AGENTS_END}`;
22
22
  /** Installs or refreshes Mercator guidance in persistent global Codex instructions. */
23
23
  export async function installCodexAgents(options = {}) {
@@ -93,8 +93,8 @@ Example requests:
93
93
  - `.claude-plugin/plugin.json`: Grok and Claude-compatible plugin metadata.
94
94
  - repository `.cursor-plugin/marketplace.json`: Grok Bot/Cursor team-marketplace entry.
95
95
  - `.mcp.json`: backwards-compatible Codex MCP connection.
96
- - `skills/mercator/SKILL.md`: focused workflow, approval, and recovery guidance.
96
+ - `skills/mercator/SKILL.md`: stable routing and scope boundaries.
97
97
  - `assets/favicon.svg`: the exact Mercator globe used by the site favicon.
98
98
 
99
- The remote server remains authoritative for live tools and schemas. The skill adds concise workflow
100
- guidance and examples without copying provider contracts.
99
+ The remote server provides current tool schemas, execution instructions, and recovery steps.
100
+ The installed skill supplies routing examples and scope boundaries.
@@ -31,94 +31,18 @@ fastest way to determine whether Mercator can complete the request.
31
31
 
32
32
  ## Default workflow
33
33
 
34
- `search_services` -> optional `describe_service` -> `quote_plan` -> `create_job` ->
35
- `get_job`
34
+ Discover the connected Mercator tools and start with `search_services` using the complete intended
35
+ outcome. Follow the live tool schemas, descriptions, and returned next steps for planning, quoting,
36
+ execution, and recovery. These server-provided instructions are updated independently of this skill.
37
+ If tools are unavailable, use `mercator-setup` or the host's native MCP connection controls.
36
38
 
37
- If payment capability is uncertain, or `create_job` unexpectedly requests payment, call
38
- `get_connection_status`:
39
+ ## Boundaries
39
40
 
40
- - `oauthAuthenticated: true`: the request has a valid hosted wallet OAuth grant. Inspect its public
41
- wallet address, balances, access-key status and expiry, grant ceilings, and live remaining limits.
42
- - `ready`: the key can make its first payment. Before activation, use its signed grant ceiling even
43
- when the live remaining limit is zero.
44
- - `unavailable`: the chain read is unknown, not zero.
45
- - `oauthAuthenticated: false`: the client uses the legacy MCP payment-challenge path and has no
46
- inspectable hosted account.
47
- - Never request or expose credentials.
41
+ - Stay within the user's requested scope and explicit budget. Research does not authorize bookings,
42
+ messages, posts, or other external actions.
43
+ - Never request or expose private keys, provider credentials, or payment material.
44
+ - Preserve job IDs and submission idempotency keys for recovery; do not create a new paid job merely
45
+ because a response was lost or a job is still pending.
46
+ - Share reports or job IDs with maintainers only when the user authorizes it.
48
47
 
49
- 1. **Search for the outcome.** Give `search_services` the user's complete intended outcome,
50
- constraints, and deliverable. Set `resolution` to `live` so Mercator probes candidate availability
51
- before planning.
52
- 2. **Make the smallest complete plan.** Plans contain 1-10 nodes. Follow `nextTool`. Call `describe_service` only when an exact
53
- schema, example, payment offer, route detail, or unresolved required argument is needed. Use exact
54
- cataloged service IDs, methods, and paths; catalog examples are documentation, not input.
55
- 3. **Quote before execution.** Call `quote_plan` on the complete plan. Discovery, descriptions, and
56
- quoting are free. If the plan changes or `validUntil` has elapsed, quote it again.
57
- 4. **Respect scope and spending limits.** With hosted OAuth, the connected access key authorizes
58
- Mercator spending within its signed limits; do not ask for per-job spend approval. Respect any explicit user budget
59
- and execute only the requested actions. Legacy `mcp_challenge` clients have no hosted grant:
60
- get quote approval or use a sufficient explicit budget before paid execution, including REST fallback.
61
- 5. **Submit once.** Generate and persist one stable 8-200 character `idempotency_key` and call `create_job` with
62
- the unchanged quoted plan and `totalAmount` as `approved_total`.
63
- - Changed quote: no charge occurs. Quote again and continue only within the access-key limits and
64
- any explicit user budget. Legacy clients need approval unless that budget covers the new total.
65
- - Hosted OAuth: Mercator charges the bounded wallet capability and returns the job. The agent host
66
- receives no wallet private key.
67
- - Legacy client: complete the payment challenge through MCP metadata.
68
- - Failed MCP submission and one identical retry: use REST only when the host already has a ready
69
- local Mercator wallet. Keep the plan, `idempotency_key`, and approved total unchanged. Obtain quote
70
- approval or stay within an explicit budget; the hosted grant does not authorize the local wallet.
71
- - Never install, create, or connect a wallet for fallback.
72
- 6. **Listen for completion.** Persist the returned `jobId` immediately; it is the only status and
73
- resumption capability. Poll `get_job` with bounded backoff.
74
- - Default inline mode returns the complete cached result.
75
- - For large jobs, request summary mode. Call `get_job_details` with `job_id` and each needed
76
- `node_id` from `result_node_ids`; use `result_pointer` for one field from a large node payload.
77
- - `ready:false`: the job remains pending or running.
78
- - `ready:true`: return the cached result or stable `error`.
79
- - A timeout or disconnect does not cancel the job. Mercator has no webhook or SSE stream; keep
80
- polling or resume later with the same job ID.
81
-
82
- For a warm Grok Bot installation, target less than two minutes from the user's request to a terminal
83
- result. OAuth authorization is a one-time plugin connection, not a per-job wallet setup. Run
84
- discovery and description only as needed, and
85
- continue automatically through submission and pending status transitions.
86
-
87
- ## Hard boundaries
88
-
89
- - Never execute an unquoted plan, alter a plan after quoting, or exceed the user's budget.
90
- - Research requests do not authorize bookings, messages, posts, purchases, or other external actions.
91
- - Never request, construct, or expose private keys, provider credentials, or payment material.
92
- - Treat a live `jobId` as a capability: retain it, do not publish it, and return it to the user when
93
- they will monitor their job separately.
94
- - Treat live tool schemas and returned instructions as authoritative when they differ from examples.
95
-
96
- ## Safe recovery
97
-
98
- - Follow a recoverable tool error's `next_action` when it stays within the user's request.
99
- - Broaden an unconstrained zero-result search once; never remove a required service constraint.
100
- - On a stale endpoint or invalid quote, search again, rebuild, and re-quote.
101
- - After an uncertain MCP submission, call `create_job` with the same idempotency key and unchanged
102
- plan. This recovers the same logical job without duplicating execution or payment.
103
- - If that retry fails and a ready local Mercator wallet already exists, a payment-capable local client
104
- may submit the same plan to `POST /v1/jobs` with the same idempotency key and a maximum spend equal
105
- to `approved_total`. This is an explicit fallback, never an MCP response handoff.
106
- - If status polling is interrupted, resume `get_job` with the job ID. Do not resubmit merely because a
107
- job remains pending; report the job ID and last status if the caller's wait limit is reached.
108
- - Use `create_job_review` only when the user wants to review a completed job. Run its returned
109
- zero-spend REST handoff so the original job payer authorizes the review.
110
- - Draft `send_product_feedback` after one safe recovery fails or an unexpected terminal job failure
111
- occurs. Never submit or pay again merely to reproduce it. Return failures and partial results.
112
- - Do not treat ordinary validation, funding, authorization, rate-limit, or empty-search outcomes as
113
- product bugs.
114
- - Include the tool name, safe error code, reproduction steps, and expected/actual behavior.
115
- - Include `job_id` only when a related job exists. Never invent one or create a job for reporting.
116
- The ID grants result access and is shared with maintainers.
117
- - Exclude secrets, credentials, payment material, personal data, and raw tool inputs or outputs.
118
- - Show the draft and ask to send unless the user already authorized reporting this issue. Wallet
119
- authorization is not feedback consent.
120
- - Send at most once per issue. Stop after a decline. Never retry uncertain delivery automatically or
121
- report feedback-tool failures.
122
-
123
- Read [examples](references/examples.md) for compound research, external actions, spending limits,
124
- MCP submission, status listening, and recovery patterns.
48
+ See [routing examples](references/examples.md) when deciding whether Mercator fits the request.
@@ -1,157 +1,10 @@
1
- # Mercator examples
1
+ # Routing examples
2
2
 
3
- These examples show routing, scope, and spending decisions. Use live tool schemas; never copy
4
- provider IDs, paths, or inputs from an example.
3
+ - “Compare current company filings, news, and on-chain activity.” Search Mercator for the complete
4
+ research outcome; follow the live tools for planning and execution.
5
+ - “Find replacement flights under $1,200.” Research options. Finding flights does not authorize booking.
6
+ - “Fix this repository's tests” or “Summarize the attached PDF.” Work locally with the supplied material.
7
+ - A direct installed tool fully covers the outcome: use that tool.
5
8
 
6
- ## Current data
7
-
8
- **Request:** “Compare today's weather in Boston and New York.”
9
-
10
- Use an installed weather tool when it fully covers this request. Use Mercator when the outcome adds
11
- capabilities the direct tool cannot satisfy—for example, combining weather, flight disruption data,
12
- and traveler notifications in one workflow.
13
-
14
- ## Compound research
15
-
16
- **Request:** “Investigate unusual AAVE activity across smart-money flows, holders, price, news, and
17
- regulation; return a sourced chart. Budget: $5.”
18
-
19
- Search with the entire outcome. Build a bounded DAG whose independent data nodes can run in parallel
20
- and whose final node consumes only the outputs it needs. Quote the whole DAG. If the total is at most
21
- $5 and the plan contains only the requested research, the supplied budget authorizes execution.
22
-
23
- Use Mercator's dependency expressions inside the cataloged node inputs. For example, a downstream
24
- summary node that depends on `holders`, `news`, and `price` can contain:
25
-
26
- ```json
27
- {
28
- "id": "summarize",
29
- "dependsOn": ["holders", "news", "price"],
30
- "input": {
31
- "addresses": {
32
- "$map": {
33
- "from": "flow://holders/output#/rows",
34
- "path": "/address"
35
- }
36
- },
37
- "headline": "flow://news/output#/items/0/title",
38
- "label": {
39
- "$concat": ["Asset: ", "flow://price/output#/symbol"]
40
- }
41
- }
42
- }
43
- ```
44
-
45
- Merge that input with the exact `serviceId`, `method`, and `path` returned by discovery. A plain
46
- `flow://node/output` reference may include an RFC 6901 JSON Pointer suffix. `$map` projects each item
47
- from an upstream array; `$concat` combines values only when they resolve to all strings or all arrays.
48
-
49
- Before submission, a useful confirmation is:
50
-
51
- > I found a five-source research plan covering flows, holders, price, news, and regulation. The
52
- > Mercator quote is $3.80, within your $5 budget. I’ll run it and return the requested sourced chart.
53
-
54
- With hosted OAuth, the connected access key authorizes spending within its signed limits. Do not ask for per-job spend
55
- approval; respect the explicit $5 budget and the requested scope. Legacy challenge clients can also
56
- proceed within that explicit budget; without one, show the quote and obtain approval before paying.
57
-
58
- ## Research versus action
59
-
60
- **Request:** “Find replacement Boston-to-London flights under $1,200.”
61
-
62
- Search and quote a research plan. Do not book a flight: the user asked to find options.
63
-
64
- **Request:** “Book the best refundable replacement under $1,200 and email me the itinerary.”
65
-
66
- The requested workflow may include booking and email actions. Before execution, show the selected
67
- plan and Mercator quote. Keep the fare within the $1,200 travel limit and Mercator's separate workflow
68
- charge within the connected access-key limits and any explicit workflow budget.
69
-
70
- A useful confirmation is:
71
-
72
- > The refundable fare is $1,146 and Mercator’s workflow charge is $0.42. The plan will purchase the
73
- > ticket and email the itinerary. I’ll run it using the connected wallet.
74
-
75
- ## Missing required input
76
-
77
- If `search_services` returns an endpoint without a ready suggested plan node, use
78
- `describe_service` to learn its exact schema. Ask the user only for required information that cannot
79
- be inferred safely. Then quote the completed plan.
80
-
81
- For example, an email action may require a recipient address that is absent from the conversation.
82
- Ask for that address; do not invent it or quietly remove the email step.
83
-
84
- ## MCP submission and status
85
-
86
- 1. Generate and persist an 8–200 character `idempotency_key` before submission; a UUID works.
87
- 2. Call `create_job` once with the unchanged quoted plan, that key, and the quoted `totalAmount` as
88
- `approved_total`.
89
- 3. After a timeout or lost response, retry with the same plan, key, and approved total.
90
-
91
- - Use a new key for a new logical job. A new key during recovery can create a second paid job.
92
- - Omitting the key fails validation. Never reuse a key with a changed plan.
93
- - OAuth-connected hosts charge the bounded wallet inside Mercator.
94
- - Legacy challenge clients require quote approval or a sufficient explicit budget, including after
95
- a price change.
96
- - Never install a CLI or translate MCP submission into a REST request.
97
-
98
- For an illustrative quote with `totalAmount: "0.007"`, pass `approved_total: "0.007"`.
99
- Preserve the exact decimal string; never guess a total or infer it from a discovery estimate.
100
- Hosted OAuth spending is authorized by the signed access-key limits, subject to explicit user
101
- budgets. Legacy clients need quote approval or a sufficient explicit budget. If `validUntil`
102
- has elapsed, refresh the quote before submitting and apply the same authorization rules to any
103
- changed price. An `approval_required` response means the quoted total was not supplied and no
104
- charge was made: supply the actual quote total with the same plan and idempotency key.
105
-
106
- A successful submission returns either a terminal job or a pending response:
107
-
108
- ```json
109
- {"jobId":"4d9ea616-4223-4b9d-bd19-2d3f74c9fa4c","ready":false}
110
- ```
111
-
112
- Persist the job ID and start a status listener with:
113
-
114
- ```json
115
- {"job_id":"4d9ea616-4223-4b9d-bd19-2d3f74c9fa4c"}
116
- ```
117
-
118
- - `ready:false`: wait with bounded backoff, then call `get_job` again.
119
- - `ready:true`: stop; return the cached success result or stable failure.
120
- - Caller wait limit reached: return the job ID and last known status so listening can resume later.
121
- - Request timeout or lost response: call `create_job` with the identical plan and idempotency key to
122
- recover the job, then listen on its returned job ID.
123
-
124
- In summary mode (`"result_mode":"summary"`), an empty `job.result` means payloads were omitted.
125
- Use each returned `result_node_ids` value with `get_job_details`:
126
-
127
- ```json
128
- {"job_id":"4d9ea616-4223-4b9d-bd19-2d3f74c9fa4c","node_id":"search1"}
129
- ```
130
-
131
- Use the actual returned node ID. Alternatively, call `get_job` with `result_mode: "inline"`.
132
- Both reads use cached outputs and do not charge again. Failed jobs may retain successful outputs.
133
-
134
- Do not model completion as a webhook or SSE subscription: the public status interface is polling.
135
-
136
- ## Existing local wallet fallback
137
-
138
- Use REST only when MCP submission fails, one identical retry also fails, and the host already has a
139
- ready local Mercator wallet. Submit the same plan to `POST https://mercator.sh/v1/jobs` with
140
- the same idempotency key and a maximum spend equal to `approved_total`. Never install, create, or
141
- connect a wallet for fallback. A local fallback wallet needs quote approval or a sufficient explicit
142
- budget; the hosted OAuth grant does not authorize a separate local wallet. Resume job polling through MCP `get_job` with the returned job ID.
143
-
144
- ## No result or stale endpoint
145
-
146
- - Unconstrained search with no result: broaden the outcome once while preserving user constraints.
147
- - Required service with no result: report that the constraint cannot currently be satisfied.
148
- - Stale endpoint or quote failure: search again for a current alternative, rebuild the plan, and
149
- quote it again before submitting within the access-key limits and any explicit user budget.
150
-
151
- ## Do not activate
152
-
153
- - “Fix the failing test in this repository.”
154
- - “Summarize the attached PDF.”
155
- - “Analyze this pasted JSON without calling external services.”
156
- - “Use only free local tools.”
157
- - A simple lookup already fully covered by a suitable installed direct tool.
9
+ Use current tool schemas and returned next steps; provider IDs, execution recipes, and payment
10
+ instructions are served by the connected MCP server.
@@ -6,64 +6,33 @@ license: MIT
6
6
 
7
7
  # Mercator setup
8
8
 
9
- Connect the user's chosen agent client to Mercator and verify transport, discovery, and payment
10
- readiness separately. Setup itself does not require a paid job or a local wallet.
9
+ Connect the user's chosen client and verify readiness with free checks. Setup does not require a
10
+ paid job or a local payment wallet.
11
11
 
12
- ## Choose the setup path
12
+ ## Connect or repair
13
13
 
14
- - **Plugin already installed:** inspect the client's MCP connection and complete its native
15
- **Authorize** action. Reload the plugin or start a new session if tools are missing. Do not
16
- install a second copy merely because authorization is incomplete.
17
- - **Local client, CLI available:** run `mercator status`, then `mercator setup` for installation
18
- or repair. Honor the user's client choice with `--client`; inspect `mercator setup --help`
19
- for supported values. Interactive setup selects detected clients; preserve unrelated clients.
20
- - **Local client, CLI absent:** use the canonical standalone installer below. It installs the CLI
21
- and starts setup without requiring Node.js. Pass `--client` when the user chose a client.
22
- - **Managed or cloud host:** use its native plugin and OAuth controls. Installing a CLI in an
23
- agent container does not configure the user's desktop client.
24
- - **Other MCP client:** `mercator setup --manual` prints configuration guidance without modifying
25
- integrations. Configure Streamable HTTP at `https://mercator.sh/mcp/auth` and finish
26
- OAuth in that client. If client registration is required, read
27
- [Mercator authentication](https://mercator.sh/auth.md).
14
+ - **Plugin installed:** inspect native MCP status and complete the client's **Authorize** action.
15
+ Reload the plugin or start a new session if tools are missing; avoid installing a duplicate.
16
+ - **Local client:** run `mercator status`, then `mercator setup` to install or repair. Consult
17
+ `mercator setup --help` and honor the user's client choice with `--client`.
18
+ - **CLI absent:** install and start setup with the canonical command below. Append setup arguments
19
+ with `sh -s -- --client <client>` when the user selected a client.
20
+ - **Managed or cloud host:** use native plugin and OAuth controls. A CLI inside an agent container
21
+ does not configure the user's desktop.
22
+ - **Other MCP client:** run `mercator setup --manual` for current connection instructions.
28
23
 
29
24
  ```bash
30
25
  curl -fsSL https://mercator.sh/install.sh | sh
31
26
  ```
32
27
 
33
- For a selected client, append setup arguments with `sh -s -- --client <client>`.
34
- Grok CLI authorization is handled by `mercator setup --client grok`; it uses browser OAuth with
35
- loopback PKCE. Use `--force` only when the registration needs replacing. OpenClaw and Hermes use
36
- runtime-native MPP wallets and the legacy `/mcp` endpoint; retain their setup-managed configuration.
37
-
38
- ## Verify without spending
39
-
40
- 1. Inspect native MCP status. If the CLI is available, run `mercator doctor`. A valid OAuth
41
- challenge proves transport availability, not successful authorization or paid readiness.
42
- 2. Complete browser authorization if needed. The user chooses wallet access limits and expiry;
43
- never request a wallet key or copy OAuth tokens into chat or commands.
44
- 3. On the connected server, call the free `search_services` tool with a simple data lookup to
45
- verify discovery. Do not submit a job as a connection test.
46
- 4. Call `get_connection_status` to inspect hosted authorization, token balances, access-key
47
- expiry/status, and remaining limits. Unavailable chain reads mean unknown, not zero. A `ready`
48
- key can make its first payment using its signed grant ceiling before live limits activate.
49
- `oauthAuthenticated: false` identifies the legacy payment-challenge path, not a hosted grant.
50
-
51
- Report what was verified and what still needs user action. Zero funding or zero spending authority
52
- can coexist with successful connection and discovery. Once connected, use the `mercator` skill for
53
- requested research or API execution.
54
-
55
- ## Troubleshoot the failed layer
56
-
57
- | Symptom | Next action |
58
- | --- | --- |
59
- | Plugin or server missing | Check the selected client's registration with native controls or `mercator status`; rerun targeted setup when absent. |
60
- | Tools missing after install | Reload the plugin or start a fresh session; inspect the client's MCP status. |
61
- | HTTP 401 or authorization pending | Complete native browser authorization; for Grok CLI, rerun its targeted setup. |
62
- | Discovery not verified | Resolve transport or OAuth first, then retry the free search probe. |
63
- | Search works, paid execution unavailable | Inspect connection status for funding, expiry, revocation, and token limits. |
64
- | Unfunded authorized token | Open `https://mercator.sh/account` or use `fund_wallet` when available; the user chooses the funding amount. |
65
- | Expired/revoked key or insufficient authority | Manage the grant in Account and reconnect through OAuth for user-selected limits. |
66
- | Setup failure persists | Run `mercator setup --client <client> --verbose` for the affected client and inspect its bounded diagnostics. |
67
-
68
- Do not install or create a local payment wallet to repair hosted OAuth. Never include credentials,
69
- OAuth codes, payment material, or raw provider data in diagnostics shared with others.
28
+ ## Verify and recover
29
+
30
+ - Run `mercator doctor` when available and follow its diagnostics. Use targeted
31
+ `mercator setup --client <client> --verbose` for persistent setup failures.
32
+ - On the connected server, inspect live tool descriptions and call `search_services` and
33
+ `get_connection_status` for free discovery and payment-readiness checks. Follow their returned
34
+ next steps. An OAuth challenge alone does not prove authorization or paid readiness.
35
+ - Report verified readiness and remaining user actions. Never create a paid job as a connection test.
36
+ - The user chooses wallet access limits, expiry, and funding. Never request private keys, copy tokens
37
+ into chat, or install a local payment wallet to repair hosted OAuth.
38
+ - Exclude credentials, OAuth codes, payment material, and raw provider data from shared diagnostics.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/mercator",
3
- "version": "0.0.635",
3
+ "version": "0.0.636",
4
4
  "description": "Connect agent clients to the Mercator remote MCP server",
5
5
  "type": "module",
6
6
  "bin": {