@agentcash/discovery 0.1.1 → 0.1.2

package/README.md

@@ -98,6 +98,37 @@ const harness = await auditContextHarness({
 });
 ```
 
+## MCP Adapter Contract
+
+This section is the canonical contract for MCP-facing discovery adapters:
+
+- `discoverForMcp(options)` for L2 resources + L4 guidance policy projection.
+- `inspectEndpointForMcp(options)` for L3 OpenAPI advisory projection.
+
+`discoverForMcp` guarantees:
+
+- `guidanceAvailable` is always present.
+- `guidanceTokens` is present when guidance exists.
+- `guidance` is included when `includeGuidance=true`, excluded when
+  `includeGuidance=false`, and auto-included under the token threshold when not
+  specified.
+
+`inspectEndpointForMcp` guarantees:
+
+- Spec-derived HTTP methods for the selected endpoint path.
+- Per-method advisory data: summary, estimated price, protocols, auth mode, and
+  input schema.
+
+Ownership boundary:
+
+- `@agentcash/discovery` owns discovery/advisory contracts.
+- Runtime probe truth (live 402 parsing/payment option extraction/divergence)
+  belongs to the `agentcash` MCP package.
+
+Reference integration boundary:
+
+- `https://github.com/Merit-Systems/agentcash/blob/main/packages/external/mcp/docs/discovery-boundary.md`
+
 ## Discovery Waterfall
 
 Default order:

package/dist/cli.cjs

@@ -637,7 +637,7 @@ function renderJson(run, options) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.1".includes("-mmm");
+var isMmmEnabled = () => "0.1.2".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];

package/dist/cli.js

@@ -611,7 +611,7 @@ function renderJson(run, options) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.1".includes("-mmm");
+var isMmmEnabled = () => "0.1.2".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];

package/dist/index.cjs

@@ -30,7 +30,9 @@ __export(index_exports, {
   defaultHarnessProbeCandidates: () => defaultHarnessProbeCandidates,
   discover: () => discover,
   discoverDetailed: () => discoverDetailed,
+  discoverForMcp: () => discoverForMcp,
   getHarnessClientProfile: () => getHarnessClientProfile,
+  inspectEndpointForMcp: () => inspectEndpointForMcp,
   listHarnessClientProfiles: () => listHarnessClientProfiles
 });
 module.exports = __toCommonJS(index_exports);
@@ -49,7 +51,7 @@ var STRICT_ESCALATION_CODES = [
 ];
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.1".includes("-mmm");
+var isMmmEnabled = () => "0.1.2".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -1437,6 +1439,396 @@ async function runDiscovery({
   };
 }
 
+// src/adapters/mcp.ts
+var DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS = 1e3;
+var OPENAPI_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+];
+function isRecord4(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+function formatPriceHintFromResource(resource) {
+  const pricing = resource.pricing;
+  if (pricing) {
+    if (pricing.pricingMode === "fixed" && pricing.price) {
+      return pricing.price.startsWith("$") ? pricing.price : `$${pricing.price}`;
+    }
+    if (pricing.pricingMode === "range" && pricing.minPrice && pricing.maxPrice) {
+      const min = pricing.minPrice.startsWith("$") ? pricing.minPrice : `$${pricing.minPrice}`;
+      const max = pricing.maxPrice.startsWith("$") ? pricing.maxPrice : `$${pricing.maxPrice}`;
+      return `${min}-${max}`;
+    }
+  }
+  if (!resource.priceHint) return void 0;
+  const hint = resource.priceHint.trim();
+  if (hint.length === 0) return void 0;
+  if (hint.startsWith("$")) return hint;
+  if (hint.includes("-")) {
+    const [min, max] = hint.split("-", 2).map((part) => part.trim());
+    if (min && max) return `$${min}-$${max}`;
+  }
+  return `$${hint}`;
+}
+function deriveMcpAuthMode(resource) {
+  if (!resource) return void 0;
+  const hint = resource.authHint;
+  if (hint === "paid" || hint === "siwx" || hint === "apiKey" || hint === "unprotected") {
+    return hint;
+  }
+  return void 0;
+}
+function inferFailureCause(warnings) {
+  const openapiWarnings = warnings.filter((w) => w.stage === "openapi");
+  const parseWarning = openapiWarnings.find(
+    (w) => w.code === "PARSE_FAILED" || w.code === "OPENAPI_TOP_LEVEL_INVALID" || w.code === "OPENAPI_OPERATION_INVALID" || w.code === "OPENAPI_PRICING_INVALID"
+  );
+  if (parseWarning) {
+    return { cause: "parse", message: parseWarning.message };
+  }
+  const fetchWarning = openapiWarnings.find((w) => w.code === "FETCH_FAILED");
+  if (fetchWarning) {
+    const msg = fetchWarning.message.toLowerCase();
+    if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("abort")) {
+      return { cause: "timeout", message: fetchWarning.message };
+    }
+    return { cause: "network", message: fetchWarning.message };
+  }
+  return { cause: "not_found" };
+}
+function getOpenApiInfo(document) {
+  if (!isRecord4(document) || !isRecord4(document.info)) return void 0;
+  if (typeof document.info.title !== "string") return void 0;
+  return {
+    title: document.info.title,
+    ...typeof document.info.version === "string" ? { version: document.info.version } : {},
+    ...typeof document.info.description === "string" ? { description: document.info.description } : {}
+  };
+}
+function getGuidanceUrl(result) {
+  const fromTrace = result.trace.find((entry) => entry.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromTrace) return fromTrace;
+  const fromResource = result.resources.find((resource) => resource.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromResource) return fromResource;
+  return void 0;
+}
+async function resolveGuidance(options) {
+  let guidanceText = typeof options.result.rawSources?.llmsTxt === "string" ? options.result.rawSources.llmsTxt : void 0;
+  if (!guidanceText) {
+    const guidanceUrl = getGuidanceUrl(options.result) ?? `${options.result.origin}/llms.txt`;
+    const fetcher = options.fetcher ?? fetch;
+    try {
+      const response = await fetcher(guidanceUrl, {
+        method: "GET",
+        headers: { Accept: "text/plain", ...options.headers },
+        signal: options.signal
+      });
+      if (response.ok) guidanceText = await response.text();
+    } catch {
+    }
+  }
+  if (!guidanceText) {
+    return { guidanceAvailable: false };
+  }
+  const guidanceTokens = estimateTokenCount(guidanceText);
+  const threshold = options.guidanceAutoIncludeMaxTokens ?? DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS;
+  const shouldInclude = options.includeGuidance === true || options.includeGuidance == null && guidanceTokens <= threshold;
+  return {
+    guidanceAvailable: true,
+    guidanceTokens,
+    ...shouldInclude ? { guidance: guidanceText } : {}
+  };
+}
+function extractPathsDocument(document) {
+  if (!isRecord4(document)) return void 0;
+  if (!isRecord4(document.paths)) return void 0;
+  return document.paths;
+}
+function findMatchingOpenApiPath(paths, targetPath) {
+  const exact = paths[targetPath];
+  if (isRecord4(exact)) return { matchedPath: targetPath, pathItem: exact };
+  for (const [specPath, entry] of Object.entries(paths)) {
+    if (!isRecord4(entry)) continue;
+    const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
+    const regex = new RegExp(`^${pattern}$`);
+    if (regex.test(targetPath)) {
+      return { matchedPath: specPath, pathItem: entry };
+    }
+  }
+  return null;
+}
+function resolveRef(document, ref, seen) {
+  if (!ref.startsWith("#/")) return void 0;
+  if (seen.has(ref)) return { $circular: ref };
+  seen.add(ref);
+  const parts = ref.slice(2).split("/");
+  let current = document;
+  for (const part of parts) {
+    if (!isRecord4(current)) return void 0;
+    current = current[part];
+    if (current === void 0) return void 0;
+  }
+  if (isRecord4(current)) return resolveRefs(document, current, seen);
+  return current;
+}
+function resolveRefs(document, obj, seen, depth = 0) {
+  if (depth > 4) return obj;
+  const resolved = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$ref" && typeof value === "string") {
+      const deref = resolveRef(document, value, seen);
+      if (isRecord4(deref)) {
+        Object.assign(resolved, deref);
+      } else {
+        resolved[key] = value;
+      }
+      continue;
+    }
+    if (isRecord4(value)) {
+      resolved[key] = resolveRefs(document, value, seen, depth + 1);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      resolved[key] = value.map(
+        (item) => isRecord4(item) ? resolveRefs(document, item, seen, depth + 1) : item
+      );
+      continue;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+function extractRequestBodySchema(operationSchema) {
+  const requestBody = operationSchema.requestBody;
+  if (!isRecord4(requestBody)) return void 0;
+  const content = requestBody.content;
+  if (!isRecord4(content)) return void 0;
+  const jsonMediaType = content["application/json"];
+  if (isRecord4(jsonMediaType) && isRecord4(jsonMediaType.schema)) {
+    return jsonMediaType.schema;
+  }
+  for (const mediaType of Object.values(content)) {
+    if (isRecord4(mediaType) && isRecord4(mediaType.schema)) {
+      return mediaType.schema;
+    }
+  }
+  return void 0;
+}
+function extractParameters(operationSchema) {
+  const params = operationSchema.parameters;
+  if (!Array.isArray(params)) return [];
+  return params.filter((value) => isRecord4(value));
+}
+function extractInputSchema(operationSchema) {
+  const requestBody = extractRequestBodySchema(operationSchema);
+  const parameters = extractParameters(operationSchema);
+  if (!requestBody && parameters.length === 0) return void 0;
+  if (requestBody && parameters.length === 0) return requestBody;
+  return {
+    ...requestBody ? { requestBody } : {},
+    ...parameters.length > 0 ? { parameters } : {}
+  };
+}
+function parseOperationPrice(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord4(paymentInfo)) return void 0;
+  const fixed = toFiniteNumber(paymentInfo.price);
+  if (fixed != null) return `$${String(fixed)}`;
+  const min = toFiniteNumber(paymentInfo.minPrice);
+  const max = toFiniteNumber(paymentInfo.maxPrice);
+  if (min != null && max != null) return `$${String(min)}-$${String(max)}`;
+  return void 0;
+}
+function parseOperationProtocols(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord4(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
+  const protocols = paymentInfo.protocols.filter(
+    (protocol) => typeof protocol === "string" && protocol.length > 0
+  );
+  return protocols.length > 0 ? protocols : void 0;
+}
+function parseOperationAuthMode(operation) {
+  const authExtension = operation["x-agentcash-auth"];
+  if (isRecord4(authExtension)) {
+    const mode = authExtension.mode;
+    if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
+      return mode;
+    }
+  }
+  if (isRecord4(operation["x-payment-info"])) return "paid";
+  return void 0;
+}
+function createResourceMap(result) {
+  const map = /* @__PURE__ */ new Map();
+  for (const resource of result.resources) {
+    map.set(resource.resourceKey, resource);
+  }
+  return map;
+}
+function toMcpEndpointSummary(resource) {
+  const method = parseMethod(resource.method);
+  if (!method) return void 0;
+  const price = formatPriceHintFromResource(resource);
+  const authMode = deriveMcpAuthMode(resource);
+  return {
+    path: resource.path,
+    method,
+    summary: resource.summary ?? `${method} ${resource.path}`,
+    ...price ? { price } : {},
+    ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+    ...authMode ? { authMode } : {}
+  };
+}
+async function discoverForMcp(options) {
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  if (result.resources.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin: result.origin,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  const source = result.selectedStage ?? "openapi";
+  const endpoints = result.resources.map(toMcpEndpointSummary).filter((endpoint) => endpoint != null).sort((a, b) => {
+    if (a.path !== b.path) return a.path.localeCompare(b.path);
+    return a.method.localeCompare(b.method);
+  });
+  const guidance = await resolveGuidance({
+    result,
+    includeGuidance: options.includeGuidance,
+    guidanceAutoIncludeMaxTokens: options.guidanceAutoIncludeMaxTokens,
+    fetcher: options.fetcher,
+    headers: options.headers,
+    signal: options.signal
+  });
+  return {
+    found: true,
+    origin: result.origin,
+    source,
+    ...getOpenApiInfo(result.rawSources?.openapi) ? { info: getOpenApiInfo(result.rawSources?.openapi) } : {},
+    ...guidance,
+    endpoints,
+    warnings: result.warnings
+  };
+}
+async function inspectEndpointForMcp(options) {
+  const endpoint = new URL(options.endpointUrl);
+  const origin = normalizeOrigin(endpoint.origin);
+  const path = normalizePath(endpoint.pathname || "/");
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  const document = result.rawSources?.openapi;
+  const paths = extractPathsDocument(document);
+  const resourceMap = createResourceMap(result);
+  const advisories = {};
+  const specMethods = [];
+  if (paths) {
+    const matched = findMatchingOpenApiPath(paths, path);
+    if (matched) {
+      for (const candidate of OPENAPI_METHODS) {
+        const operation = matched.pathItem[candidate.toLowerCase()];
+        if (!isRecord4(operation) || !isRecord4(document)) continue;
+        specMethods.push(candidate);
+        const resolvedOperation = resolveRefs(document, operation, /* @__PURE__ */ new Set());
+        const resource = resourceMap.get(toResourceKey(origin, candidate, matched.matchedPath));
+        const formattedPrice = resource ? formatPriceHintFromResource(resource) : void 0;
+        const operationSummary = typeof resolvedOperation.summary === "string" ? resolvedOperation.summary : typeof resolvedOperation.description === "string" ? resolvedOperation.description : void 0;
+        const operationPrice = parseOperationPrice(resolvedOperation);
+        const operationProtocols = parseOperationProtocols(resolvedOperation);
+        const operationAuthMode = parseOperationAuthMode(resolvedOperation);
+        const inputSchema = extractInputSchema(resolvedOperation);
+        advisories[candidate] = {
+          method: candidate,
+          ...resource?.summary || operationSummary ? {
+            summary: resource?.summary ?? operationSummary
+          } : {},
+          ...formattedPrice || operationPrice ? {
+            estimatedPrice: formattedPrice ?? operationPrice
+          } : {},
+          ...resource?.protocolHints?.length || operationProtocols ? {
+            protocols: resource?.protocolHints ?? operationProtocols
+          } : {},
+          ...deriveMcpAuthMode(resource) || operationAuthMode ? {
+            authMode: deriveMcpAuthMode(resource) ?? operationAuthMode
+          } : {},
+          ...inputSchema ? { inputSchema } : {},
+          operationSchema: resolvedOperation
+        };
+      }
+    }
+  }
+  if (specMethods.length === 0) {
+    for (const method of OPENAPI_METHODS) {
+      const resource = resourceMap.get(toResourceKey(origin, method, path));
+      if (!resource) continue;
+      specMethods.push(method);
+      const formattedPrice = formatPriceHintFromResource(resource);
+      advisories[method] = {
+        method,
+        ...resource.summary ? { summary: resource.summary } : {},
+        ...formattedPrice ? { estimatedPrice: formattedPrice } : {},
+        ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+        ...deriveMcpAuthMode(resource) ? { authMode: deriveMcpAuthMode(resource) } : {}
+      };
+    }
+  }
+  if (specMethods.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin,
+      path,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  return {
+    found: true,
+    origin,
+    path,
+    specMethods,
+    advisories,
+    warnings: result.warnings
+  };
+}
+
 // src/harness.ts
 var INTENT_TRIGGERS = ["x402", "mpp", "pay for", "micropayment", "agentic commerce"];
 var CLIENT_PROFILES = {
@@ -1696,6 +2088,8 @@ async function discoverDetailed(options) {
   defaultHarnessProbeCandidates,
   discover,
   discoverDetailed,
+  discoverForMcp,
   getHarnessClientProfile,
+  inspectEndpointForMcp,
   listHarnessClientProfiles
 });

package/dist/index.d.cts

@@ -94,6 +94,88 @@ interface DiscoverDetailedOptions extends DiscoverOptions {
     includeInteropMpp?: boolean;
 }
 
+type McpFailureCause = 'not_found' | 'network' | 'timeout' | 'parse';
+type McpAuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface McpOpenApiInfo {
+    title: string;
+    version?: string;
+    description?: string;
+}
+interface McpEndpointSummary {
+    path: string;
+    method: HttpMethod;
+    summary: string;
+    price?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+}
+interface McpGuidance {
+    guidanceAvailable: boolean;
+    guidanceTokens?: number;
+    guidance?: string;
+}
+interface DiscoverForMcpOptions {
+    target: string;
+    includeGuidance?: boolean;
+    guidanceAutoIncludeMaxTokens?: number;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface DiscoverForMcpSuccess extends McpGuidance {
+    found: true;
+    origin: string;
+    source: string;
+    info?: McpOpenApiInfo;
+    endpoints: McpEndpointSummary[];
+    warnings: DiscoveryWarning[];
+}
+interface DiscoverForMcpFailure {
+    found: false;
+    origin: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type DiscoverForMcpResult = DiscoverForMcpSuccess | DiscoverForMcpFailure;
+interface EndpointMethodAdvisory {
+    method: HttpMethod;
+    summary?: string;
+    estimatedPrice?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+    inputSchema?: Record<string, unknown>;
+    operationSchema?: Record<string, unknown>;
+}
+interface InspectEndpointForMcpOptions {
+    target: string;
+    endpointUrl: string;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface InspectEndpointForMcpSuccess {
+    found: true;
+    origin: string;
+    path: string;
+    specMethods: HttpMethod[];
+    advisories: Partial<Record<HttpMethod, EndpointMethodAdvisory>>;
+    warnings: DiscoveryWarning[];
+}
+interface InspectEndpointForMcpFailure {
+    found: false;
+    origin: string;
+    path: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type InspectEndpointForMcpResult = InspectEndpointForMcpSuccess | InspectEndpointForMcpFailure;
+declare function discoverForMcp(options: DiscoverForMcpOptions): Promise<DiscoverForMcpResult>;
+declare function inspectEndpointForMcp(options: InspectEndpointForMcpOptions): Promise<InspectEndpointForMcpResult>;
+
 declare const UPGRADE_WARNING_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "OPENAPI_AUTH_MODE_MISSING", "OPENAPI_TOP_LEVEL_INVALID"];
 declare function computeUpgradeSignal(warnings: DiscoveryWarning[]): {
     upgradeSuggested: boolean;
@@ -207,4 +289,4 @@ declare function defaultHarnessProbeCandidates(report: ContextHarnessReport): Pr
 declare function discover(options: DiscoverOptions): Promise<DiscoverResult>;
 declare function discoverDetailed(options: DiscoverDetailedOptions): Promise<DiscoverDetailedResult>;
 
-export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, getHarnessClientProfile, listHarnessClientProfiles };
+export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverForMcpFailure, type DiscoverForMcpOptions, type DiscoverForMcpResult, type DiscoverForMcpSuccess, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type EndpointMethodAdvisory, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type InspectEndpointForMcpFailure, type InspectEndpointForMcpOptions, type InspectEndpointForMcpResult, type InspectEndpointForMcpSuccess, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, discoverForMcp, getHarnessClientProfile, inspectEndpointForMcp, listHarnessClientProfiles };

package/dist/index.d.ts

@@ -94,6 +94,88 @@ interface DiscoverDetailedOptions extends DiscoverOptions {
     includeInteropMpp?: boolean;
 }
 
+type McpFailureCause = 'not_found' | 'network' | 'timeout' | 'parse';
+type McpAuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface McpOpenApiInfo {
+    title: string;
+    version?: string;
+    description?: string;
+}
+interface McpEndpointSummary {
+    path: string;
+    method: HttpMethod;
+    summary: string;
+    price?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+}
+interface McpGuidance {
+    guidanceAvailable: boolean;
+    guidanceTokens?: number;
+    guidance?: string;
+}
+interface DiscoverForMcpOptions {
+    target: string;
+    includeGuidance?: boolean;
+    guidanceAutoIncludeMaxTokens?: number;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface DiscoverForMcpSuccess extends McpGuidance {
+    found: true;
+    origin: string;
+    source: string;
+    info?: McpOpenApiInfo;
+    endpoints: McpEndpointSummary[];
+    warnings: DiscoveryWarning[];
+}
+interface DiscoverForMcpFailure {
+    found: false;
+    origin: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type DiscoverForMcpResult = DiscoverForMcpSuccess | DiscoverForMcpFailure;
+interface EndpointMethodAdvisory {
+    method: HttpMethod;
+    summary?: string;
+    estimatedPrice?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+    inputSchema?: Record<string, unknown>;
+    operationSchema?: Record<string, unknown>;
+}
+interface InspectEndpointForMcpOptions {
+    target: string;
+    endpointUrl: string;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface InspectEndpointForMcpSuccess {
+    found: true;
+    origin: string;
+    path: string;
+    specMethods: HttpMethod[];
+    advisories: Partial<Record<HttpMethod, EndpointMethodAdvisory>>;
+    warnings: DiscoveryWarning[];
+}
+interface InspectEndpointForMcpFailure {
+    found: false;
+    origin: string;
+    path: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type InspectEndpointForMcpResult = InspectEndpointForMcpSuccess | InspectEndpointForMcpFailure;
+declare function discoverForMcp(options: DiscoverForMcpOptions): Promise<DiscoverForMcpResult>;
+declare function inspectEndpointForMcp(options: InspectEndpointForMcpOptions): Promise<InspectEndpointForMcpResult>;
+
 declare const UPGRADE_WARNING_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "OPENAPI_AUTH_MODE_MISSING", "OPENAPI_TOP_LEVEL_INVALID"];
 declare function computeUpgradeSignal(warnings: DiscoveryWarning[]): {
     upgradeSuggested: boolean;
@@ -207,4 +289,4 @@ declare function defaultHarnessProbeCandidates(report: ContextHarnessReport): Pr
 declare function discover(options: DiscoverOptions): Promise<DiscoverResult>;
 declare function discoverDetailed(options: DiscoverDetailedOptions): Promise<DiscoverDetailedResult>;
 
-export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, getHarnessClientProfile, listHarnessClientProfiles };
+export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverForMcpFailure, type DiscoverForMcpOptions, type DiscoverForMcpResult, type DiscoverForMcpSuccess, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type EndpointMethodAdvisory, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type InspectEndpointForMcpFailure, type InspectEndpointForMcpOptions, type InspectEndpointForMcpResult, type InspectEndpointForMcpSuccess, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, discoverForMcp, getHarnessClientProfile, inspectEndpointForMcp, listHarnessClientProfiles };

package/dist/index.js

@@ -12,7 +12,7 @@ var STRICT_ESCALATION_CODES = [
 ];
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.1".includes("-mmm");
+var isMmmEnabled = () => "0.1.2".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -1400,6 +1400,396 @@ async function runDiscovery({
   };
 }
 
+// src/adapters/mcp.ts
+var DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS = 1e3;
+var OPENAPI_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+];
+function isRecord4(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+function formatPriceHintFromResource(resource) {
+  const pricing = resource.pricing;
+  if (pricing) {
+    if (pricing.pricingMode === "fixed" && pricing.price) {
+      return pricing.price.startsWith("$") ? pricing.price : `$${pricing.price}`;
+    }
+    if (pricing.pricingMode === "range" && pricing.minPrice && pricing.maxPrice) {
+      const min = pricing.minPrice.startsWith("$") ? pricing.minPrice : `$${pricing.minPrice}`;
+      const max = pricing.maxPrice.startsWith("$") ? pricing.maxPrice : `$${pricing.maxPrice}`;
+      return `${min}-${max}`;
+    }
+  }
+  if (!resource.priceHint) return void 0;
+  const hint = resource.priceHint.trim();
+  if (hint.length === 0) return void 0;
+  if (hint.startsWith("$")) return hint;
+  if (hint.includes("-")) {
+    const [min, max] = hint.split("-", 2).map((part) => part.trim());
+    if (min && max) return `$${min}-$${max}`;
+  }
+  return `$${hint}`;
+}
+function deriveMcpAuthMode(resource) {
+  if (!resource) return void 0;
+  const hint = resource.authHint;
+  if (hint === "paid" || hint === "siwx" || hint === "apiKey" || hint === "unprotected") {
+    return hint;
+  }
+  return void 0;
+}
+function inferFailureCause(warnings) {
+  const openapiWarnings = warnings.filter((w) => w.stage === "openapi");
+  const parseWarning = openapiWarnings.find(
+    (w) => w.code === "PARSE_FAILED" || w.code === "OPENAPI_TOP_LEVEL_INVALID" || w.code === "OPENAPI_OPERATION_INVALID" || w.code === "OPENAPI_PRICING_INVALID"
+  );
+  if (parseWarning) {
+    return { cause: "parse", message: parseWarning.message };
+  }
+  const fetchWarning = openapiWarnings.find((w) => w.code === "FETCH_FAILED");
+  if (fetchWarning) {
+    const msg = fetchWarning.message.toLowerCase();
+    if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("abort")) {
+      return { cause: "timeout", message: fetchWarning.message };
+    }
+    return { cause: "network", message: fetchWarning.message };
+  }
+  return { cause: "not_found" };
+}
+function getOpenApiInfo(document) {
+  if (!isRecord4(document) || !isRecord4(document.info)) return void 0;
+  if (typeof document.info.title !== "string") return void 0;
+  return {
+    title: document.info.title,
+    ...typeof document.info.version === "string" ? { version: document.info.version } : {},
+    ...typeof document.info.description === "string" ? { description: document.info.description } : {}
+  };
+}
+function getGuidanceUrl(result) {
+  const fromTrace = result.trace.find((entry) => entry.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromTrace) return fromTrace;
+  const fromResource = result.resources.find((resource) => resource.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromResource) return fromResource;
+  return void 0;
+}
+async function resolveGuidance(options) {
+  let guidanceText = typeof options.result.rawSources?.llmsTxt === "string" ? options.result.rawSources.llmsTxt : void 0;
+  if (!guidanceText) {
+    const guidanceUrl = getGuidanceUrl(options.result) ?? `${options.result.origin}/llms.txt`;
+    const fetcher = options.fetcher ?? fetch;
+    try {
+      const response = await fetcher(guidanceUrl, {
+        method: "GET",
+        headers: { Accept: "text/plain", ...options.headers },
+        signal: options.signal
+      });
+      if (response.ok) guidanceText = await response.text();
+    } catch {
+    }
+  }
+  if (!guidanceText) {
+    return { guidanceAvailable: false };
+  }
+  const guidanceTokens = estimateTokenCount(guidanceText);
+  const threshold = options.guidanceAutoIncludeMaxTokens ?? DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS;
+  const shouldInclude = options.includeGuidance === true || options.includeGuidance == null && guidanceTokens <= threshold;
+  return {
+    guidanceAvailable: true,
+    guidanceTokens,
+    ...shouldInclude ? { guidance: guidanceText } : {}
+  };
+}
+function extractPathsDocument(document) {
+  if (!isRecord4(document)) return void 0;
+  if (!isRecord4(document.paths)) return void 0;
+  return document.paths;
+}
+function findMatchingOpenApiPath(paths, targetPath) {
+  const exact = paths[targetPath];
+  if (isRecord4(exact)) return { matchedPath: targetPath, pathItem: exact };
+  for (const [specPath, entry] of Object.entries(paths)) {
+    if (!isRecord4(entry)) continue;
+    const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
+    const regex = new RegExp(`^${pattern}$`);
+    if (regex.test(targetPath)) {
+      return { matchedPath: specPath, pathItem: entry };
+    }
+  }
+  return null;
+}
+function resolveRef(document, ref, seen) {
+  if (!ref.startsWith("#/")) return void 0;
+  if (seen.has(ref)) return { $circular: ref };
+  seen.add(ref);
+  const parts = ref.slice(2).split("/");
+  let current = document;
+  for (const part of parts) {
+    if (!isRecord4(current)) return void 0;
+    current = current[part];
+    if (current === void 0) return void 0;
+  }
+  if (isRecord4(current)) return resolveRefs(document, current, seen);
+  return current;
+}
+function resolveRefs(document, obj, seen, depth = 0) {
+  if (depth > 4) return obj;
+  const resolved = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$ref" && typeof value === "string") {
+      const deref = resolveRef(document, value, seen);
+      if (isRecord4(deref)) {
+        Object.assign(resolved, deref);
+      } else {
+        resolved[key] = value;
+      }
+      continue;
+    }
+    if (isRecord4(value)) {
+      resolved[key] = resolveRefs(document, value, seen, depth + 1);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      resolved[key] = value.map(
+        (item) => isRecord4(item) ? resolveRefs(document, item, seen, depth + 1) : item
+      );
+      continue;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+function extractRequestBodySchema(operationSchema) {
+  const requestBody = operationSchema.requestBody;
+  if (!isRecord4(requestBody)) return void 0;
+  const content = requestBody.content;
+  if (!isRecord4(content)) return void 0;
+  const jsonMediaType = content["application/json"];
+  if (isRecord4(jsonMediaType) && isRecord4(jsonMediaType.schema)) {
+    return jsonMediaType.schema;
+  }
+  for (const mediaType of Object.values(content)) {
+    if (isRecord4(mediaType) && isRecord4(mediaType.schema)) {
+      return mediaType.schema;
+    }
+  }
+  return void 0;
+}
+function extractParameters(operationSchema) {
+  const params = operationSchema.parameters;
+  if (!Array.isArray(params)) return [];
+  return params.filter((value) => isRecord4(value));
+}
+function extractInputSchema(operationSchema) {
+  const requestBody = extractRequestBodySchema(operationSchema);
+  const parameters = extractParameters(operationSchema);
+  if (!requestBody && parameters.length === 0) return void 0;
+  if (requestBody && parameters.length === 0) return requestBody;
+  return {
+    ...requestBody ? { requestBody } : {},
+    ...parameters.length > 0 ? { parameters } : {}
+  };
+}
+function parseOperationPrice(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord4(paymentInfo)) return void 0;
+  const fixed = toFiniteNumber(paymentInfo.price);
+  if (fixed != null) return `$${String(fixed)}`;
+  const min = toFiniteNumber(paymentInfo.minPrice);
+  const max = toFiniteNumber(paymentInfo.maxPrice);
+  if (min != null && max != null) return `$${String(min)}-$${String(max)}`;
+  return void 0;
+}
+function parseOperationProtocols(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord4(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
+  const protocols = paymentInfo.protocols.filter(
+    (protocol) => typeof protocol === "string" && protocol.length > 0
+  );
+  return protocols.length > 0 ? protocols : void 0;
+}
+function parseOperationAuthMode(operation) {
+  const authExtension = operation["x-agentcash-auth"];
+  if (isRecord4(authExtension)) {
+    const mode = authExtension.mode;
+    if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
+      return mode;
+    }
+  }
+  if (isRecord4(operation["x-payment-info"])) return "paid";
+  return void 0;
+}
+function createResourceMap(result) {
+  const map = /* @__PURE__ */ new Map();
+  for (const resource of result.resources) {
+    map.set(resource.resourceKey, resource);
+  }
+  return map;
+}
+function toMcpEndpointSummary(resource) {
+  const method = parseMethod(resource.method);
+  if (!method) return void 0;
+  const price = formatPriceHintFromResource(resource);
+  const authMode = deriveMcpAuthMode(resource);
+  return {
+    path: resource.path,
+    method,
+    summary: resource.summary ?? `${method} ${resource.path}`,
+    ...price ? { price } : {},
+    ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+    ...authMode ? { authMode } : {}
+  };
+}
+async function discoverForMcp(options) {
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  if (result.resources.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin: result.origin,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  const source = result.selectedStage ?? "openapi";
+  const endpoints = result.resources.map(toMcpEndpointSummary).filter((endpoint) => endpoint != null).sort((a, b) => {
+    if (a.path !== b.path) return a.path.localeCompare(b.path);
+    return a.method.localeCompare(b.method);
+  });
+  const guidance = await resolveGuidance({
+    result,
+    includeGuidance: options.includeGuidance,
+    guidanceAutoIncludeMaxTokens: options.guidanceAutoIncludeMaxTokens,
+    fetcher: options.fetcher,
+    headers: options.headers,
+    signal: options.signal
+  });
+  return {
+    found: true,
+    origin: result.origin,
+    source,
+    ...getOpenApiInfo(result.rawSources?.openapi) ? { info: getOpenApiInfo(result.rawSources?.openapi) } : {},
+    ...guidance,
+    endpoints,
+    warnings: result.warnings
+  };
+}
+async function inspectEndpointForMcp(options) {
+  const endpoint = new URL(options.endpointUrl);
+  const origin = normalizeOrigin(endpoint.origin);
+  const path = normalizePath(endpoint.pathname || "/");
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  const document = result.rawSources?.openapi;
+  const paths = extractPathsDocument(document);
+  const resourceMap = createResourceMap(result);
+  const advisories = {};
+  const specMethods = [];
+  if (paths) {
+    const matched = findMatchingOpenApiPath(paths, path);
+    if (matched) {
+      for (const candidate of OPENAPI_METHODS) {
+        const operation = matched.pathItem[candidate.toLowerCase()];
+        if (!isRecord4(operation) || !isRecord4(document)) continue;
+        specMethods.push(candidate);
+        const resolvedOperation = resolveRefs(document, operation, /* @__PURE__ */ new Set());
+        const resource = resourceMap.get(toResourceKey(origin, candidate, matched.matchedPath));
+        const formattedPrice = resource ? formatPriceHintFromResource(resource) : void 0;
+        const operationSummary = typeof resolvedOperation.summary === "string" ? resolvedOperation.summary : typeof resolvedOperation.description === "string" ? resolvedOperation.description : void 0;
+        const operationPrice = parseOperationPrice(resolvedOperation);
+        const operationProtocols = parseOperationProtocols(resolvedOperation);
+        const operationAuthMode = parseOperationAuthMode(resolvedOperation);
+        const inputSchema = extractInputSchema(resolvedOperation);
+        advisories[candidate] = {
+          method: candidate,
+          ...resource?.summary || operationSummary ? {
+            summary: resource?.summary ?? operationSummary
+          } : {},
+          ...formattedPrice || operationPrice ? {
+            estimatedPrice: formattedPrice ?? operationPrice
+          } : {},
+          ...resource?.protocolHints?.length || operationProtocols ? {
+            protocols: resource?.protocolHints ?? operationProtocols
+          } : {},
+          ...deriveMcpAuthMode(resource) || operationAuthMode ? {
+            authMode: deriveMcpAuthMode(resource) ?? operationAuthMode
+          } : {},
+          ...inputSchema ? { inputSchema } : {},
+          operationSchema: resolvedOperation
+        };
+      }
+    }
+  }
+  if (specMethods.length === 0) {
+    for (const method of OPENAPI_METHODS) {
+      const resource = resourceMap.get(toResourceKey(origin, method, path));
+      if (!resource) continue;
+      specMethods.push(method);
+      const formattedPrice = formatPriceHintFromResource(resource);
+      advisories[method] = {
+        method,
+        ...resource.summary ? { summary: resource.summary } : {},
+        ...formattedPrice ? { estimatedPrice: formattedPrice } : {},
+        ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+        ...deriveMcpAuthMode(resource) ? { authMode: deriveMcpAuthMode(resource) } : {}
+      };
+    }
+  }
+  if (specMethods.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin,
+      path,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  return {
+    found: true,
+    origin,
+    path,
+    specMethods,
+    advisories,
+    warnings: result.warnings
+  };
+}
+
 // src/harness.ts
 var INTENT_TRIGGERS = ["x402", "mpp", "pay for", "micropayment", "agentic commerce"];
 var CLIENT_PROFILES = {
@@ -1658,6 +2048,8 @@ export {
   defaultHarnessProbeCandidates,
   discover,
   discoverDetailed,
+  discoverForMcp,
   getHarnessClientProfile,
+  inspectEndpointForMcp,
   listHarnessClientProfiles
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/discovery",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Canonical OpenAPI-first discovery runtime for the agentcash ecosystem",
   "type": "module",
   "main": "./dist/index.cjs",