@raytio/mcp-server 3.0.0 → 3.1.1

package/README.md

@@ -145,13 +145,14 @@ Restart Codex CLI after editing the config. Inside a session, `/mcp` lists loade
 
 ### Tool domain selection
 
-The server decides which tools to expose using the following precedence:
+The server decides which tools to expose in two layers:
 
-1. **`RAYTIO_TOOL_DOMAINS` env var** (static override) — if set and non-empty, this value is used directly. No backend query is made.
-2. **Dynamic role resolution** — if `RAYTIO_TOOL_DOMAINS` is not set, the server queries the authenticated user's roles via `fnd_authz_user_groups()` at startup and maps them to tool domains automatically.
-3. **All domains** (fallback) — if the role query fails or returns no recognised roles, every domain is exposed (matching pre-v1.4.0 behaviour).
+1. **Role-domain filter** (coarse) — at startup the server queries the authenticated user's roles via `fnd_authz_user_groups()` and maps them to tool domains. The `RAYTIO_TOOL_DOMAINS` env var can further restrict this set but never expand it.
+2. **Effective-capability filter** (fine) — the server then calls the Persist RPC `fnd_get_effective_capabilities()` and drops any tool whose declared `(resource_group, resource_name, operation, scope)` requirement is not satisfied. `OWN_RECORDS` grants NEVER silently satisfy `ALL_RECORDS` requirements.
 
-The server logs which path was taken at startup (to stderr).
+Both layers **fail closed**: if the role query or capability RPC fails, or returns no recognised roles / no capabilities for a gated tool, that tool is not exposed. Dispatch re-checks capabilities at call time, so a stale `ListTools` result cannot bypass the check.
+
+The server logs which path was taken and how many tools were hidden at startup (to stderr).
 
 #### How dynamic resolution works
 

package/dist/authorization.d.ts

@@ -1,4 +1,6 @@
+import { EffectiveCapabilityIndex } from './capabilities/effective-capabilities.js';
 import { RaytioApiClient } from './raytio/api-client.js';
+import { Tool } from './tools/registry.js';
 /**
  * Result of resolving the effective tool domain set for the authenticated
  * user. When `authorized` is `false`, the caller MUST expose no tools.
@@ -10,20 +12,43 @@ export interface AuthorizationResult {
     reason: string;
     /** `true` when the caller should expose tools. `false` means fail closed — expose nothing. */
     authorized: boolean;
+    /**
+     * Immutable index over the caller's effective Persist capabilities.
+     * Present only when the effective-capabilities RPC was fetched and
+     * validated successfully. Consumers use this both to filter the
+     * advertised tool list and to gate `CallTool` dispatch.
+     */
+    capabilities?: EffectiveCapabilityIndex;
 }
 type StderrLogger = Pick<Console, 'error'>;
 /**
  * Resolve the tool domain surface for the authenticated user.
  *
  * Behaviour:
- *  - Always queries the backend for the user's resolved roles. On any
- *    failure, fails closed and exposes no tools.
+ *  - Always queries the backend for the user's resolved roles AND
+ *    effective Persist capabilities. On any failure of either query,
+ *    fails closed and exposes no tools.
  *  - The static `RAYTIO_TOOL_DOMAINS` override may only *restrict* the
  *    user's resolved domain set. It never grants access to domains the
  *    user does not have.
  *  - If the intersection is empty (or the user has no recognised roles),
  *    fails closed.
+ *  - The returned `capabilities` index is used downstream by
+ *    {@link filterToolsByCapabilities} and by the dispatch layer to
+ *    enforce per-tool authorisation at both advertisement and call time.
  */
 export declare function resolveToolDomains(apiClient: RaytioApiClient, envSpec: string | undefined, logger?: StderrLogger): Promise<AuthorizationResult>;
+/**
+ * Drop any tool whose declared `capabilities` are not satisfied by the
+ * caller's effective capability set. Tools that have no `capabilities`
+ * declaration pass through unchanged — they are gated only by the
+ * coarser role-domain filter until they are migrated onto the pinned
+ * Persist resource contract (see WI-0003500 onward).
+ *
+ * A tool with an empty `capabilities` array is treated as declaring
+ * "requires no permission" and passes through — the empty list is an
+ * explicit affirmation, not a fallthrough.
+ */
+export declare function filterToolsByCapabilities(tools: readonly Tool[], capabilities: EffectiveCapabilityIndex, logger?: StderrLogger): Tool[];
 export {};
 //# sourceMappingURL=authorization.d.ts.map

package/dist/authorization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mHAAmH;IACnH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAgD3C;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,GAAE,YAAsB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAyC9B"}
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,wBAAwB,EAEzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mHAAmH;IACnH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;CACzC;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAgD3C;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,GAAE,YAAsB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAqE9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,YAAY,EAAE,wBAAwB,EACtC,MAAM,GAAE,YAAsB,GAC7B,IAAI,EAAE,CA8BR"}

package/dist/authorization.js

@@ -1,3 +1,4 @@
+import { EffectiveCapabilityError, fetchEffectiveCapabilities, } from './capabilities/effective-capabilities.js';
 import { resolveUserDomains } from './tools/role-mapping.js';
 /**
  * Domains that a static override may resolve to when the user only holds
@@ -44,13 +45,17 @@ function restrictToUserDomains(staticDomains, userDomains) {
  * Resolve the tool domain surface for the authenticated user.
  *
  * Behaviour:
- *  - Always queries the backend for the user's resolved roles. On any
- *    failure, fails closed and exposes no tools.
+ *  - Always queries the backend for the user's resolved roles AND
+ *    effective Persist capabilities. On any failure of either query,
+ *    fails closed and exposes no tools.
  *  - The static `RAYTIO_TOOL_DOMAINS` override may only *restrict* the
  *    user's resolved domain set. It never grants access to domains the
  *    user does not have.
  *  - If the intersection is empty (or the user has no recognised roles),
  *    fails closed.
+ *  - The returned `capabilities` index is used downstream by
+ *    {@link filterToolsByCapabilities} and by the dispatch layer to
+ *    enforce per-tool authorisation at both advertisement and call time.
  */
 export async function resolveToolDomains(apiClient, envSpec, logger = console) {
     const staticDomains = parseSpec(envSpec);
@@ -69,10 +74,28 @@ export async function resolveToolDomains(apiClient, envSpec, logger = console) {
         logger.error(`Raytio MCP: ${reason} — exposing no tools (fail closed)`);
         return { domainSpec: undefined, reason, authorized: false };
     }
+    let capabilities;
+    try {
+        capabilities = await fetchEffectiveCapabilities(apiClient);
+    }
+    catch (err) {
+        const detail = err instanceof EffectiveCapabilityError
+            ? err.message
+            : `unexpected error: ${err.message}`;
+        const reason = `effective capabilities discovery failed: ${detail}`;
+        logger.error(`Raytio MCP: ${reason} — exposing no tools (fail closed)`);
+        return { domainSpec: undefined, reason, authorized: false };
+    }
+    logger.error(`Raytio MCP: fetched ${capabilities.size} effective capability rows for authenticated user`);
     if (staticDomains.length === 0) {
         const spec = userDomains.join(',');
         logger.error(`Raytio MCP: resolved domains from user roles: ${spec}`);
-        return { domainSpec: spec, reason: 'resolved from user roles', authorized: true };
+        return {
+            domainSpec: spec,
+            reason: 'resolved from user roles',
+            authorized: true,
+            capabilities,
+        };
     }
     const allowed = restrictToUserDomains(staticDomains, userDomains);
     if (allowed.length === 0) {
@@ -82,6 +105,46 @@ export async function resolveToolDomains(apiClient, envSpec, logger = console) {
     }
     const spec = allowed.join(',');
     logger.error(`Raytio MCP: static RAYTIO_TOOL_DOMAINS restricted user roles (${userDomains.join(',')}) to ${spec}`);
-    return { domainSpec: spec, reason: 'restricted by static override', authorized: true };
+    return {
+        domainSpec: spec,
+        reason: 'restricted by static override',
+        authorized: true,
+        capabilities,
+    };
+}
+/**
+ * Drop any tool whose declared `capabilities` are not satisfied by the
+ * caller's effective capability set. Tools that have no `capabilities`
+ * declaration pass through unchanged — they are gated only by the
+ * coarser role-domain filter until they are migrated onto the pinned
+ * Persist resource contract (see WI-0003500 onward).
+ *
+ * A tool with an empty `capabilities` array is treated as declaring
+ * "requires no permission" and passes through — the empty list is an
+ * explicit affirmation, not a fallthrough.
+ */
+export function filterToolsByCapabilities(tools, capabilities, logger = console) {
+    const allowed = [];
+    let hidden = 0;
+    for (const tool of tools) {
+        if (!tool.capabilities || tool.capabilities.length === 0) {
+            allowed.push(tool);
+            continue;
+        }
+        const missing = tool.capabilities.filter((req) => !capabilities.satisfies(req));
+        if (missing.length === 0) {
+            allowed.push(tool);
+            continue;
+        }
+        hidden += 1;
+        const detail = missing
+            .map((r) => `${r.resourceGroup}.${r.resourceName}#${r.operation}@${r.scope ?? 'OWN_RECORDS'}`)
+            .join(', ');
+        logger.error(`Raytio MCP: hiding tool "${tool.name}" — missing capability: ${detail}`);
+    }
+    if (hidden > 0) {
+        logger.error(`Raytio MCP: capability filter hid ${hidden}/${tools.length} tools`);
+    }
+    return allowed;
 }
 //# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/effective-capabilities.d.ts

@@ -0,0 +1,241 @@
+import { z } from 'zod';
+import { RaytioApiClient } from '../raytio/api-client.js';
+/**
+ * Client and index for the supported Persist "effective capabilities" RPC
+ * (`public.fnd_get_effective_capabilities()`), owned by WI-0003499.
+ *
+ * The RPC returns one row per (resource_group, resource_name, operation)
+ * tuple that the authenticated user may exercise. MCP uses that set to
+ * authorise both tool advertisement (`ListTools`) and tool dispatch
+ * (`CallTool`).
+ *
+ * Row semantics — see `docs/mcp-effective-capabilities.md` in the Persist
+ * repository:
+ *
+ *  - `resource_group` — 3-letter module code (e.g. `HRM`, `DSM`, `FAR`).
+ *    Matches `resources[*].permission.resource_group` in the pinned MCP
+ *    resource contract.
+ *  - `resource_name` — resource-scoped code (e.g. `ACCESS_APPLICATIONS`),
+ *    or `null` for a domain-level permission that applies to every
+ *    resource in the group. Persist suppresses domain rows when
+ *    table-specific entries exist for the same (group, operation) —
+ *    MCP relies on that shadowing and does not re-check it here.
+ *  - `operation` — one of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or a
+ *    semantic operation seeded into the `HRM_PERMISSIONS_OPERATION`
+ *    lookup.
+ *  - `scope` — exactly one of `ALL_RECORDS` or `ROW_BOUNDED` on the wire.
+ *    `ALL_RECORDS` means "verified unbounded HRM access". `ROW_BOUNDED`
+ *    means "the HRM grant exists at OWN_RECORDS scope but real access is
+ *    via ownership / ReBAC / row filters — treat as informational". A
+ *    `NULL` scope is coerced to `ROW_BOUNDED` inside the RPC, never to
+ *    unbounded. MCP normalises `ROW_BOUNDED` to the pre-existing internal
+ *    alias `OWN_RECORDS` on ingress (see {@link CAPABILITY_SCOPES}); both
+ *    names refer to the same "not verified unbounded" semantic, so the
+ *    rest of the MCP code path — CapabilityRequirement, satisfies(),
+ *    dispatch — is unchanged. Reconciled in WI-0003661.
+ *  - `advisory` — `TRUE` iff `scope = ROW_BOUNDED`; `FALSE` for
+ *    `ALL_RECORDS`. Redundant with `scope` today; accepted (optional) on
+ *    the wire so a producer-side addition remains non-breaking.
+ *
+ * When the caller reaches the same capability at both `ALL_RECORDS` and
+ * `ROW_BOUNDED`, the RPC collapses the row to `ALL_RECORDS`. MCP relies
+ * on that guarantee — the client does not attempt its own scope merge.
+ *
+ * MCP fails closed on any of:
+ *  - HTTP transport failure,
+ *  - JSON that does not parse or does not match the schema below,
+ *  - unknown values in `operation` or `scope`,
+ *  - a required tool capability that is not present in the returned set.
+ *
+ * `OWN_RECORDS` MUST NEVER silently become `ALL_RECORDS` — the tool
+ * declaration carries the scope its handler is safe with, and a broader
+ * effective capability satisfies it; a narrower one does not.
+ *
+ * ---
+ *
+ * Deliberate deviation from Persist's interpretation invariant
+ * (WI-0003661):
+ *
+ * Persist's contract states that "absence means unknown — ask the
+ * database" and that `ROW_BOUNDED` rows are informational, not a
+ * deny-side authorisation gate. MCP intentionally departs from that on
+ * the tool-advertisement path:
+ *
+ *  - {@link filterToolsByCapabilities} HIDES any tool whose declared
+ *    capabilities are missing from the caller's returned set.
+ *  - {@link EffectiveCapabilityIndex.satisfies} returns `false` when the
+ *    caller holds no matching row.
+ *
+ * The rationale is fail-closed advertisement: exposing a tool a caller
+ * cannot execute is a poor UX and leaks the shape of the denied surface.
+ * The database still enforces at call time — HRM permissions, ownership,
+ * and ReBAC all continue to gate the underlying query — so any tool
+ * whose actual access path is via ownership or ReBAC (never surfaced by
+ * this RPC) will be hidden until an explicit capability is granted or
+ * the tool's declaration is loosened. This is a design choice, not an
+ * oversight; revisit if MCP ever needs to advertise
+ * ownership/ReBAC-only tools.
+ */
+/**
+ * Wire-side scope vocabulary the RPC emits (per Persist's
+ * `docs/mcp-effective-capabilities.md`, WI-0003499):
+ *
+ *   - `ALL_RECORDS` — verified unbounded HRM access.
+ *   - `ROW_BOUNDED` — advisory HRM row; actual access via
+ *     ownership / ReBAC / row filters.
+ *
+ * The legacy `OWN_RECORDS` label — the pre-rename name for `ROW_BOUNDED`
+ * — is still accepted for transitional deployments of Persist; both
+ * legacy and current values are normalised to the internal
+ * `OWN_RECORDS` alias.
+ */
+export declare const WIRE_CAPABILITY_SCOPES: readonly ["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"];
+export type WireCapabilityScope = (typeof WIRE_CAPABILITY_SCOPES)[number];
+/**
+ * MCP-internal scope vocabulary used by {@link CapabilityRequirement}
+ * declarations and by the scope stored inside
+ * {@link EffectiveCapabilityIndex}. Persist's `ROW_BOUNDED` is
+ * normalised to `OWN_RECORDS` on ingress — the two names encode the
+ * same semantic ("not a verified unbounded HRM grant — enforcement of
+ * access is via ownership / ReBAC / row filters at call time").
+ *
+ * Internal-only rename to `ROW_BOUNDED` was deliberately deferred: no
+ * tool currently declares a scope, so the alias keeps this WI a
+ * one-file change (WI-0003661). Rename in a follow-up if the internal
+ * vocabulary starts to feel misleading.
+ */
+export declare const CAPABILITY_SCOPES: readonly ["ALL_RECORDS", "OWN_RECORDS"];
+export type CapabilityScope = (typeof CAPABILITY_SCOPES)[number];
+/**
+ * Zod schema for one row returned by `fnd_get_effective_capabilities()`.
+ * The RPC guarantees a `NOT NULL` `resource_group`, `operation`, and
+ * `scope`; `resource_name` may be `NULL` for a domain-level permission.
+ *
+ * Any structural drift here is a hard error — MCP MUST NOT accept an
+ * unknown scope value, empty operation, or malformed resource_group.
+ */
+export declare const effectiveCapabilityRowSchema: z.ZodObject<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+export type EffectiveCapabilityRow = z.infer<typeof effectiveCapabilityRowSchema>;
+export declare const effectiveCapabilityResponseSchema: z.ZodArray<z.ZodObject<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>, "many">;
+/**
+ * The declared capability requirement for a tool. A tool is authorised iff
+ * every requirement in its list is satisfied by the caller's effective
+ * capability set.
+ *
+ * The requirement is intentionally narrow — no wildcards, no "any op". A
+ * tool that reads and writes must declare both requirements. This keeps
+ * the authorisation graph auditable and cheap to reason about.
+ */
+export interface CapabilityRequirement {
+    /**
+     * Persist resource group (e.g. `WRM`). Compared case-insensitively
+     * against the RPC's `resource_group`.
+     */
+    resourceGroup: string;
+    /**
+     * Persist resource name (e.g. `ROLES`). Compared case-insensitively
+     * against the RPC's `resource_name`. A domain-level row
+     * (`resource_name: null`) satisfies any resource in the same group.
+     */
+    resourceName: string;
+    /** Operation code (e.g. `SELECT`). Compared case-insensitively. */
+    operation: string;
+    /**
+     * The minimum scope the tool's handler is safe with. `OWN_RECORDS`
+     * (the default) is satisfied by either `OWN_RECORDS` or `ALL_RECORDS`
+     * capabilities. `ALL_RECORDS` requires an `ALL_RECORDS` capability —
+     * an `OWN_RECORDS` capability is NOT sufficient, so an own-record
+     * grant can never silently become an all-record grant.
+     */
+    scope?: CapabilityScope;
+}
+/**
+ * Immutable index over the caller's effective capability set. Answers
+ * "does the user hold capability X at scope Y?" in O(1). Domain-level
+ * rows (`resource_name: null`) are pre-expanded so table-specific lookups
+ * still hit the map.
+ */
+export declare class EffectiveCapabilityIndex {
+    /**
+     * Map keys are `${GROUP}|${NAME|*}|${OPERATION}` (uppercase). The value
+     * is the strongest scope observed for that tuple.
+     *
+     * Domain-level rows are stored with `resource_name = "*"` — table-level
+     * lookups probe both the specific name and the wildcard.
+     */
+    private readonly index;
+    constructor(rows: EffectiveCapabilityRow[]);
+    /** Total number of effective (group, name, operation) rows held. */
+    get size(): number;
+    /**
+     * Return the strongest scope the caller holds for the (group, name,
+     * operation) tuple, or `undefined` if they hold no matching capability.
+     *
+     * A domain-level grant (`resource_name = null`) satisfies any resource
+     * in the same group.
+     */
+    lookup(resourceGroup: string, resourceName: string, operation: string): CapabilityScope | undefined;
+    /**
+     * `true` iff the caller holds a capability that satisfies the
+     * requirement. `OWN_RECORDS` requirements are satisfied by any grant.
+     * `ALL_RECORDS` requirements are satisfied only by an `ALL_RECORDS`
+     * grant — an `OWN_RECORDS` grant does NOT silently upgrade.
+     */
+    satisfies(requirement: CapabilityRequirement): boolean;
+}
+/**
+ * Error thrown when the RPC cannot be fetched, decoded, or validated.
+ * Callers MUST fail closed (expose no tools) on this error.
+ */
+export declare class EffectiveCapabilityError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** PostgREST path to the Persist RPC. */
+export declare const EFFECTIVE_CAPABILITIES_RPC_PATH = "/db/v1/rpc/fnd_get_effective_capabilities";
+/**
+ * Fetch the caller's effective capabilities from Persist, validate the
+ * response shape, and return an index ready for constant-time lookup.
+ *
+ * Throws {@link EffectiveCapabilityError} on any transport, decode, or
+ * validation failure. Callers MUST fail closed on that error — never fall
+ * back to a permissive default.
+ */
+export declare function fetchEffectiveCapabilities(apiClient: RaytioApiClient): Promise<EffectiveCapabilityIndex>;
+//# sourceMappingURL=effective-capabilities.d.ts.map

package/dist/capabilities/effective-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-capabilities.d.ts","sourceRoot":"","sources":["../../src/capabilities/effective-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,wDAIzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,yCAA0C,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAQjE;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;gCAuBzB,CAAC;AAEjB,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;yCAAwC,CAAC;AAEvF;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;gBAEzC,IAAI,EAAE,sBAAsB,EAAE;IAgB1C,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,MAAM,CACJ,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,eAAe,GAAG,SAAS;IAW9B;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,qBAAqB,GAAG,OAAO;CAWvD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,yCAAyC;AACzC,eAAO,MAAM,+BAA+B,8CACC,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,wBAAwB,CAAC,CAmBnC"}

package/dist/capabilities/effective-capabilities.js

@@ -0,0 +1,252 @@
+import { z } from 'zod';
+/**
+ * Client and index for the supported Persist "effective capabilities" RPC
+ * (`public.fnd_get_effective_capabilities()`), owned by WI-0003499.
+ *
+ * The RPC returns one row per (resource_group, resource_name, operation)
+ * tuple that the authenticated user may exercise. MCP uses that set to
+ * authorise both tool advertisement (`ListTools`) and tool dispatch
+ * (`CallTool`).
+ *
+ * Row semantics — see `docs/mcp-effective-capabilities.md` in the Persist
+ * repository:
+ *
+ *  - `resource_group` — 3-letter module code (e.g. `HRM`, `DSM`, `FAR`).
+ *    Matches `resources[*].permission.resource_group` in the pinned MCP
+ *    resource contract.
+ *  - `resource_name` — resource-scoped code (e.g. `ACCESS_APPLICATIONS`),
+ *    or `null` for a domain-level permission that applies to every
+ *    resource in the group. Persist suppresses domain rows when
+ *    table-specific entries exist for the same (group, operation) —
+ *    MCP relies on that shadowing and does not re-check it here.
+ *  - `operation` — one of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or a
+ *    semantic operation seeded into the `HRM_PERMISSIONS_OPERATION`
+ *    lookup.
+ *  - `scope` — exactly one of `ALL_RECORDS` or `ROW_BOUNDED` on the wire.
+ *    `ALL_RECORDS` means "verified unbounded HRM access". `ROW_BOUNDED`
+ *    means "the HRM grant exists at OWN_RECORDS scope but real access is
+ *    via ownership / ReBAC / row filters — treat as informational". A
+ *    `NULL` scope is coerced to `ROW_BOUNDED` inside the RPC, never to
+ *    unbounded. MCP normalises `ROW_BOUNDED` to the pre-existing internal
+ *    alias `OWN_RECORDS` on ingress (see {@link CAPABILITY_SCOPES}); both
+ *    names refer to the same "not verified unbounded" semantic, so the
+ *    rest of the MCP code path — CapabilityRequirement, satisfies(),
+ *    dispatch — is unchanged. Reconciled in WI-0003661.
+ *  - `advisory` — `TRUE` iff `scope = ROW_BOUNDED`; `FALSE` for
+ *    `ALL_RECORDS`. Redundant with `scope` today; accepted (optional) on
+ *    the wire so a producer-side addition remains non-breaking.
+ *
+ * When the caller reaches the same capability at both `ALL_RECORDS` and
+ * `ROW_BOUNDED`, the RPC collapses the row to `ALL_RECORDS`. MCP relies
+ * on that guarantee — the client does not attempt its own scope merge.
+ *
+ * MCP fails closed on any of:
+ *  - HTTP transport failure,
+ *  - JSON that does not parse or does not match the schema below,
+ *  - unknown values in `operation` or `scope`,
+ *  - a required tool capability that is not present in the returned set.
+ *
+ * `OWN_RECORDS` MUST NEVER silently become `ALL_RECORDS` — the tool
+ * declaration carries the scope its handler is safe with, and a broader
+ * effective capability satisfies it; a narrower one does not.
+ *
+ * ---
+ *
+ * Deliberate deviation from Persist's interpretation invariant
+ * (WI-0003661):
+ *
+ * Persist's contract states that "absence means unknown — ask the
+ * database" and that `ROW_BOUNDED` rows are informational, not a
+ * deny-side authorisation gate. MCP intentionally departs from that on
+ * the tool-advertisement path:
+ *
+ *  - {@link filterToolsByCapabilities} HIDES any tool whose declared
+ *    capabilities are missing from the caller's returned set.
+ *  - {@link EffectiveCapabilityIndex.satisfies} returns `false` when the
+ *    caller holds no matching row.
+ *
+ * The rationale is fail-closed advertisement: exposing a tool a caller
+ * cannot execute is a poor UX and leaks the shape of the denied surface.
+ * The database still enforces at call time — HRM permissions, ownership,
+ * and ReBAC all continue to gate the underlying query — so any tool
+ * whose actual access path is via ownership or ReBAC (never surfaced by
+ * this RPC) will be hidden until an explicit capability is granted or
+ * the tool's declaration is loosened. This is a design choice, not an
+ * oversight; revisit if MCP ever needs to advertise
+ * ownership/ReBAC-only tools.
+ */
+/**
+ * Wire-side scope vocabulary the RPC emits (per Persist's
+ * `docs/mcp-effective-capabilities.md`, WI-0003499):
+ *
+ *   - `ALL_RECORDS` — verified unbounded HRM access.
+ *   - `ROW_BOUNDED` — advisory HRM row; actual access via
+ *     ownership / ReBAC / row filters.
+ *
+ * The legacy `OWN_RECORDS` label — the pre-rename name for `ROW_BOUNDED`
+ * — is still accepted for transitional deployments of Persist; both
+ * legacy and current values are normalised to the internal
+ * `OWN_RECORDS` alias.
+ */
+export const WIRE_CAPABILITY_SCOPES = [
+    'ALL_RECORDS',
+    'ROW_BOUNDED',
+    'OWN_RECORDS',
+];
+/**
+ * MCP-internal scope vocabulary used by {@link CapabilityRequirement}
+ * declarations and by the scope stored inside
+ * {@link EffectiveCapabilityIndex}. Persist's `ROW_BOUNDED` is
+ * normalised to `OWN_RECORDS` on ingress — the two names encode the
+ * same semantic ("not a verified unbounded HRM grant — enforcement of
+ * access is via ownership / ReBAC / row filters at call time").
+ *
+ * Internal-only rename to `ROW_BOUNDED` was deliberately deferred: no
+ * tool currently declares a scope, so the alias keeps this WI a
+ * one-file change (WI-0003661). Rename in a follow-up if the internal
+ * vocabulary starts to feel misleading.
+ */
+export const CAPABILITY_SCOPES = ['ALL_RECORDS', 'OWN_RECORDS'];
+const wireScopeSchema = z
+    .enum(WIRE_CAPABILITY_SCOPES)
+    .transform((wire) => wire === 'ROW_BOUNDED' ? 'OWN_RECORDS' : wire);
+/**
+ * Zod schema for one row returned by `fnd_get_effective_capabilities()`.
+ * The RPC guarantees a `NOT NULL` `resource_group`, `operation`, and
+ * `scope`; `resource_name` may be `NULL` for a domain-level permission.
+ *
+ * Any structural drift here is a hard error — MCP MUST NOT accept an
+ * unknown scope value, empty operation, or malformed resource_group.
+ */
+export const effectiveCapabilityRowSchema = z
+    .object({
+    resource_group: z
+        .string()
+        .min(1)
+        .max(16)
+        .describe('Persist resource group code, e.g. "HRM", "DSM", "FAR"'),
+    resource_name: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe('Resource-specific code, or null for a domain-level permission'),
+    operation: z
+        .string()
+        .min(1)
+        .describe('Operation code, e.g. "SELECT", "INSERT", "UPDATE", "DELETE"'),
+    scope: wireScopeSchema,
+    // Redundant with `scope` — always true when scope=ROW_BOUNDED, false
+    // when scope=ALL_RECORDS. Not consumed by MCP today but declared so
+    // producer additions do not silently drop; optional so older Persist
+    // deployments that predate the advisory column still parse.
+    advisory: z.boolean().optional(),
+})
+    .passthrough();
+export const effectiveCapabilityResponseSchema = z.array(effectiveCapabilityRowSchema);
+/**
+ * Immutable index over the caller's effective capability set. Answers
+ * "does the user hold capability X at scope Y?" in O(1). Domain-level
+ * rows (`resource_name: null`) are pre-expanded so table-specific lookups
+ * still hit the map.
+ */
+export class EffectiveCapabilityIndex {
+    /**
+     * Map keys are `${GROUP}|${NAME|*}|${OPERATION}` (uppercase). The value
+     * is the strongest scope observed for that tuple.
+     *
+     * Domain-level rows are stored with `resource_name = "*"` — table-level
+     * lookups probe both the specific name and the wildcard.
+     */
+    index;
+    constructor(rows) {
+        this.index = new Map();
+        for (const row of rows) {
+            const group = row.resource_group.toUpperCase();
+            const name = (row.resource_name ?? '*').toUpperCase();
+            const op = row.operation.toUpperCase();
+            const key = `${group}|${name}|${op}`;
+            const previous = this.index.get(key);
+            // ALL_RECORDS always wins over OWN_RECORDS. The RPC already
+            // collapses duplicates but we defend in depth in case the row set
+            // is ever assembled from multiple sources.
+            if (previous === 'ALL_RECORDS')
+                continue;
+            this.index.set(key, row.scope);
+        }
+    }
+    /** Total number of effective (group, name, operation) rows held. */
+    get size() {
+        return this.index.size;
+    }
+    /**
+     * Return the strongest scope the caller holds for the (group, name,
+     * operation) tuple, or `undefined` if they hold no matching capability.
+     *
+     * A domain-level grant (`resource_name = null`) satisfies any resource
+     * in the same group.
+     */
+    lookup(resourceGroup, resourceName, operation) {
+        const group = resourceGroup.toUpperCase();
+        const name = resourceName.toUpperCase();
+        const op = operation.toUpperCase();
+        const specific = this.index.get(`${group}|${name}|${op}`);
+        const domain = this.index.get(`${group}|*|${op}`);
+        if (specific === 'ALL_RECORDS' || domain === 'ALL_RECORDS')
+            return 'ALL_RECORDS';
+        if (specific === 'OWN_RECORDS' || domain === 'OWN_RECORDS')
+            return 'OWN_RECORDS';
+        return undefined;
+    }
+    /**
+     * `true` iff the caller holds a capability that satisfies the
+     * requirement. `OWN_RECORDS` requirements are satisfied by any grant.
+     * `ALL_RECORDS` requirements are satisfied only by an `ALL_RECORDS`
+     * grant — an `OWN_RECORDS` grant does NOT silently upgrade.
+     */
+    satisfies(requirement) {
+        const held = this.lookup(requirement.resourceGroup, requirement.resourceName, requirement.operation);
+        if (!held)
+            return false;
+        const need = requirement.scope ?? 'OWN_RECORDS';
+        if (need === 'ALL_RECORDS')
+            return held === 'ALL_RECORDS';
+        return true;
+    }
+}
+/**
+ * Error thrown when the RPC cannot be fetched, decoded, or validated.
+ * Callers MUST fail closed (expose no tools) on this error.
+ */
+export class EffectiveCapabilityError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'EffectiveCapabilityError';
+    }
+}
+/** PostgREST path to the Persist RPC. */
+export const EFFECTIVE_CAPABILITIES_RPC_PATH = '/db/v1/rpc/fnd_get_effective_capabilities';
+/**
+ * Fetch the caller's effective capabilities from Persist, validate the
+ * response shape, and return an index ready for constant-time lookup.
+ *
+ * Throws {@link EffectiveCapabilityError} on any transport, decode, or
+ * validation failure. Callers MUST fail closed on that error — never fall
+ * back to a permissive default.
+ */
+export async function fetchEffectiveCapabilities(apiClient) {
+    let raw;
+    try {
+        raw = await apiClient.post(EFFECTIVE_CAPABILITIES_RPC_PATH, {});
+    }
+    catch (error) {
+        throw new EffectiveCapabilityError(`effective capabilities RPC failed: ${error.message}`, error);
+    }
+    const parsed = effectiveCapabilityResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new EffectiveCapabilityError(`effective capabilities response failed validation: ${parsed.error.message}`);
+    }
+    return new EffectiveCapabilityIndex(parsed.data);
+}
+//# sourceMappingURL=effective-capabilities.js.map

package/dist/capabilities/effective-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-capabilities.js","sourceRoot":"","sources":["../../src/capabilities/effective-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,7 +8,7 @@ import { PersistContractError, loadPersistResourceContract, } from './contracts/
 import { CognitoAuth } from './raytio/auth.js';
 import { RaytioApiClient } from './raytio/api-client.js';
 import { resolveDomains } from './tools/domains.js';
-import { resolveToolDomains } from './authorization.js';
+import { filterToolsByCapabilities, resolveToolDomains } from './authorization.js';
 import { dispatchToolCall } from './tools/dispatch.js';
 import { PACKAGE_VERSION } from './version.js';
 // Load configuration
@@ -42,14 +42,23 @@ const auth = new CognitoAuth({
 });
 const apiClient = new RaytioApiClient(config.raytio.apiBaseUrl, auth);
 const ctx = { apiClient, auth, config };
-// Resolve tool domains. The static RAYTIO_TOOL_DOMAINS override may only
-// restrict the user's resolved roles — it never grants access to a domain
-// the user does not already hold. Any failure to resolve roles fails closed
-// (expose no tools) rather than falling back to the full surface.
+// Resolve tool domains AND the caller's effective Persist capabilities.
+// The static RAYTIO_TOOL_DOMAINS override may only restrict the user's
+// resolved roles — it never grants access to a domain the user does not
+// already hold. Any failure to resolve roles or discover capabilities
+// fails closed (expose no tools) rather than falling back to the full
+// surface.
 const authorization = await resolveToolDomains(apiClient, process.env.RAYTIO_TOOL_DOMAINS);
-const allTools = authorization.authorized
+const domainTools = authorization.authorized
     ? resolveDomains(authorization.domainSpec)
     : [];
+// Layer the effective-capability filter on top of the role-domain filter.
+// Tools without a declared `capabilities` field pass through unchanged —
+// they remain gated by the role-domain filter until they are migrated
+// onto the pinned Persist resource contract (WI-0003500 onward).
+const allTools = authorization.authorized && authorization.capabilities
+    ? filterToolsByCapabilities(domainTools, authorization.capabilities)
+    : domainTools;
 console.error(`Raytio MCP: exposing ${allTools.length} tools` +
     (authorization.domainSpec
         ? ` (domains: ${authorization.domainSpec})`
@@ -74,10 +83,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     };
 });
 // Handle tool calls — dispatch centrally so every input is parsed through
-// its Zod schema before the tool handler is invoked.
+// its Zod schema and every declared capability is re-checked before the
+// tool handler is invoked. Passing the capability index through here
+// closes the gap where a client discovers a tool name out-of-band or via
+// a stale ListTools result.
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args = {} } = request.params;
-    const response = await dispatchToolCall(allTools, name, args, ctx);
+    const response = await dispatchToolCall(allTools, name, args, ctx, authorization.capabilities);
     return {
         content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
         ...(response.success ? {} : { isError: true }),

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/dispatch.d.ts

@@ -1,18 +1,25 @@
+import { EffectiveCapabilityIndex } from '../capabilities/effective-capabilities.js';
 import { Tool, ToolContext } from './registry.js';
 import { ToolResponse } from './types.js';
 export declare const INPUT_VALIDATION_ERROR = "INPUT_VALIDATION_ERROR";
 export declare const UNKNOWN_TOOL = "UNKNOWN_TOOL";
 export declare const TOOL_ERROR = "TOOL_ERROR";
+export declare const CAPABILITY_DENIED = "CAPABILITY_DENIED";
 /**
  * Central dispatch entry point for every MCP `tools/call` request.
  *
  * Guarantees:
  *  - The advertised Zod schema is parsed before the tool handler runs,
  *    so handlers only ever see structurally valid input.
+ *  - When an effective-capability index is provided, every declared
+ *    capability on the tool is re-checked at dispatch time. A missing
+ *    capability aborts the call with `CAPABILITY_DENIED` — this is
+ *    belt-and-braces protection against a caller that discovered the
+ *    tool name out-of-band or through a stale ListTools result.
  *  - Unknown tool names return a stable `UNKNOWN_TOOL` error rather than
  *    passing an arbitrary name deeper into the stack.
  *  - Handler exceptions are converted to structured `TOOL_ERROR`
  *    responses so the MCP transport always sees a well-formed reply.
  */
-export declare function dispatchToolCall(tools: Tool[], name: string, args: unknown, ctx: ToolContext): Promise<ToolResponse<unknown>>;
+export declare function dispatchToolCall(tools: Tool[], name: string, args: unknown, ctx: ToolContext, capabilities?: EffectiveCapabilityIndex): Promise<ToolResponse<unknown>>;
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/tools/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,IAAI,EAAE,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAqBhC"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,IAAI,EAAE,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,EAChB,YAAY,CAAC,EAAE,wBAAwB,GACtC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAsChC"}

package/dist/tools/dispatch.js

@@ -2,22 +2,37 @@ import { errorResponse } from './types.js';
 export const INPUT_VALIDATION_ERROR = 'INPUT_VALIDATION_ERROR';
 export const UNKNOWN_TOOL = 'UNKNOWN_TOOL';
 export const TOOL_ERROR = 'TOOL_ERROR';
+export const CAPABILITY_DENIED = 'CAPABILITY_DENIED';
 /**
  * Central dispatch entry point for every MCP `tools/call` request.
  *
  * Guarantees:
  *  - The advertised Zod schema is parsed before the tool handler runs,
  *    so handlers only ever see structurally valid input.
+ *  - When an effective-capability index is provided, every declared
+ *    capability on the tool is re-checked at dispatch time. A missing
+ *    capability aborts the call with `CAPABILITY_DENIED` — this is
+ *    belt-and-braces protection against a caller that discovered the
+ *    tool name out-of-band or through a stale ListTools result.
  *  - Unknown tool names return a stable `UNKNOWN_TOOL` error rather than
  *    passing an arbitrary name deeper into the stack.
  *  - Handler exceptions are converted to structured `TOOL_ERROR`
  *    responses so the MCP transport always sees a well-formed reply.
  */
-export async function dispatchToolCall(tools, name, args, ctx) {
+export async function dispatchToolCall(tools, name, args, ctx, capabilities) {
     const tool = tools.find((t) => t.name === name);
     if (!tool) {
         return errorResponse(UNKNOWN_TOOL, `Unknown tool: ${name}`);
     }
+    if (capabilities && tool.capabilities && tool.capabilities.length > 0) {
+        const missing = tool.capabilities.filter((req) => !capabilities.satisfies(req));
+        if (missing.length > 0) {
+            const detail = missing
+                .map((r) => `${r.resourceGroup}.${r.resourceName}#${r.operation}@${r.scope ?? 'OWN_RECORDS'}`)
+                .join(', ');
+            return errorResponse(CAPABILITY_DENIED, `Tool "${name}" requires capabilities the authenticated user does not hold: ${detail}`, { missing });
+        }
+    }
     const rawInput = args ?? {};
     const parsed = tool.inputSchema.safeParse(rawInput);
     if (!parsed.success) {

package/dist/tools/dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/tools/dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAEzD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAa,EACb,IAAY,EACZ,IAAa,EACb,GAAgB;IAEhB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,aAAa,CAAC,YAAY,EAAE,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,aAAa,CAClB,sBAAsB,EACtB,+BAA+B,IAAI,MAAM,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACvE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAChC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAiB;IACvC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACjE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/tools/dispatch.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAEzD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAa,EACb,IAAY,EACZ,IAAa,EACb,GAAgB,EAChB,YAAuC;IAEvC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,aAAa,CAAC,YAAY,EAAE,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAChF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,OAAO;iBACnB,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,KAAK,IAAI,aAAa,EAAE,CACpF;iBACA,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO,aAAa,CAClB,iBAAiB,EACjB,SAAS,IAAI,iEAAiE,MAAM,EAAE,EACtF,EAAE,OAAO,EAAE,CACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,aAAa,CAClB,sBAAsB,EACtB,+BAA+B,IAAI,MAAM,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACvE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAChC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAiB;IACvC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACjE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/tools/registry.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { RaytioApiClient } from '../raytio/api-client.js';
 import { CognitoAuth } from '../raytio/auth.js';
 import { Config } from '../config.js';
+import { CapabilityRequirement } from '../capabilities/effective-capabilities.js';
 import { ToolResponse } from './types.js';
 export interface ToolContext {
     apiClient: RaytioApiClient;
@@ -13,5 +14,17 @@ export interface Tool {
     description: string;
     inputSchema: z.ZodTypeAny;
     handler: (args: unknown, ctx: ToolContext) => Promise<ToolResponse<unknown>>;
+    /**
+     * Persist capabilities the caller MUST hold for this tool to be
+     * advertised or dispatched. Every requirement in the list must be
+     * satisfied — the tool acts as if the caller holds their intersection.
+     *
+     * Tools without an explicit `capabilities` field are not gated by the
+     * effective-capability check and rely on the coarser role-domain
+     * filter only. As tools migrate onto the pinned Persist resource
+     * contract (WI-0003500 onward), each new/regenerated tool is expected
+     * to declare its capabilities.
+     */
+    capabilities?: readonly CapabilityRequirement[];
 }
 //# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9E"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7E;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raytio/mcp-server",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "MCP server for secure AI agent access to Raytio user data",
   "type": "module",
   "main": "dist/index.js",