@pdpp/mcp-server 0.0.0 → 0.1.0-beta.8

package/README.md

@@ -0,0 +1,213 @@
+# @pdpp/mcp-server
+
+Local stdio and hosted Streamable HTTP [Model Context Protocol](https://modelcontextprotocol.io/)
+adapter for grant-scoped access to a [PDPP](https://pdpp.vivid.fish) resource server.
+
+The adapter is a thin client of the PDPP resource server (RS). It does not run connectors,
+issue grants, or replicate any RS authorization logic. Every data-bearing tool call is a
+forwarded request to an existing `/v1/*` endpoint, authenticated with the scoped client
+access token already cached by `pdpp connect`. The MCP setup is a profile-free normal
+read surface; event-subscription management is not part of the recommended MCP tool list.
+
+## What this is not
+
+- **Not a grant-issuance surface.** If the cache is empty or the token is invalid, the
+  adapter exits / surfaces an error directing the operator at `pdpp connect`.
+- **Not an owner-mode bypass.** `PDPP_OWNER_TOKEN` and other owner credentials are
+  refused by default.
+- **Not a proxy.** Per-client consent and confused-deputy mitigations would be required
+  before this package accepted unvalidated MCP-client tokens. Hosted callers must
+  validate the bearer before passing it to this package.
+
+## Publication status
+
+Published to npm as [`@pdpp/mcp-server@beta`](https://www.npmjs.com/package/@pdpp/mcp-server).
+Follow the [package release policy](../../docs/package-release-policy.md) — use the `@beta`
+dist-tag until a stable release is cut. Matches the posture of `@pdpp/cli` and
+`@pdpp/local-collector`.
+
+## Install (local agent harness)
+
+```jsonc
+// claude_desktop_config.json (or equivalent)
+{
+  "mcpServers": {
+    "pdpp": {
+      "command": "npx",
+      "args": ["-y", "@pdpp/mcp-server@beta", "--provider-url", "https://pdpp.example.com"]
+    }
+  }
+}
+```
+
+Run `pdpp connect https://pdpp.example.com` first so a scoped client token is cached at
+`.pdpp/clients/<host>.json`.
+
+## CLI
+
+```
+pdpp-mcp-server --provider-url <url> [--cache-root <dir>] [--server-name <name>]
+```
+
+Flags can also come from environment variables: `PDPP_PROVIDER_URL`,
+`PDPP_CACHE_ROOT`, `PDPP_MCP_SERVER_NAME`.
+
+The adapter writes only MCP protocol messages to stdout. Diagnostics go to stderr.
+
+## Tools
+
+### Read tools (read-only, idempotent)
+
+| Tool | RS endpoint |
+| --- | --- |
+| `schema` | `GET /v1/schema` |
+| `query_records` | `GET /v1/streams/{stream}/records` |
+| `aggregate` | `GET /v1/streams/{stream}/aggregate` |
+| `search` | `GET /v1/search` |
+| `fetch` | `GET /v1/streams/{stream}/records/{record_id}` |
+
+Plus one resource template: `pdpp://stream/{name}` → `GET /v1/streams/{name}`.
+
+`search` preserves the RS envelope in `structuredContent.data` and also returns
+ChatGPT-compatible `structuredContent.results[]` entries with `id`, `title`, `url`,
+and available source handles such as `connection_id`. Its `content[]` text also
+previews a bounded set of top hits so clients that cannot inspect structured
+tool output can still fetch a result.
+`fetch` accepts result ids in `stream:record_id` form and follows the
+MCP/OpenAI search-fetch document contract: `structuredContent` is exactly
+`id`, `title`, `text`, `url`, and `metadata`, and `content[]` contains the same
+object as JSON text for hosts that hide structured output. It does not return a
+canonical PDPP record envelope under `structuredContent.data`; use
+`query_records` for canonical structured record reads. `fetch(fields)` projects
+the source record before rendering the document so unrequested source-native
+payload fields do not leak into `text` or `metadata`. If that projection omits
+every text-like field (`text`, `content`, `body`, `summary`), the document
+`text` contains compact JSON for the projected record rather than the full
+document body; source handles such as stream, `connection_id`, and
+`connector_key` remain in `metadata`.
+
+The `schema` tool includes concise parseable text with stream
+names, `connection_id`, `connector_key`, display labels, and schema field-capability
+essentials so MCP clients whose models read only `content[]` can still choose streams,
+fields, and connection scopes.
+
+`schema` defaults to a **compact** schema document under `structuredContent.data`
+(`detail: "compact"`). It does not wrap the REST `/v1/schema` body again, so
+callers read `structuredContent.data.connectors`, not `structuredContent.data.data.connectors`.
+A real owner's grant-scoped `GET /v1/schema` body can exceed 2 MB once every connector
+advertises full per-field JSON Schema, which is too large as the default agent-facing
+payload. The compact projection collapses each field to a terse capability flag string
+(declared type, grant, and usable filter/search/aggregation flags — e.g.
+`type=string,granted=true,exact,range=gte|lt,agg=group_by_time`) and drops the raw
+per-field JSON Schema, while preserving connection identities (`connection_id`,
+`display_name`) and canonical `connector_key` metadata. This keeps
+the discovery path `schema -> schema(stream) -> schema(stream, connection_id) -> query_records`
+cheap: the package-level text summary lists streams without per-field flags and
+points the agent at scoped schema calls for them. Stream names are not globally
+unique; `schema(stream)` returns every granted connector/connection with that
+stream name. Add `connection_id` when you need one configured source, especially
+before requesting `detail: "full"`. Pass `detail: "full"` only together with
+`stream`; if that stream name spans multiple sources, retry with `connection_id`
+to get deduped exhaustive schema for one configured source. Full detail
+preserves raw per-field JSON Schema and structured capability sub-objects, but
+does not repeat the same selected stream list in both top-level and
+connector-nested locations.
+
+`query_records` also preserves the full RS envelope in `structuredContent.data`, and its
+text content includes a bounded preview of returned records. This keeps agents that can
+only reason over MCP `content[]` from seeing only a count summary while preserving
+`structuredContent` as the canonical machine-readable result.
+
+The `query_records` page is bounded by the spec-core §8 contract: omitting `limit` returns
+at most 25 records, and `limit` is capped at 100. This tool advertises `100` as the input
+maximum and rejects a larger `limit` at input validation, so the page size you request is
+the page size you get — page forward with the returned `cursor` rather than asking for a
+bigger page. (A direct REST client that sends `limit > 100` is clamped to 100 and told so
+via a `limit_clamped` entry in the response `meta.warnings[]`; the cap is never silent on
+either surface.)
+
+### Filtering (`query_records`, `aggregate`, `search`)
+
+Pass `filter` as a **typed object**, not a pre-encoded query string. The adapter
+encodes it into the resource server's `filter[field]=value` (exact) and
+`filter[field][op]=value` (range) parameters for you:
+
+```jsonc
+// exact match
+{ "filter": { "user_id": "U123" } }
+// range (operators: gte, gt, lte, lt; AND together across fields)
+{ "filter": { "created_at": { "gte": "2026-01-01T00:00:00Z", "lt": "2026-02-01T00:00:00Z" } } }
+```
+
+Allowed fields and operators are advertised per stream by `GET /v1/schema`
+(`field_capabilities`) — discover them with the cheap
+`schema -> schema(stream) -> schema(stream, connection_id) -> query_records`
+path before constructing a filter. A legacy raw string using literal bracket syntax
+(`"filter[user_id]=U123"`) is still accepted and parsed. Any other string shape
+(a bare term like `"Vana"`, `"field=value"`, `"amount>100"`, or JSON encoded as a
+string) is **rejected with a typed `invalid_filter` error** — it is never
+silently forwarded as a bare `filter=` parameter (which the resource server
+ignores). `aggregate` and `search` accept the same typed `filter` input.
+
+`expand_limit` is typed the same way: pass an object keyed by relation name, for
+example `{ "expand": ["messages"], "expand_limit": { "messages": 3 } }`. The
+adapter encodes it as `expand_limit[messages]=3`; do not pre-encode bracket keys.
+
+`aggregate` is the token-efficient way to answer count / sum / min / max / distinct-count and
+grouped or time-bucketed rollup questions. It returns small bucket rows from
+`GET /v1/streams/{stream}/aggregate`, never record bodies — so an agent that needs "how many
+orders", "total spend by month", or "distinct senders" should call `aggregate` instead of
+paging `query_records` and counting client-side. Group with exactly one dimension per call
+(`group_by` for a scalar field XOR `group_by_time` + `granularity` for a date field).
+Groupable, time-bucketable, and distinct-able fields are advertised by `GET /v1/schema`
+(`field_capabilities.*.aggregation`). The aggregate tool result `content[]` text includes
+the metric, stream, and numeric result (or a compact preview of grouped buckets with their
+counts) so an agent that can read only `content[]` still gets the answer; the canonical
+envelope remains in `structuredContent.data`.
+
+`search` is bounded the same way: omitting `limit` returns at most 25 hits, and `limit` is
+capped at 100 — the bound the published `/v1/search`, `/v1/search/semantic`, and
+`/v1/search/hybrid` contract declares and every mode honors (advertised as
+`capabilities.{lexical,semantic,hybrid}_retrieval.max_limit`). This tool advertises `100` as
+the input maximum and rejects a larger `limit` at input validation, so the page size you
+request is the page size you get — page forward with the returned `cursor` (lexical and
+semantic; hybrid does not page) rather than asking for a bigger page. The MCP input cap is
+the primary safeguard against an agent silently losing the page size it asked for: an over-cap
+`limit` never reaches the RS from this tool. A _direct REST_ caller that sends `limit > 100`
+is still served a bounded page, and — like `query_records` — now receives a structured
+`limit_clamped` warning in `meta.warnings[]` (carrying `detail.requested_limit` /
+`detail.max_limit`) on all three search modes, so the clamp is never silent on any read
+surface.
+
+Use lexical search for exact known terms. Semantic search is approximate
+retrieval; it can surface conceptually related records but is not a replacement
+for exact-term lookup when a user names a literal string.
+
+When a response or typed `ambiguous_connection` error includes both `connection_id` and
+`grant_id`, use `connection_id` as the stable data-source selector. `grant_id` identifies
+the current authorization grant and can change when the owner reconnects or re-authorizes
+the client. Do not persist `grant_id` as a reconnect-stable source identifier.
+
+## Hosted Streamable HTTP helper
+
+Reference servers can mount hosted MCP by authenticating the incoming bearer themselves,
+then passing a Web `Request` plus scoped token to `handleStreamableHttpRequest()`:
+
+```js
+import { handleStreamableHttpRequest } from '@pdpp/mcp-server';
+
+const response = await handleStreamableHttpRequest(request, {
+  providerUrl: 'https://pdpp.example.com',
+  accessToken: scopedClientBearer,
+});
+```
+
+The helper creates a fresh server and Streamable HTTP transport per request with MCP
+session ids disabled. `/mcp` serves the profile-free normal read surface.
+
+## Errors
+
+Resource-server error responses (4xx/5xx including `invalid_token`, `insufficient_scope`,
+`needs_broader_grant`, `invalid_cursor`) are surfaced as MCP `isError: true` results with
+the original envelope preserved in `structuredContent.error`. The adapter does not retry
+with broader credentials.

package/bin/pdpp-mcp-server.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { runMcpServerCli } from '../src/index.js';
+
+runMcpServerCli(process.argv.slice(2)).then(
+  (code) => {
+    process.exit(code);
+  },
+  (error) => {
+    process.stderr.write(`pdpp-mcp-server: ${error?.stack ?? error}\n`);
+    process.exit(1);
+  }
+);

package/package.json

@@ -1,9 +1,53 @@
 {
   "name": "@pdpp/mcp-server",
-  "version": "0.0.0",
-  "description": "Local stdio MCP adapter for PDPP grant-scoped reads. Placeholder release; real versions are published by the repository's semantic-release pipeline under the beta dist-tag.",
+  "version": "0.1.0-beta.8",
+  "description": "Local stdio MCP adapter for grant-scoped PDPP reads and event-subscription management.",
+  "type": "module",
+  "bin": {
+    "pdpp-mcp-server": "bin/pdpp-mcp-server.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "verify": "pnpm test && node bin/pdpp-mcp-server.js --help",
+    "pack:dry-run": "pnpm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@pdpp/cli": "workspace:*",
+    "zod": "^3.25.76"
+  },
+  "keywords": [
+    "pdpp",
+    "personal-data",
+    "mcp",
+    "model-context-protocol"
+  ],
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vana-com/pdpp.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/vana-com/pdpp/issues"
+  },
+  "homepage": "https://github.com/vana-com/pdpp#readme",
+  "engines": {
+    "node": ">=22.14.0"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": false,
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
   }
 }

package/src/credentials.js

@@ -0,0 +1,99 @@
+import { readStoredCredential } from '@pdpp/cli';
+
+export class CredentialError extends Error {
+  constructor(code, message, exitCode = 78) {
+    super(message);
+    this.name = 'CredentialError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Load a scoped PDPP client credential from the `pdpp connect` cache.
+ *
+ * Owner credentials are refused by default; the adapter uses a grant-scoped bearer
+ * token for PDPP reads and event-subscription management. The env-derived
+ * `PDPP_OWNER_TOKEN` is never consulted.
+ */
+export async function loadScopedCredential(providerUrl, options = {}) {
+  if (!providerUrl) {
+    throw new CredentialError(
+      'no_provider_url',
+      'Provider URL required. Pass --provider-url <url> or set PDPP_PROVIDER_URL.',
+      64
+    );
+  }
+
+  let result;
+  try {
+    result = await readStoredCredential(providerUrl, { cacheRoot: options.cacheRoot });
+  } catch (error) {
+    if (error?.code === 'not_connected') {
+      throw new CredentialError(
+        'not_connected',
+        `No scoped PDPP credential cached for ${providerUrl}. Run \`pdpp connect ${providerUrl}\` and try again.`,
+        78
+      );
+    }
+    if (error?.code === 'credential_expired') {
+      throw new CredentialError(
+        'credential_expired',
+        `Cached PDPP credential for ${providerUrl} is expired. Run \`pdpp connect ${providerUrl}\` again.`,
+        78
+      );
+    }
+    if (error?.code === 'credential_invalid') {
+      throw new CredentialError(
+        'credential_invalid',
+        `Cached PDPP credential for ${providerUrl} is malformed; re-run \`pdpp connect ${providerUrl}\`.`,
+        78
+      );
+    }
+    if (error?.code === 'invalid_provider_url') {
+      throw new CredentialError('invalid_provider_url', error.message, 64);
+    }
+    throw error;
+  }
+
+  const credential = result?.credential;
+  if (!credential?.access_token) {
+    throw new CredentialError(
+      'credential_invalid',
+      `Cached PDPP credential for ${providerUrl} is missing an access token.`,
+      78
+    );
+  }
+
+  if (isOwnerKind(credential)) {
+    throw new CredentialError(
+      'owner_token_refused',
+      `Cached credential for ${providerUrl} is an owner token; owner credentials are refused by the MCP adapter.`,
+      77
+    );
+  }
+
+  return {
+    providerUrl: result.providerUrl,
+    cacheFile: result.cacheFile,
+    accessToken: credential.access_token,
+    tokenType: credential.token_type ?? 'Bearer',
+    scope: credential.scope ?? result.payload?.scope ?? null,
+    grantId: credential.grant_id ?? result.payload?.grant_id ?? null,
+  };
+}
+
+function isOwnerKind(credential) {
+  if (!credential || typeof credential !== 'object') {
+    return false;
+  }
+  // The PDPP audit doc names `pdpp_token_kind=owner` as the owner-distinguishing claim
+  // on cached credentials. Treat any kind/role-shaped owner signal as a refusal trigger.
+  const flagged = [
+    credential.pdpp_token_kind,
+    credential.token_kind,
+    credential.kind,
+    credential.role,
+  ];
+  return flagged.some((value) => typeof value === 'string' && value.toLowerCase() === 'owner');
+}

package/src/index.js

@@ -0,0 +1,141 @@
+import { CredentialError, loadScopedCredential } from './credentials.js';
+import {
+  DEFAULT_SERVER_NAME,
+  DEFAULT_SERVER_VERSION,
+  startStdioServer,
+} from './server.js';
+
+const HELP = `pdpp-mcp-server — local stdio MCP adapter over a PDPP resource server
+
+Usage:
+  pdpp-mcp-server --provider-url <url> [--cache-root <dir>] [--server-name <name>]
+
+Environment:
+  PDPP_PROVIDER_URL      Default for --provider-url
+  PDPP_CACHE_ROOT        Default for --cache-root (defaults to .pdpp)
+  PDPP_MCP_SERVER_NAME   Default for --server-name
+
+The adapter uses a grant-scoped client token for the profile-free normal PDPP read
+surface. It refuses owner credentials and exits non-zero if no scoped grant token is
+cached for the provider. Run \`pdpp connect <provider-url>\` first.
+
+stdout is reserved for MCP protocol messages. Diagnostics go to stderr.
+`;
+
+/**
+ * Entry point used by both the published bin and tests.
+ *
+ * Resolves config from argv/env, loads the cached scoped client token, refuses owner
+ * credentials, and starts the stdio server. Returns the process exit code; callers are
+ * responsible for invoking process.exit().
+ */
+export async function runMcpServerCli(argv, deps = {}) {
+  const stderr = deps.stderr ?? process.stderr;
+  const env = deps.env ?? process.env;
+  const load = deps.loadScopedCredential ?? loadScopedCredential;
+  const start = deps.startStdioServer ?? startStdioServer;
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stderr.write(HELP);
+    return 0;
+  }
+  if (argv.includes('--version')) {
+    stderr.write(`${DEFAULT_SERVER_VERSION}\n`);
+    return 0;
+  }
+
+  let options;
+  try {
+    options = parseOptions(argv, env);
+  } catch (error) {
+    stderr.write(`pdpp-mcp-server: ${error.message}\n`);
+    stderr.write(HELP);
+    return error.exitCode ?? 64;
+  }
+
+  let credential;
+  try {
+    credential = await load(options.providerUrl, { cacheRoot: options.cacheRoot });
+  } catch (error) {
+    if (error instanceof CredentialError) {
+      stderr.write(`pdpp-mcp-server: ${error.message}\n`);
+      return error.exitCode;
+    }
+    stderr.write(`pdpp-mcp-server: ${error?.stack ?? error}\n`);
+    return 1;
+  }
+
+  stderr.write(
+    `pdpp-mcp-server: connected to ${credential.providerUrl} using scoped credential at ${credential.cacheFile}\n`
+  );
+
+  let handle;
+  try {
+    handle = await start({
+      providerUrl: credential.providerUrl,
+      accessToken: credential.accessToken,
+      serverName: options.serverName,
+    });
+  } catch (error) {
+    stderr.write(`pdpp-mcp-server: failed to start stdio server: ${error?.stack ?? error}\n`);
+    return 1;
+  }
+
+  // Block until the transport signals close (e.g. parent harness closes our stdin).
+  // Without this, the bin would exit immediately after wiring up the server and the
+  // child process would terminate before any MCP request could be processed.
+  if (handle && typeof handle.closed?.then === 'function') {
+    await handle.closed;
+  }
+
+  return 0;
+}
+
+export class OptionParseError extends Error {
+  constructor(message, exitCode = 64) {
+    super(message);
+    this.name = 'OptionParseError';
+    this.exitCode = exitCode;
+  }
+}
+
+export function parseOptions(argv, env) {
+  const providerUrl = readOption(argv, '--provider-url') ?? env.PDPP_PROVIDER_URL ?? '';
+  const cacheRoot = readOption(argv, '--cache-root') ?? env.PDPP_CACHE_ROOT ?? '.pdpp';
+  const serverName =
+    readOption(argv, '--server-name') ?? env.PDPP_MCP_SERVER_NAME ?? DEFAULT_SERVER_NAME;
+
+  if (!providerUrl) {
+    throw new OptionParseError('Missing --provider-url (or PDPP_PROVIDER_URL).');
+  }
+
+  if (env.PDPP_OWNER_TOKEN || env.PDPP_OWNER_SESSION_COOKIE) {
+    // Refuse to operate when an owner credential is in the environment even though
+    // we never consult it. Exposing the owner-mode self-export surface through MCP
+    // is the footgun the design forbids.
+    throw new OptionParseError(
+      'Refusing to start: owner credentials (PDPP_OWNER_TOKEN / PDPP_OWNER_SESSION_COOKIE) are present in the environment. Unset them before running the MCP adapter.',
+      77
+    );
+  }
+
+  return { providerUrl, cacheRoot, serverName };
+}
+
+function readOption(argv, name) {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  return argv[index + 1];
+}
+
+export { CredentialError, loadScopedCredential } from './credentials.js';
+export {
+  createPdppMcpServer,
+  handleStreamableHttpRequest,
+  startStdioServer,
+  DEFAULT_SERVER_NAME,
+  DEFAULT_SERVER_VERSION,
+  PDPP_MCP_TOOL_NAMES,
+} from './server.js';
+export { RsClient } from './rs-client.js';
+export { buildTools, buildStreamResourceTemplate, InvalidResourceUriError } from './tools.js';

package/src/rs-client.js

@@ -0,0 +1,167 @@
+/**
+ * Thin client over the PDPP resource server. Every request attaches the configured
+ * scoped client bearer token; no token rotation or owner fallback happens here.
+ */
+export class RsClient {
+  constructor({ providerUrl, accessToken, fetch = globalThis.fetch, userAgent }) {
+    if (typeof fetch !== 'function') {
+      throw new TypeError('RsClient requires a fetch implementation');
+    }
+    if (!providerUrl) {
+      throw new TypeError('RsClient requires providerUrl');
+    }
+    if (!accessToken) {
+      throw new TypeError('RsClient requires accessToken');
+    }
+    this.providerUrl = providerUrl.replace(/\/$/, '');
+    this.accessToken = accessToken;
+    this.fetch = fetch;
+    this.userAgent = userAgent ?? '@pdpp/mcp-server';
+  }
+
+  async getJson(path, { query, headers } = {}) {
+    const url = this.buildUrl(path, query);
+    const response = await this.fetch(url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${this.accessToken}`,
+        'User-Agent': this.userAgent,
+        ...(headers ?? {}),
+      },
+    });
+    return parseRsResponse(response, { expectJson: true });
+  }
+
+  async getRaw(path, { query, headers } = {}) {
+    const url = this.buildUrl(path, query);
+    const response = await this.fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        'User-Agent': this.userAgent,
+        ...(headers ?? {}),
+      },
+    });
+    return parseRsResponse(response, { expectJson: false });
+  }
+
+  async postJson(path, { body, query, headers } = {}) {
+    return this.sendJson('POST', path, { body, query, headers });
+  }
+
+  async patchJson(path, { body, query, headers } = {}) {
+    return this.sendJson('PATCH', path, { body, query, headers });
+  }
+
+  async deleteJson(path, { query, headers } = {}) {
+    return this.sendJson('DELETE', path, { body: undefined, query, headers });
+  }
+
+  async sendJson(method, path, { body, query, headers } = {}) {
+    const url = this.buildUrl(path, query);
+    const hasBody = body !== undefined && body !== null;
+    const init = {
+      method,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${this.accessToken}`,
+        'User-Agent': this.userAgent,
+        ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+        ...(headers ?? {}),
+      },
+    };
+    if (hasBody) {
+      init.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+    const response = await this.fetch(url, init);
+    return parseRsResponse(response, { expectJson: true });
+  }
+
+  buildUrl(path, query) {
+    const url = new URL(path.startsWith('/') ? path : `/${path}`, `${this.providerUrl}/`);
+    if (query && typeof query === 'object') {
+      for (const [key, value] of Object.entries(query)) {
+        appendQuery(url, key, value);
+      }
+    }
+    return url.toString();
+  }
+}
+
+function appendQuery(url, key, value) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      if (entry === undefined || entry === null) continue;
+      url.searchParams.append(key, String(entry));
+    }
+    return;
+  }
+  if (typeof value === 'object') {
+    throw new TypeError(
+      `query parameter '${key}' must be a scalar or array; encode nested query shapes explicitly before calling RsClient`,
+    );
+  }
+  url.searchParams.append(key, String(value));
+}
+
+async function parseRsResponse(response, { expectJson }) {
+  const status = response.status;
+  const contentType = response.headers?.get?.('content-type') ?? '';
+  const requestId = response.headers?.get?.('x-request-id') ?? null;
+
+  if (status >= 200 && status < 300) {
+    if (expectJson) {
+      if (status === 204) {
+        return { ok: true, status, body: null, requestId, contentType };
+      }
+      const body = contentType.includes('application/json') ? await response.json() : await response.text();
+      return { ok: true, status, body, requestId, contentType };
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    return { ok: true, status, body: buffer, requestId, contentType };
+  }
+
+  let errorBody = null;
+  try {
+    if (contentType.includes('application/json')) {
+      errorBody = await response.json();
+    } else {
+      errorBody = await response.text();
+    }
+  } catch {
+    errorBody = null;
+  }
+
+  const envelope = normalizeErrorEnvelope(errorBody, status);
+  if (requestId && envelope && typeof envelope === 'object' && !envelope.request_id) {
+    envelope.request_id = requestId;
+  }
+
+  return { ok: false, status, error: envelope, requestId, contentType };
+}
+
+function normalizeErrorEnvelope(body, status) {
+  if (body && typeof body === 'object') {
+    if (body.error && typeof body.error === 'object') {
+      return body.error;
+    }
+    if (typeof body.error === 'string') {
+      return {
+        type: body.error,
+        code: body.error,
+        message: body.error_description ?? body.message ?? body.error,
+      };
+    }
+    return body;
+  }
+
+  return {
+    type: 'rs_error',
+    code: `http_${status}`,
+    message: typeof body === 'string' && body.length > 0 ? body : `Resource server returned HTTP ${status}`,
+  };
+}