@rockcarver/frodo-lib 4.10.0 → 4.11.0-1

package/types/mcp/CapabilityTypes.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Defines the canonical type contracts used by the MCP capability layer.
+ *
+ * @remarks
+ * This module is intentionally declarative. It provides the shared vocabulary for
+ * capability discovery, policy filtering, and runtime registration so each layer
+ * can evolve independently without breaking shape compatibility.
+ */
+import { OperationType } from '../shared/OperationType';
+/**
+ * Normalized operation kinds inferred from Frodo methods or explicitly supplied by
+ * metadata in future registry manifests.
+ *
+ * @remarks
+ * A type alias of the core library's deployment-agnostic `OperationType`
+ * (`shared/OperationType.ts`), not an independent definition — the MCP
+ * capability layer may depend on core library vocabulary, but core library
+ * code must never depend on `mcp/`, so the canonical union lives there.
+ */
+export type McpCapabilityOperationType = OperationType;
+/**
+ * Risk classification used by policy presets and launch-time exposure controls.
+ */
+export type McpCapabilityRiskClass = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * High-level classification of whether a capability maps to the generic MCP tool
+ * surface or must be exposed as a domain-specific operation.
+ */
+export type McpCapabilityKind = 'generic' | 'special';
+/**
+ * Caller-privilege tier a capability is safe to expose to.
+ *
+ * @remarks
+ * Deliberately not named "audience" — that term already has a specific,
+ * unrelated meaning in OAuth2/OIDC (a token's `aud` claim, matched against a
+ * resource server's own identifier). This is Frodo's own concept: today's
+ * `admin-account` and `service-account` auth modes are already full-trust
+ * identities, so `'full-trust'` is the universal default every capability
+ * gets unless explicitly narrowed. `'delegated'` marks a capability safe for
+ * a non-admin caller resolved via a real interactive (browser) login — see
+ * `ops/CallerTrustTierOps.ts`'s `determineCallerTrustTier()`. `'both'`
+ * covers capabilities safe for either.
+ */
+export type McpCapabilityTrustTier = 'full-trust' | 'delegated' | 'both';
+/**
+ * Deployment families that can be used to constrain capability exposure.
+ */
+export type McpDeploymentType = 'cloud' | 'classic' | 'forgeops' | 'any';
+/**
+ * MCP tool behavior hints that clients and models may use during tool selection.
+ */
+export type McpToolAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+/**
+ * Argument-shape contract surfaced to MCP callers for a capability.
+ */
+export type McpCapabilityArgumentMode = 'none' | 'positional' | 'named' | 'mixed';
+/**
+ * Lightweight JSON-schema-style contract for a structured MCP parameter value.
+ *
+ * @remarks
+ * This intentionally supports only the subset needed for agent guidance and
+ * runtime validation.
+ */
+export type McpCapabilityParameterSchema = {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+    description?: string;
+    enum?: unknown[];
+    properties?: Record<string, McpCapabilityParameterSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: McpCapabilityParameterSchema;
+};
+/**
+ * Parameter definition for a capability exposed through discovery metadata.
+ */
+export type McpCapabilityParameter = {
+    name: string;
+    type: string;
+    required?: boolean;
+    position?: number;
+    description?: string;
+    /** Optional MCP-side default applied when the caller omits this parameter. */
+    defaultValue?: unknown;
+    /** Optional schema contract for structured or enum-like parameter values. */
+    schema?: McpCapabilityParameterSchema;
+    /** Optional example values surfaced in discovery and validation errors. */
+    examples?: unknown[];
+};
+/**
+ * Per-parameter annotation overlay applied on top of an auto-derived
+ * parameter (see {@link OperationCapabilityMeta.parameterOverrides}).
+ *
+ * @remarks
+ * Deliberately excludes `name` and `position`: which parameters exist, in
+ * which order, always comes from the auto-derived signature (Help.ts,
+ * falling back to name-based inference) so it can't silently drift from the
+ * real bound method. `type` and `required` may be set here too, but only
+ * for refinements the type system can't express on its own (e.g. narrowing
+ * a `number` to a JSON-Schema `integer`, or documenting an MCP-dispatch-
+ * layer default that makes an otherwise-required parameter effectively
+ * optional at the call site) — not as a general-purpose escape hatch.
+ */
+export type McpCapabilityParameterOverlay = Partial<Pick<McpCapabilityParameter, 'type' | 'required' | 'description' | 'defaultValue' | 'schema' | 'examples'>>;
+/**
+ * Optional selector that disambiguates multiple capabilities sharing the same
+ * generic `(operationType, domain, objectType)` tuple.
+ */
+export type McpCapabilityScope = 'single' | 'bulk';
+/**
+ * Canonical capability descriptor produced by inventory/registry builders.
+ */
+export type McpCapabilityDescriptor = {
+    id: string;
+    toolName: string;
+    methodName: string;
+    modulePath: string[];
+    domain: string;
+    objectType: string;
+    operationType: McpCapabilityOperationType;
+    /** Optional MCP-facing argument contract for this capability. */
+    argumentMode?: McpCapabilityArgumentMode;
+    /** Optional ordered/named parameter metadata for this capability. */
+    parameters?: McpCapabilityParameter[];
+    /** Optional selector value used to disambiguate generic capabilities. */
+    scope?: McpCapabilityScope;
+    /** Whether the generic tool supports realm override for this capability. */
+    supportsRealm?: boolean;
+    /** Whether the generic tool supports paging hints for this capability. */
+    supportsPaging?: boolean;
+    /** Whether the generic tool supports includeTotal for this capability. */
+    supportsIncludeTotal?: boolean;
+    kind: McpCapabilityKind;
+    riskClass: McpCapabilityRiskClass;
+    mutating: boolean;
+    destructive: boolean;
+    /**
+     * Whether this capability has no platform-native undo once it completes.
+     * Set from {@link OperationCapabilityMeta.irreversible} when declared;
+     * absent otherwise (not inferred, unlike {@link destructive}/{@link riskClass} —
+     * there's no reliable naming-convention signal for irreversibility).
+     */
+    irreversible?: boolean;
+    /** Deployment families where this capability is functional. Defaults to `['any']`. */
+    deploymentTypes: McpDeploymentType[];
+    /**
+     * Deployment families where this capability is the preferred/optimal choice.
+     * Set from {@link OperationCapabilityMeta.preferredDeploymentTypes} when available;
+     * absent when no explicit preference has been declared.
+     */
+    preferredDeploymentTypes?: McpDeploymentType[];
+    /**
+     * Identity surface this capability operates on.
+     * Set from {@link OperationCapabilityMeta.identitySurface} when available.
+     */
+    identitySurface?: McpIdentitySurface;
+    /**
+     * Glob-style object type patterns this capability applies to.
+     * Set from {@link OperationCapabilityMeta.objectTypePatterns} when available.
+     */
+    objectTypePatterns?: string[];
+    /** Optional human-readable note surfaced in discovery and validation output. */
+    notes?: string;
+    /** Curated natural-language phrases used to retrieve this capability. */
+    semanticAliases?: string[];
+    /**
+     * A credential beyond the standard AM/IDM bearer token this capability
+     * requires. When set, the runtime verifies it's present on the dispatching
+     * Frodo instance's state before invoking the descriptor, and fails fast with
+     * an actionable error instead of letting the underlying API call 401.
+     * Set from {@link OperationCapabilityMeta.requiredCredential} when available.
+     */
+    requiredCredential?: McpRequiredCredential;
+    requiredScopes: string[];
+    /**
+     * Caller-privilege tier this capability is safe to expose to. Defaults to
+     * `'full-trust'` (see {@link McpCapabilityTrustTier}) — a conservative
+     * allow-list posture where every capability requires the maintainer to
+     * deliberately opt in a narrower tier, mirroring how {@link deploymentTypes}
+     * always resolves to at least `['any']` rather than being left unset.
+     * Set from {@link OperationCapabilityMeta.trustTier} when declared.
+     */
+    trustTier: McpCapabilityTrustTier;
+    annotations: McpToolAnnotations;
+};
+/**
+ * Controls for capability inventory generation.
+ */
+export type McpCapabilityInventoryOptions = {
+    includeTopLevelDomains?: string[];
+    excludeTopLevelDomains?: string[];
+    includeUtils?: boolean;
+};
+/**
+ * Policy model used to include or exclude capabilities before registration.
+ */
+export type McpCapabilityPolicy = {
+    name: string;
+    allowOperationTypes?: McpCapabilityOperationType[];
+    denyOperationTypes?: McpCapabilityOperationType[];
+    allowRiskClasses?: McpCapabilityRiskClass[];
+    denyRiskClasses?: McpCapabilityRiskClass[];
+    /** Statically pre-filters capabilities by {@link McpCapabilityTrustTier} at manifest-build time — see `ToolRuntime.ts`'s `assertTrustTierAllowed` for the complementary per-request dynamic check. */
+    allowTrustTiers?: McpCapabilityTrustTier[];
+    denyTrustTiers?: McpCapabilityTrustTier[];
+    allowDomains?: string[];
+    denyDomains?: string[];
+    /** Optional allow-list of capability module/id path prefixes. */
+    allowCapabilityPathPrefixes?: string[];
+    /** Optional deny-list of capability module/id path prefixes. */
+    denyCapabilityPathPrefixes?: string[];
+    includeSpecial?: boolean;
+};
+/**
+ * Built-in policy preset names recognized by the baseline MCP capability layer.
+ */
+export type McpCapabilityPolicyPresetName = 'read-only' | 'agentic' | 'standard' | 'admin';
+/**
+ * Identifies the identity data surface a capability operates on.
+ *
+ * @remarks
+ * - `managed` — IDM managed objects accessed via `openidm/managed/` (cloud + forgeops only)
+ * - `am-user` — AM realm users accessed via the AM REST API (classic only)
+ * - `connector-system` — Objects in an ICF connector system via `openidm/system/` (cloud + forgeops only)
+ * - `unknown` — Surface not classified
+ */
+export type McpIdentitySurface = 'managed' | 'am-user' | 'connector-system' | 'unknown';
+/**
+ * Identifies a credential a capability needs beyond the standard AM/IDM bearer
+ * token, which the MCP runtime should verify is present before dispatching.
+ *
+ * @remarks
+ * - `logApi` — a Log API key/secret (`state.getLogApiKey()`/`getLogApiSecret()`),
+ *   used by the Identity Cloud debug/audit log endpoints, which authenticate
+ *   with `X-API-Key`/`X-API-Secret` rather than the AM session bearer token.
+ */
+export type McpRequiredCredential = 'logApi';
+/**
+ * Explicit capability metadata entry stored in the static {@link CAPABILITY_META} map.
+ *
+ * @remarks
+ * Entries in the static map are keyed by a capability ID (exact dot-path match, e.g.
+ * `"idm.managed.countManagedObjects"`) or by a module prefix (e.g. `"idm.managed"`) that
+ * covers all capabilities whose IDs start with that prefix. Exact matches take priority
+ * over prefix matches. All fields are optional — only overrides need to be specified; the
+ * registry falls back to inferred defaults for absent fields.
+ */
+export type OperationCapabilityMeta = {
+    /**
+     * Explicit complete list of deployment types where this capability is functional.
+     * When set, overrides the default `['any']` inferred by the registry.
+     */
+    deploymentTypes?: McpDeploymentType[];
+    /**
+     * Subset of `deploymentTypes` indicating the deployment(s) where this capability
+     * is the optimal/recommended choice for the given object surface. Used by
+     * `frodo_discover` to produce routing hints for agents.
+     */
+    preferredDeploymentTypes?: McpDeploymentType[];
+    /**
+     * The identity data surface this capability operates on.
+     * Enables discovery tools to recommend the right domain for a given object type.
+     */
+    identitySurface?: McpIdentitySurface;
+    /**
+     * A credential beyond the standard AM/IDM bearer token this capability
+     * requires. See {@link McpRequiredCredential}.
+     */
+    requiredCredential?: McpRequiredCredential;
+    /**
+     * Glob-style object type patterns this capability applies to.
+     * Used by discovery to map object names (e.g. `alpha_user`) to the preferred domain.
+     * Examples: `['*_user', '*_organization', '*_application']`
+     */
+    objectTypePatterns?: string[];
+    /** Optional human-readable note surfaced in discovery tool output. */
+    notes?: string;
+    /** Curated natural-language phrases used for capability retrieval. */
+    semanticAliases?: string[];
+    /** Explicit MCP-facing argument mode override for the capability. */
+    argumentMode?: McpCapabilityArgumentMode;
+    /**
+     * Per-parameter annotation overlay, keyed by the parameter's auto-derived
+     * name (from Help.ts, falling back to name-based inference). Only fields
+     * present in {@link McpCapabilityParameterOverlay} may be set — the
+     * auto-derived parameter list (which parameters exist, their order) is
+     * always the baseline, so an entry here can annotate a real parameter but
+     * can never fabricate one, silently reorder one, or hide a signature
+     * change. Use {@link excludeParameters} to hide a parameter entirely.
+     */
+    parameterOverrides?: Record<string, McpCapabilityParameterOverlay>;
+    /**
+     * Names of auto-derived parameters to exclude from this capability's
+     * advertised parameter contract — e.g. a trailing `resultCallback` (a JS
+     * function reference an MCP JSON payload can never carry).
+     */
+    excludeParameters?: string[];
+    /** Optional selector value used to distinguish single vs bulk semantics, etc. */
+    scope?: McpCapabilityScope;
+    /** Whether the capability supports MCP realm override controls. */
+    supportsRealm?: boolean;
+    /** Whether the capability supports MCP paging controls. */
+    supportsPaging?: boolean;
+    /** Whether the capability supports MCP includeTotal hints. */
+    supportsIncludeTotal?: boolean;
+    /**
+     * Explicit operation-type override for capabilities whose method name doesn't
+     * follow the CRUD naming convention `inferOperationType` relies on (e.g. `fetch`,
+     * `tail`). When set, this wins over naming-convention inference and also drives
+     * the derived `kind` (`'special'` iff `operationType === 'special'`).
+     */
+    operationType?: McpCapabilityOperationType;
+    /**
+     * Explicit object-type override for capabilities whose method name doesn't carry
+     * an inferable object-type suffix (e.g. `fetch` → `LogEvent`). When set, this wins
+     * over naming-convention inference.
+     */
+    objectType?: string;
+    /**
+     * Explicit mutating override. Naming-convention inference only recognizes
+     * `create`/`update`/`delete`/`import` as mutating, so any capability that writes
+     * state under a different verb (including one classified `operationType: 'special'`)
+     * needs this set explicitly rather than relying on the permissive `false` default.
+     */
+    mutating?: boolean;
+    /**
+     * Explicit destructive-hint override, analogous to {@link mutating}.
+     */
+    destructive?: boolean;
+    /**
+     * Marks a capability as having no platform-native undo once it completes —
+     * distinct from {@link riskClass}, which describes blast radius. An
+     * operation can be `riskClass: 'critical'` without being irreversible (a
+     * schema-property delete can be restored from a prior export) or
+     * irreversible without being otherwise unusual (an IDM feature install is
+     * a single, deliberate, low-frequency action, not "high blast radius" in
+     * the everyday sense, but Ping's own docs state that uninstalling
+     * requires contacting support and rolling back the tenant). Pure
+     * discoverability metadata — surfaced on the descriptor for callers and
+     * policy designers to see (like {@link destructive}), not itself wired
+     * into policy-tier filtering, since capabilities marked irreversible so
+     * far are already `riskClass: 'critical'` and therefore already excluded
+     * from every non-admin preset by the existing risk-class filter.
+     */
+    irreversible?: boolean;
+    /**
+     * Explicit risk-class override. Naming-convention inference only escalates risk
+     * for `delete`/`import`/`export`/`create`/`update` and secret-ish keyword matches,
+     * so non-CRUD capabilities that warrant elevated caution need this set explicitly.
+     */
+    riskClass?: McpCapabilityRiskClass;
+    /**
+     * Explicit caller-privilege-tier override. See {@link McpCapabilityTrustTier}.
+     * The registry defaults every capability to `'full-trust'` when absent —
+     * this is the enforceable replacement for an "Admin-only" free-text note
+     * in {@link notes} (keep the prose too; it explains *why*, this field says
+     * *what's enforced*).
+     */
+    trustTier?: McpCapabilityTrustTier;
+    /**
+     * When `true`, this capability is dropped from the inventory entirely instead of
+     * becoming a descriptor. Intended for methods that make no tenant/API call (pure
+     * local helpers) and therefore aren't remote operations at all.
+     */
+    excluded?: boolean;
+};
+//# sourceMappingURL=CapabilityTypes.d.ts.map

package/types/mcp/CapabilityTypes.d.ts.map

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

package/types/mcp/DiscoveryHydration.d.ts

@@ -0,0 +1,21 @@
+import { Frodo } from '../lib/FrodoLib';
+import { McpCatalogHydrationStatus, McpDiscoveryContext, McpDiscoveryTarget } from './ToolManifest';
+export type McpDiscoveryHydrationCatalog = 'managed-object-types' | 'config-entity-ids';
+export type McpDiscoveryHydrationEvent = {
+    catalog: McpDiscoveryHydrationCatalog;
+    status: McpCatalogHydrationStatus;
+    count: number;
+    error?: unknown;
+};
+export type McpDiscoveryHydrationOptions = {
+    frodoInstance?: Frodo;
+    timeoutMs?: number;
+    activeTarget?: McpDiscoveryTarget;
+    onEvent?: (event: McpDiscoveryHydrationEvent) => void;
+};
+/**
+ * Hydrates tenant catalogs used by MCP discovery and semantic skill matching.
+ * Catalog failures are isolated so service construction can continue.
+ */
+export declare function hydrateMcpDiscoveryContext(options?: McpDiscoveryHydrationOptions): Promise<McpDiscoveryContext>;
+//# sourceMappingURL=DiscoveryHydration.d.ts.map

package/types/mcp/DiscoveryHydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiscoveryHydration.d.ts","sourceRoot":"","sources":["../../src/mcp/DiscoveryHydration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAS,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,MAAM,4BAA4B,GACtC,sBAAsB,GAAG,mBAAmB,CAAC;AAE/C,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,4BAA4B,CAAC;IACtC,MAAM,EAAE,yBAAyB,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;CACvD,CAAC;AAOF;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,mBAAmB,CAAC,CAoD9B"}

package/types/mcp/DocsContext.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Resolves which Ping documentation docset (and version, where applicable) an
+ * MCP session's active deployment should be pointed at.
+ *
+ * @remarks
+ * Ping publishes every docs page as a Markdown alternate (swap `.html` for
+ * `.md`, or send `Accept: text/markdown`) and a per-product discovery index at
+ * `docs.pingidentity.com/{product}/llms.txt` — a flat title-to-URL list an
+ * agent can match a question against directly. That fetch-and-match mechanism
+ * is generic and needs no logic of its own; what does need logic is picking
+ * the right `{product}` and, for versioned products, the right version —
+ * getting either wrong doesn't fail loudly, it silently serves plausible but
+ * wrong documentation:
+ *
+ * - Advanced Identity Cloud (`cloud`) is continuously deployed and reports
+ *   internal component versions (e.g. an AM version) that run ahead of any
+ *   public release. Treating that as a docs version would produce a 404 at
+ *   best. The correct behavior is to ignore it entirely and always resolve to
+ *   the unversioned `pingoneaic` docset.
+ * - Self-managed AM (`classic`) is genuinely versioned, but
+ *   `docs.pingidentity.com/pingam/llms.txt` is itself unversioned — it only
+ *   ever indexes whichever version is currently latest on the docs site, not
+ *   necessarily the one this deployment runs. Verified live: older
+ *   version-pinned page trees stay reachable at their own path even once
+ *   superseded (e.g. `.../pingam/7.5/...` resolves cleanly with `8.1`
+ *   current), so the fix is to rewrite the version segment in a matched page
+ *   URL to the deployment's actual version rather than trust whatever the
+ *   index links to.
+ * - ForgeOps (`forgeops`) runs AM and IDM as separately versioned components,
+ *   each with its own docset (`pingam`, `pingidm`), so a single docs target
+ *   can't be resolved without knowing which component a given question is
+ *   about. Rather than guess, `resolveDocsContext` returns both components'
+ *   docs targets plus `domainRouting` — a lookup from frodo's own top-level
+ *   capability domain (the `frodo.<domain>...` namespace a skill's `domain`
+ *   field already reports, e.g. `'realm'`, `'idm'`, `'authn'`) to which
+ *   component owns it, built from the actual API generator (`generateAmApi`
+ *   vs `generateIdmApi`) each domain's operations call under the hood.
+ */
+import { McpDeploymentType } from './CapabilityTypes';
+/** Docs product slugs this resolver knows about. */
+export type McpDocsProduct = 'pingoneaic' | 'pingam' | 'pingidm';
+/**
+ * A resolved docs target: which product, whether it's versioned, and (for
+ * versioned products) which version — plus the discovery index URL and
+ * guidance on how to use it correctly.
+ */
+export type McpDocsContext = {
+    product: McpDocsProduct;
+    versioned: boolean;
+    /** Present only when `versioned` is true and a version could be determined. */
+    version?: string;
+    /** Always the unversioned per-product discovery index — never version-scoped. */
+    llmsTxtUrl: string;
+    /** Usage guidance specific to this product/version combination. */
+    notes: string;
+};
+/** Returned when a docs target cannot be resolved. */
+export type McpDocsContextUnresolved = {
+    product: null;
+    unresolved: true;
+    reason: string;
+};
+/**
+ * Which product's docs own a given top-level frodo capability domain (the
+ * `frodo.<domain>...` namespace, e.g. `'realm'`, `'idm'`, `'authn'`):
+ *
+ * - `'am'` / `'idm'`: operations under this domain call that component's API
+ *   exclusively (verified against the actual `generateAmApi`/`generateIdmApi`
+ *   call sites, not inferred from the domain's name — several domain names
+ *   are misleading, e.g. `user` is AM's identity-store users REST resource,
+ *   not IDM managed users, which live under `idm.managed` instead).
+ * - `'both'`: the domain spans both components (e.g. whole-tenant config
+ *   export/import), so a single product can't be chosen for it.
+ * - `'cloud-only'`: an Advanced Identity Cloud SaaS feature with no ForgeOps
+ *   equivalent at all (ESVs, IGA, promotion, service accounts, ...).
+ * - `'n/a'`: an internal/client-side helper with no corresponding product
+ *   documentation (HTTP client factory, local utility functions, connection
+ *   profile and token cache management).
+ */
+export type McpDocsDomainProduct = 'am' | 'idm' | 'both' | 'cloud-only' | 'n/a';
+/**
+ * Verified domain → product mapping for every top-level frodo capability
+ * domain, derived from which API generator (`generateAmApi`/
+ * `generateAmAuthApi`/`generateOauth2Api` vs `generateIdmApi`) that domain's
+ * operations call. Domains not listed here default to `'both'` in
+ * {@link classifyDomainProduct} — an unclassified domain should prompt
+ * checking both docsets rather than silently guessing one.
+ */
+export declare const FORGEOPS_DOMAIN_PRODUCT_MAP: Record<string, McpDocsDomainProduct>;
+/**
+ * Classifies a top-level frodo capability domain by which product's docs own
+ * it. Falls back to `'both'` for anything not in
+ * {@link FORGEOPS_DOMAIN_PRODUCT_MAP} — an unrecognized domain should never
+ * be silently routed to one product's docs.
+ */
+export declare function classifyDomainProduct(domain: string): McpDocsDomainProduct;
+/** A resolved forgeops docs target: independently versioned AM and IDM docsets, plus domain routing. */
+export type McpDocsContextForgeops = {
+    deploymentType: 'forgeops';
+    am: McpDocsContext | McpDocsContextUnresolved;
+    idm: McpDocsContext | McpDocsContextUnresolved;
+    domainRouting: Record<string, McpDocsDomainProduct>;
+    notes: string;
+};
+/** @see extractDocsMajorMinor */
+export declare function parseAmDocsVersion(rawAmVersion: string | undefined): string | undefined;
+/** @see extractDocsMajorMinor */
+export declare function parseIdmDocsVersion(rawIdmVersion: string | undefined): string | undefined;
+/**
+ * Resolves the docs target for a deployment, given its type and (for
+ * self-managed AM/IDM) its raw version string(s).
+ *
+ * @param deploymentType Active deployment type, or `undefined` if unknown.
+ * @param rawAmVersion Raw value from `state.getAmVersion()`, consulted for
+ *   `classic` and `forgeops` deployments.
+ * @param rawIdmVersion Raw value from `state.getIdmVersion()`, consulted only
+ *   for `forgeops` deployments (classic has no IDM component; cloud ignores
+ *   component versions by design).
+ * @returns A resolved docs context, or an explicit unresolved result — never
+ *   a guess.
+ */
+export declare function resolveDocsContext(deploymentType: McpDeploymentType | undefined, rawAmVersion?: string, rawIdmVersion?: string): McpDocsContext | McpDocsContextUnresolved | McpDocsContextForgeops;
+//# sourceMappingURL=DocsContext.d.ts.map

package/types/mcp/DocsContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsContext.d.ts","sourceRoot":"","sources":["../../src/mcp/DocsContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,IAAI,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,YAAY,GAAG,KAAK,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAgC1E,CAAC;AAEJ;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAE1E;AAED,wGAAwG;AACxG,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,EAAE,UAAU,CAAC;IAC3B,EAAE,EAAE,cAAc,GAAG,wBAAwB,CAAC;IAC9C,GAAG,EAAE,cAAc,GAAG,wBAAwB,CAAC;IAC/C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACpD,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AA6BF,iCAAiC;AACjC,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAEpB;AAED,iCAAiC;AACjC,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAEpB;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,iBAAiB,GAAG,SAAS,EAC7C,YAAY,CAAC,EAAE,MAAM,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,cAAc,GAAG,wBAAwB,GAAG,sBAAsB,CAyCpE"}

package/types/mcp/McpService.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Composes MCP capability inventory, policy filtering, manifest generation, and
+ * runtime execution into one launch-ready service object.
+ *
+ * @remarks
+ * This module is intentionally transport-agnostic. It prepares all data and
+ * execution hooks required by both stdio and HTTP MCP transports, while leaving
+ * actual transport wiring to higher layers.
+ */
+import { Frodo } from '../lib/FrodoLib';
+import { McpCapabilityDescriptor, McpCapabilityInventoryOptions, McpCapabilityPolicy, McpCapabilityPolicyPresetName } from './CapabilityTypes';
+import { McpProfileName } from './ProfileRegistry';
+import { McpDiscoveryContext, McpToolManifest } from './ToolManifest';
+import { McpToolExecutionRequest, McpToolExecutionResult, McpToolRuntime, McpToolRuntimeOptions } from './ToolRuntime';
+/**
+ * Lightweight tool metadata surface suitable for MCP tool registration calls.
+ */
+export type McpServiceToolDefinition = {
+    /** Stable tool name exposed to MCP clients. */
+    name: string;
+    /** Human-readable tool description. */
+    description: string;
+    /** Optional MCP annotation hints for tool selection behavior. */
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+};
+/**
+ * Options for constructing an MCP service instance.
+ */
+export type McpServiceOptions = {
+    /**
+     * Frodo instance to inspect and use as runtime factory root.
+     * Defaults to the library singleton.
+     */
+    frodoInstance?: Frodo;
+    /** Optional profile name to constrain the active capability universe. */
+    profileName?: McpProfileName;
+    /** Optional inventory-scoping controls (domains, utils visibility). */
+    inventoryOptions?: McpCapabilityInventoryOptions;
+    /** Built-in policy preset to start from. Defaults to `standard`. */
+    policyPreset?: McpCapabilityPolicyPresetName;
+    /** Optional override fields merged on top of the selected preset. */
+    policyOverride?: Partial<McpCapabilityPolicy>;
+    /** Optional runtime customization hooks. */
+    runtimeOptions?: Omit<McpToolRuntimeOptions, 'frodoRoot' | 'managedObjectTypes' | 'managedObjectHydrationStatus' | 'configEntityIds' | 'configEntityHydrationStatus'>;
+    /** Service-local tenant metadata used only for discovery and search. */
+    discoveryContext?: McpDiscoveryContext;
+};
+/**
+ * Fully composed MCP service object.
+ */
+export type McpService = {
+    /** Effective capability policy after preset + overrides are merged. */
+    policy: McpCapabilityPolicy;
+    /** Policy-filtered capabilities backing the current service. */
+    capabilities: McpCapabilityDescriptor[];
+    /** Reduced manifest consumed by transport registration code. */
+    manifest: McpToolManifest;
+    /** Runtime executor for tool calls. */
+    runtime: McpToolRuntime;
+    /**
+     * Returns tool definition metadata for transport registration.
+     *
+     * @returns Flattened canonical tool list plus discovery tool.
+     */
+    listTools(): McpServiceToolDefinition[];
+    /**
+     * Executes one tool request.
+     *
+     * @param request Tool execution request envelope.
+     * @returns Tool execution result envelope.
+     */
+    executeTool(request: McpToolExecutionRequest): Promise<McpToolExecutionResult>;
+};
+/**
+ * Merges a built-in policy preset with caller-provided overrides.
+ *
+ * @param presetName Built-in preset key.
+ * @param override Optional override object.
+ * @returns Effective policy object.
+ */
+export declare function composeCapabilityPolicy(presetName: McpCapabilityPolicyPresetName, override?: Partial<McpCapabilityPolicy>): McpCapabilityPolicy;
+/**
+ * Builds an MCP service from Frodo capabilities and policy configuration.
+ *
+ * @param options Service construction options.
+ * @returns Composed service object with manifest and runtime hooks.
+ */
+export declare function createMcpService(options?: McpServiceOptions): McpService;
+//# sourceMappingURL=McpService.d.ts.map

package/types/mcp/McpService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpService.d.ts","sourceRoot":"","sources":["../../src/mcp/McpService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAS,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,mBAAmB,EACnB,6BAA6B,EAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAA8B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAEL,mBAAmB,EACnB,eAAe,EAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,yEAAyE;IACzE,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,6BAA6B,CAAC;IACjD,oEAAoE;IACpE,YAAY,CAAC,EAAE,6BAA6B,CAAC;IAC7C,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,4CAA4C;IAC5C,cAAc,CAAC,EAAE,IAAI,CACnB,qBAAqB,EACnB,WAAW,GACX,oBAAoB,GACpB,8BAA8B,GAC9B,iBAAiB,GACjB,6BAA6B,CAChC,CAAC;IACF,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,uEAAuE;IACvE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,gEAAgE;IAChE,YAAY,EAAE,uBAAuB,EAAE,CAAC;IACxC,gEAAgE;IAChE,QAAQ,EAAE,eAAe,CAAC;IAC1B,uCAAuC;IACvC,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,SAAS,IAAI,wBAAwB,EAAE,CAAC;IACxC;;;;;OAKG;IACH,WAAW,CACT,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,6BAA6B,EACzC,QAAQ,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACtC,mBAAmB,CAOrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CA4E5E"}