@relvo/mcp 0.1.2 → 0.1.3

package/README.md

@@ -1,8 +1,7 @@
 # Relvo MCP
 
-The public package and executable are `@relvo/mcp` and `relvo-mcp`. Deployed
-`thk_` keys and `TOOLHUB_*` environment settings remain accepted. Prefer
-`RELVO_*` names; conflicting nonempty aliases fail before any request or upload.
+The public package and executable are `@relvo/mcp` and `relvo-mcp`. Keys use
+`rlv_` and settings use `RELVO_*` names.
 
 Standalone stdio MCP server for Relvo.
 Requires Node.js 22 or later. The CLI is a separate package: @relvo/cli.
@@ -10,6 +9,66 @@ It supports the MCP 2026-07-28 stateless core (`server/discover`, per-request
 metadata, no initialize handshake or protocol session) and keeps the 2025
 initialize flow as a compatibility fallback for older hosts.
 
+By default the server exposes only `platform_tools`, `platform_run` and
+`platform`; operation schemas load on demand. The first `platform_tools` match
+includes its input schema. `platform_run` accepts `{tool, arguments,
+idempotencyKey}`. Do not ask for or invent a budget when none was specified.
+`maximumChargeMicros` is optional: omit it or use null for no user ceiling;
+0 permits only zero Relvo charges. The run quotes the exact input internally,
+rejects quotes above an explicit ceiling, saves the actual quote amount/version
+when no ceiling was supplied, submits and waits for a bounded result.
+Project/account limits still apply. Externally billed usage requires existing
+authorization and `externalBillingAccepted:true`; the Relvo ceiling does not
+limit external charges.
+Set `RELVO_MCP_MODE=full` to list every original operation as its own tool
+instead. The hosted remote MCP URL serves the same compact surface, without
+local result files.
+
+Full results stay available through `platform` with `operation: "result"` and `{id, path,
+fields}` or `pick` (labels mapped to exact paths). A run can use `selection`
+or `pick` to request that same view before data enters the model context. Only
+select paths known from the actual output; missing fields are reported.
+Large collections automatically return a fitting page. Very long rows use
+`rowWindows`: complete small `fields`, explicitly partial text `fragments`, and
+references to other large values. Fragments carry exact source paths and text
+cursors; read missing details from the same execution. Never use a partial URL
+or identifier as a complete value. Collection and text cursors retain access to
+all original records without purchasing them again. To work through many rows,
+`file: true` (on `platform_run` or a result read) writes the whole selected path
+(with `fields` applied; an envelope holding one array writes that array) to an
+owner-only file, as JSON Lines for an array, and returns its path instead of the
+rows, so the host's own file tools (Read, Grep, jq) can search or read it. Files
+go to `.relvo/results` in the server's working directory, which is the host's
+project when the host starts the server, so its tools reach them without extra
+approval; git ignores that directory. `RELVO_RESULT_DIRECTORY` selects another
+directory.
+Use `operation: "schema"` to inspect one original operation, then `operation:
+"call"` with `{name, input}` to invoke it. Original validation and permissions
+still apply. A quote-only approval flow must use `platform_quote` and wait for
+approval before any run. A spending cap does not authorize external writes.
+When an unpinned Auto quote exceeds the cap, a run can return unpurchased native
+candidate tools with explicitly pinned, free example quotes. Inspect their
+schemas and check that they fit the task; actual inputs are always quoted again
+before execution. Example quotes never authorize spending or a larger budget.
+
+The exact purchase is saved in an owner-only local journal scoped to the API
+origin and credential. `RELVO_RUN_DIRECTORY` may select a private directory;
+saved arguments can contain private task data. Keep it until uncertain work is
+reconciled. After a lost reply, resend the same run body/key or use `operation:
+"resume"` with the received `runId`. Never replace unknown work with a new key.
+Pending or `needs_review` is not success; its final charge remains unknown.
+Current run IDs can recover an accepted purchase from another server instance
+without the local journal. Repeating the original body/key also works after a
+quote changes or becomes unavailable; a different request is refused. Recovery
+requires the same API origin and credential and the matching API/worker release.
+Older purchases without recovery metadata may need their original journal or
+execution history for reconciliation. Legacy 64-character run IDs still use
+their local journal.
+
+The rest of this guide describes the original operations. With
+`RELVO_MCP_MODE=full` each is its own tool; by default, reach them through
+`platform` with `operation: "call"`.
+
 Six session helpers are available: `platform_search_tools`,
 `platform_get_tool_schemas`, `platform_manage_connections`,
 `platform_multi_execute`, `platform_remote_workbench` and `platform_remote_bash`.
@@ -20,8 +79,10 @@ reservation cap. `isError:true` can contain accepted siblings: inspect every
 structured admission and wait/read its execution ID. Recover uncertain admission
 with the exact original request/session/keys, without replacement purchases.
 
-Tool replies share a 24,000-byte envelope budget, including compatible JSON text
-and structured data. Large `platform_tool` definitions and `platform_skill`
+The larger of a reply's JSON text and structured data is kept below 24,000 UTF-8
+bytes, including its data framing. Both representations are returned for
+compatibility; the combined protocol envelope can be larger.
+Large `platform_tool` definitions and `platform_skill`
 guides expose exact `path`/`offset` pages: follow entry paths lacking `value`
 and `nextOffset` only as needed. Compact batches preserve every index/admission/ID;
 match indices to saved original calls when `requestFieldsOmitted` is present.
@@ -45,6 +106,30 @@ OR within lists, AND across include lists; any exclusion wins. Empty/null is
 neutral. Excluding a provider removes every tool listing it, including fallbacks;
 discovery filters do not pin a later execution.
 
+The compact `platform_tools` accepts these options directly, without switching
+to full mode. Its `queries` accepts up to four strings or discovery-option
+objects in one call; shared options are defaults and each object may override
+them, including its limit. For example:
+
+~~~json
+{
+  "mode": "keyword",
+  "limit": 2,
+  "queries": [
+    "Instagram profiles",
+    {"query": "web search", "provider": "brave", "limit": 3},
+    {"category": "enrichment", "exclude": {"tools": ["unwanted_tool"]}}
+  ]
+}
+~~~
+
+Batch results are summaries with per-query counts and truncation; they do not
+represent every operation of an app. Inspect selected definitions as needed.
+Load the full discovery contract with `platform` / `operation: "schema"` /
+`input: {"name": "platform_tools"}`. Unknown options fail validation before a
+request; discovery never executes the tools it finds. CLI batches use the same
+per-query options, for example `relvo meta search '{"queries":[{"query":"Instagram profiles"},{"query":"web search","provider":"brave"}]}'`.
+
 platform_manage_connections returns a trusted console URL and target project for explicit user
 OAuth consent, followed by a status recheck. It does not initiate OAuth itself.
 Remote Python/Bash require an explicitly enabled persistent sandbox deployment

package/bin/relvo-mcp.mjs

@@ -7,7 +7,7 @@ if (args.length === 1 && args[0] === "--version") {
   const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   console.log(manifest.version);
 } else if (args.length === 1 && ["--help", "-h", "help"].includes(args[0])) {
-  console.log("Usage: relvo-mcp\nStart the Relvo MCP server over stdio.\nEnvironment: RELVO_API_URL, RELVO_API_KEY\nLocal uploads are disabled unless RELVO_MCP_ALLOWED_UPLOAD_ROOTS lists allowed absolute directories.\nExample: npx -y @relvo/mcp\nStandard output is reserved for MCP protocol messages.");
+  console.log("Usage: relvo-mcp\nStart the Relvo MCP server over stdio.\nEnvironment: RELVO_API_URL, RELVO_API_KEY\nOptional: RELVO_MCP_MODE=full loads every operation as its own tool; the compact agent surface is the default.\nOptional: RELVO_MCP_TOOLS=web_search,serp_lookup also lists those catalog tools as tools of their own, to call without discovery (agent surface, at most 20).\nLocal uploads are disabled unless RELVO_MCP_ALLOWED_UPLOAD_ROOTS lists allowed absolute directories.\nExample: npx -y @relvo/mcp\nStandard output is reserved for MCP protocol messages.");
 } else if (args.length && !(args.length === 2 && args[0] === "--profile")) {
   console.error("Usage: relvo-mcp [--help | --version]");
   process.exitCode = 2;