@raytio/mcp-server 3.0.0 → 3.4.0

package/dist/capabilities/effective-capabilities.js

@@ -0,0 +1,259 @@
+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").
+ *
+ * Vocabulary decision (WI-0003678): the internal alias is permanent.
+ * WI-0003661 deferred the internal `OWN_RECORDS → ROW_BOUNDED` rename
+ * on the grounds that no tool declared a scope yet. WI-0003678 changed
+ * that — every tool in {@link Tool.capabilities} now declares
+ * requirements through the contract-derived {@link cap} helper, and
+ * OWN_RECORDS is the default scope that helper produces. Renaming at
+ * this point would touch every capability declaration for no wire-side
+ * benefit (the wire vocabulary is already `ROW_BOUNDED` in Persist and
+ * the transform on ingress hides that from the rest of the code path).
+ * Keep {@link CAPABILITY_SCOPES} as-is; do not add a `ROW_BOUNDED`
+ * alias inside MCP.
+ */
+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/capabilities/tool-capability.d.ts

@@ -0,0 +1,52 @@
+import { CapabilityRequirement, CapabilityScope } from './effective-capabilities.js';
+interface ContractPermission {
+    resourceGroup: string;
+    resourceName: string;
+    operations: ReadonlySet<string>;
+}
+/**
+ * Capability requirements for the 6 RPC endpoints MCP calls. RPCs do not
+ * have a `table` entry in the pinned contract, so a matching capability
+ * MUST be declared by hand here and referenced via {@link rpcCap}. A tool
+ * calling an RPC not listed here fails the completeness test.
+ */
+export declare const RPC_CAPABILITIES: Readonly<Record<string, readonly ContractPermission[]>>;
+/** All operations that MCP knows how to map from an HTTP verb. */
+export declare const HTTP_VERBS: string[];
+/** Convert an HTTP verb (lower-case) into the Persist operation code. */
+export declare function verbToOperation(verb: string): string;
+/**
+ * Return a {@link CapabilityRequirement} for a tool that calls
+ * `/db/v1/<table>` with the given operation.
+ *
+ * Fails fast on:
+ *  - unknown table (typo, dropped from contract, forgot to sync);
+ *  - operation not in the contract's `operations` list for that resource
+ *    (e.g. declaring UPDATE on a view that is SELECT-only);
+ *  - invalid scope (guarded by {@link CAPABILITY_SCOPES}).
+ *
+ * @param table     PostgREST endpoint segment (e.g. `ppm_work_items`).
+ * @param operation One of `SELECT|INSERT|UPDATE|DELETE`, case-insensitive.
+ *                  Also accepts the HTTP verb (`get`/`post`/`patch`/`delete`).
+ * @param scope     Defaults to `OWN_RECORDS`. Only set to `ALL_RECORDS`
+ *                  when the tool genuinely needs cross-record reach
+ *                  (tenant-wide list/summary tools). See the WI-0003678
+ *                  scope-guidance block.
+ */
+export declare function cap(table: string, operation: string, scope?: CapabilityScope): CapabilityRequirement;
+/**
+ * Return the capability requirement(s) for a tool that calls
+ * `/db/v1/rpc/<name>`. Every RPC MCP surfaces MUST have an entry in
+ * {@link RPC_CAPABILITIES}; a missing entry throws.
+ */
+export declare function rpcCap(name: string, scope?: CapabilityScope): CapabilityRequirement[];
+/**
+ * Test-only: is this table known to the helper (via contract or override)?
+ * The completeness test uses this to detect drift between the tool source
+ * and the pinned contract without shelling out through {@link cap}.
+ */
+export declare function isKnownTable(table: string): boolean;
+/** Test-only: names of all RPCs the helper knows a capability for. */
+export declare function knownRpcs(): readonly string[];
+export {};
+//# sourceMappingURL=tool-capability.d.ts.map

package/dist/capabilities/tool-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-capability.d.ts","sourceRoot":"","sources":["../../src/capabilities/tool-capability.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,qBAAqB,EACrB,eAAe,EAChB,MAAM,6BAA6B,CAAC;AAsBrC,UAAU,kBAAkB;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAyDD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,CAoDpF,CAAC;AAUF,kEAAkE;AAClE,eAAO,MAAM,UAAU,UAA0B,CAAC;AAElD,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD;AAiBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,eAA+B,GACrC,qBAAqB,CAuBvB;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,eAA+B,GACrC,qBAAqB,EAAE,CAqBzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,sEAAsE;AACtE,wBAAgB,SAAS,IAAI,SAAS,MAAM,EAAE,CAE7C"}

package/dist/capabilities/tool-capability.js

@@ -0,0 +1,238 @@
+import { loadPersistResourceContract } from '../contracts/persist-resource-contract.js';
+import { CAPABILITY_SCOPES, } from './effective-capabilities.js';
+/**
+ * Contract-derived helper for declaring `Tool.capabilities` (WI-0003678).
+ *
+ * The pinned Persist resource contract (`contracts/persist/mcp_resource_contract.json`)
+ * already carries the resource-group / resource-name / operations tuple for
+ * every table MCP is allowed to surface. Rather than hand-writing those tuples
+ * in every tool file (a 748-call surface across 188 tools with predictable
+ * copy-paste drift), a tool calls {@link cap} with the table and operation it
+ * touches — the helper resolves the tuple at module load, and typos or dropped
+ * tables produce a hard error immediately.
+ *
+ * The completeness test (`src/tools/capability-completeness.test.ts`) scans
+ * every tool source for `/db/v1/<table>` literals and enforces that each is
+ * covered by a declared capability. Without that test, missing declarations
+ * fail open — the tool stays advertised even though it will short-circuit on
+ * dispatch.
+ */
+const contract = loadPersistResourceContract();
+const TABLE_TO_PERMISSION = (() => {
+    const map = new Map();
+    for (const resource of contract.resources) {
+        map.set(resource.table, {
+            resourceGroup: resource.permission.resource_group,
+            resourceName: resource.permission.resource_name,
+            operations: new Set(resource.permission.operations.map((o) => o.toUpperCase())),
+        });
+    }
+    return map;
+})();
+/**
+ * Overrides for tables that are deliberately EXCLUDED from the pinned
+ * resource contract (credentials-sensitive, internal permission tables,
+ * platform infrastructure) but that legitimate MCP tools still need to
+ * declare capabilities against.
+ *
+ * Every entry is a documented, reviewed exception — anything not in the
+ * pinned contract and not listed here will throw at module load. Do not
+ * add entries speculatively: an entry here means "MCP tools call this
+ * endpoint and we accept the sensitivity trade-off". Removing a tool that
+ * used one of these should remove the entry too.
+ *
+ * Verified against Persist naming convention (`<module>_<plural_snake>` →
+ * `<MODULE>.<PLURAL_SNAKE_UPPER>`), consistent across all in-contract
+ * resources in the same module. See wrm/, fnd/ sections of the contract.
+ */
+const CONTRACT_OVERRIDES = new Map([
+    [
+        'wrm_worker_credentials',
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'WORKER_CREDENTIALS',
+            operations: new Set(['INSERT', 'SELECT', 'UPDATE']),
+        },
+    ],
+    [
+        'wrm_credential_requests',
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'CREDENTIAL_REQUESTS',
+            operations: new Set(['INSERT', 'SELECT', 'UPDATE']),
+        },
+    ],
+    [
+        'fnd_notifications',
+        {
+            resourceGroup: 'FND',
+            resourceName: 'NOTIFICATIONS',
+            operations: new Set(['INSERT', 'SELECT', 'UPDATE']),
+        },
+    ],
+]);
+/**
+ * Capability requirements for the 6 RPC endpoints MCP calls. RPCs do not
+ * have a `table` entry in the pinned contract, so a matching capability
+ * MUST be declared by hand here and referenced via {@link rpcCap}. A tool
+ * calling an RPC not listed here fails the completeness test.
+ */
+export const RPC_CAPABILITIES = {
+    ppm_instantiate_epic_template: [
+        {
+            resourceGroup: 'PPM',
+            resourceName: 'EPIC_TEMPLATES',
+            operations: new Set(['SELECT']),
+        },
+        {
+            resourceGroup: 'PPM',
+            resourceName: 'WORK_ITEMS',
+            operations: new Set(['INSERT']),
+        },
+    ],
+    wrm_knowledge_chunk_search: [
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'KNOWLEDGE_CHUNKS',
+            operations: new Set(['SELECT']),
+        },
+    ],
+    wrm_context_aware_memory_search: [
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'ROLE_MEMORIES',
+            operations: new Set(['SELECT']),
+        },
+    ],
+    wrm_semantic_memory_search: [
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'ROLE_MEMORIES',
+            operations: new Set(['SELECT']),
+        },
+    ],
+    wrm_update_memory_access: [
+        {
+            resourceGroup: 'WRM',
+            resourceName: 'ROLE_MEMORIES',
+            operations: new Set(['UPDATE']),
+        },
+    ],
+    // fnd_authz_user_groups — advertised in the WI as a supported RPC; no
+    // current tool file calls it, but keep the row so a future consumer can
+    // reference it via `rpcCap('fnd_authz_user_groups')` without touching
+    // the helper. Verified as a semantic authz RPC per Persist docs.
+    fnd_authz_user_groups: [
+        {
+            resourceGroup: 'FND',
+            resourceName: 'USER_GROUPS',
+            operations: new Set(['SELECT']),
+        },
+    ],
+};
+const VERB_TO_OP = {
+    get: 'SELECT',
+    post: 'INSERT',
+    patch: 'UPDATE',
+    put: 'UPDATE',
+    delete: 'DELETE',
+};
+/** All operations that MCP knows how to map from an HTTP verb. */
+export const HTTP_VERBS = Object.keys(VERB_TO_OP);
+/** Convert an HTTP verb (lower-case) into the Persist operation code. */
+export function verbToOperation(verb) {
+    const op = VERB_TO_OP[verb.toLowerCase()];
+    if (!op) {
+        throw new Error(`Unknown HTTP verb "${verb}" — cannot map to a Persist operation. ` +
+            'Update VERB_TO_OP in src/capabilities/tool-capability.ts.');
+    }
+    return op;
+}
+function resolveTable(table) {
+    const fromContract = TABLE_TO_PERMISSION.get(table);
+    if (fromContract)
+        return fromContract;
+    const fromOverride = CONTRACT_OVERRIDES.get(table);
+    if (fromOverride)
+        return fromOverride;
+    throw new Error(`cap(): unknown table "${table}". The pinned Persist contract does not ` +
+        'declare a permission for it and no override is registered. Either the ' +
+        'table has been renamed / removed upstream (re-sync the contract with ' +
+        '`npm run contract:sync-resource`), or add a documented override in ' +
+        'src/capabilities/tool-capability.ts if MCP legitimately needs to hit ' +
+        'a resource excluded from the surface.');
+}
+/**
+ * Return a {@link CapabilityRequirement} for a tool that calls
+ * `/db/v1/<table>` with the given operation.
+ *
+ * Fails fast on:
+ *  - unknown table (typo, dropped from contract, forgot to sync);
+ *  - operation not in the contract's `operations` list for that resource
+ *    (e.g. declaring UPDATE on a view that is SELECT-only);
+ *  - invalid scope (guarded by {@link CAPABILITY_SCOPES}).
+ *
+ * @param table     PostgREST endpoint segment (e.g. `ppm_work_items`).
+ * @param operation One of `SELECT|INSERT|UPDATE|DELETE`, case-insensitive.
+ *                  Also accepts the HTTP verb (`get`/`post`/`patch`/`delete`).
+ * @param scope     Defaults to `OWN_RECORDS`. Only set to `ALL_RECORDS`
+ *                  when the tool genuinely needs cross-record reach
+ *                  (tenant-wide list/summary tools). See the WI-0003678
+ *                  scope-guidance block.
+ */
+export function cap(table, operation, scope = 'OWN_RECORDS') {
+    const permission = resolveTable(table);
+    const opUpper = VERB_TO_OP[operation.toLowerCase()] ?? operation.toUpperCase();
+    if (!permission.operations.has(opUpper)) {
+        throw new Error(`cap("${table}", "${operation}"): operation ${opUpper} is not in the ` +
+            `contract's permitted operations for ${permission.resourceGroup}.${permission.resourceName} ` +
+            `(supported: ${[...permission.operations].sort().join(', ')}). ` +
+            'Pick a different endpoint or fix the tool.');
+    }
+    if (!CAPABILITY_SCOPES.includes(scope)) {
+        throw new Error(`cap("${table}", "${operation}"): invalid scope "${scope}" — ` +
+            `must be one of ${CAPABILITY_SCOPES.join(', ')}.`);
+    }
+    return {
+        resourceGroup: permission.resourceGroup,
+        resourceName: permission.resourceName,
+        operation: opUpper,
+        scope,
+    };
+}
+/**
+ * Return the capability requirement(s) for a tool that calls
+ * `/db/v1/rpc/<name>`. Every RPC MCP surfaces MUST have an entry in
+ * {@link RPC_CAPABILITIES}; a missing entry throws.
+ */
+export function rpcCap(name, scope = 'OWN_RECORDS') {
+    const perms = RPC_CAPABILITIES[name];
+    if (!perms) {
+        throw new Error(`rpcCap(): unknown RPC "${name}". Add a documented entry to ` +
+            'RPC_CAPABILITIES in src/capabilities/tool-capability.ts before ' +
+            'referencing it from a tool.');
+    }
+    // Expand every operation in each entry. Taking only the first
+    // (`[...p.operations][0]`) silently dropped the rest, so a multi-op
+    // entry would under-declare and the tool would be advertised more
+    // permissively than it can actually execute.
+    return perms.flatMap((p) => [...p.operations].map((operation) => ({
+        resourceGroup: p.resourceGroup,
+        resourceName: p.resourceName,
+        operation,
+        scope,
+    })));
+}
+/**
+ * Test-only: is this table known to the helper (via contract or override)?
+ * The completeness test uses this to detect drift between the tool source
+ * and the pinned contract without shelling out through {@link cap}.
+ */
+export function isKnownTable(table) {
+    return TABLE_TO_PERMISSION.has(table) || CONTRACT_OVERRIDES.has(table);
+}
+/** Test-only: names of all RPCs the helper knows a capability for. */
+export function knownRpcs() {
+    return Object.keys(RPC_CAPABILITIES);
+}
+//# sourceMappingURL=tool-capability.js.map

package/dist/capabilities/tool-capability.js.map

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

package/dist/generated-reads/catalogue.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Assemble the full set of generated read tools from a pinned Persist
+ * resource contract. Consumers pass the contract loaded by
+ * {@link loadPersistResourceContract}; this module hands back a
+ * deterministic, filterable list of {@link Tool} objects ready to be
+ * exposed alongside hand-written tools.
+ *
+ * Safety filters applied by default (WI-0003501):
+ *
+ *  - Resources without a `list` or `read` operation are skipped — the
+ *    resource may exist only for write-only side-effect paths.
+ *  - Resources with `sensitivity` other than `normal` are skipped.
+ *    Callers who genuinely need them must set `includeSensitive: true`
+ *    on the filter; the resource-tools factory will still redact any
+ *    credential-shaped columns from every response.
+ *  - Resources that declare `side_effects` are ALWAYS skipped — there
+ *    is no opt-in. Generic CRUD around a state-transition or
+ *    notification path is a category error; dedicated tools with
+ *    explicit confirmation/idempotency semantics are required.
+ *
+ * Composite-primary-key resources still get describe + list; only the
+ * get-by-id tool is skipped.
+ */
+import type { PersistResource, PersistResourceContract } from '../contracts/persist-resource-contract.js';
+import { Tool } from '../tools/registry.js';
+import { ExclusionReason } from './guardrails.js';
+export interface CatalogueFilter {
+    /** Only emit tools for these modules. Case-insensitive; empty = all. */
+    modules?: string[];
+    /** Additional predicate — return `true` to include the resource. */
+    include?: (resource: PersistResource) => boolean;
+    /**
+     * When `true`, resources marked `sensitive`/`restricted` become
+     * eligible. Sensitive-field redaction still applies — the caller
+     * gains access to the resource's non-secret columns only. Default
+     * `false`.
+     *
+     * Side-effecting resources are NEVER made eligible by this flag —
+     * dedicated tools remain the only supported path for them.
+     */
+    includeSensitive?: boolean;
+}
+/**
+ * Result of one resource's exclusion, exposed on the report so
+ * operators and doc generators can explain "why is `foo_list` not in
+ * the surface?" without re-implementing the guardrails.
+ */
+export interface CatalogueExclusion {
+    resourceId: string;
+    module: string;
+    reasons: ExclusionReason[];
+}
+/** Report returned alongside the generated tool list. */
+export interface CatalogueReport {
+    tools: Tool[];
+    excluded: CatalogueExclusion[];
+}
+/**
+ * Deterministic, sorted list of generated read tools drawn from the
+ * pinned contract. Sorting is by (module, resource_id, tool_name) so
+ * `docs/tools.md` regeneration is reproducible.
+ *
+ * Sensitive and side-effecting resources are filtered out by default —
+ * see {@link CatalogueFilter} for the opt-in that lifts the sensitivity
+ * bar (nothing lifts the side-effect bar).
+ */
+export declare function buildGeneratedReadCatalogue(contract: PersistResourceContract, filter?: CatalogueFilter): Tool[];
+/**
+ * Same as {@link buildGeneratedReadCatalogue}, but also returns the list
+ * of resources the guardrails excluded and why. Used by tests and the
+ * doc generator to prove that the safety filter is doing its job — a
+ * silent skip is indistinguishable from a bug.
+ */
+export declare function buildGeneratedReadCatalogueReport(contract: PersistResourceContract, filter?: CatalogueFilter): CatalogueReport;
+/**
+ * Group the generated read tools by module. Modules with no eligible
+ * resources are omitted from the returned record.
+ */
+export declare function groupGeneratedReadsByModule(contract: PersistResourceContract, filter?: CatalogueFilter): Record<string, Tool[]>;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/generated-reads/catalogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../../src/generated-reads/catalogue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,uBAAuB,EACxB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAK5C,OAAO,EAEL,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC;IACjD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,eAAoB,GAC3B,IAAI,EAAE,CAER;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,eAAoB,GAC3B,eAAe,CAkCjB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,eAAoB,GAC3B,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAqBxB"}