@opengeni/capabilities 0.2.0 → 0.3.0-canary.0

package/README.md

@@ -20,4 +20,20 @@ Security defaults:
 - a safe read/query may refresh and retry exactly once on `401`, while a
   mutation is never replayed after an ambiguous provider authorization result;
   and
-- errors contain structural recovery facts, never provider bodies or secrets.
+- errors contain structural recovery facts, never provider bodies or secrets.
+
+## Local MCP bridge kit
+
+`src/mcp-bridge.ts` defines the shared contract for provider APIs exposed as
+in-process MCP servers. A bridge declares a secret-free catalog identity,
+actual authority class, reviewed tool-surface class, 1-32 exact HTTPS
+destinations, and the safe-read-only replay rule. Adapter matching is generic
+and fails closed on ambiguity. The descriptor is not authorization: each
+adapter still revalidates its Connection or host-owned authority before every
+provider request.
+
+The Gmail REST adapter is the static reviewed example. OpenAPI and GraphQL
+Integration Definitions keep their existing local MCP adapters without
+claiming this descriptor. Google Drive remains one functional Integration row
+with its existing Connection and facet authority. See
+`docs/design/first-party-mcp-bridges.md`.

package/dist/index.d.ts

@@ -2,7 +2,9 @@ export * from "./auth.js";
 export * from "./graphql.js";
 export * from "./http.js";
 export * from "./mcp-manifest.js";
+export * from "./mcp-bridge.js";
 export * from "./openapi.js";
 export * from "./integration-definitions.js";
+export * from "./integration-presentations.js";
 export * from "./revision.js";
 export * from "./types.js";

package/dist/index.js

@@ -619,6 +619,22 @@ async function sendGraphqlRequest(options, request, credential, signal) {
   headers.set("accept", "application/json");
   headers.set("content-type", "application/json");
   if (credential) applyCredentialPlacements(endpoint, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     endpoint,
@@ -830,6 +846,63 @@ function basename(value) {
   return value?.trim().split(/[\\/]/).pop() ?? "";
 }
 
+// src/mcp-bridge.ts
+var LOCAL_MCP_BRIDGE_CONTRACT_VERSION = 1;
+function defineLocalMcpBridgeDescriptor(input) {
+  const adapterId = boundedIdentity(input.adapterId, "adapterId");
+  const providerId = boundedIdentity(input.providerId, "providerId");
+  const catalogIdentity = boundedIdentity(input.catalogIdentity, "catalogIdentity", 512);
+  if (input.destinations.length === 0 || input.destinations.length > 32) {
+    throw new Error("Local MCP bridge must declare 1-32 provider destinations");
+  }
+  const destinations = input.destinations.map((destination) => {
+    const url = new URL(destination.origin);
+    if (url.protocol !== "https:" || url.origin !== destination.origin) {
+      throw new Error("Local MCP bridge destinations must be exact HTTPS origins");
+    }
+    if (!destination.pathPrefix.startsWith("/") || destination.pathPrefix.includes("\\") || destination.pathPrefix.includes("?") || destination.pathPrefix.includes("#") || new URL(destination.pathPrefix, url.origin).pathname !== destination.pathPrefix) {
+      throw new Error("Local MCP bridge destination pathPrefix must be an absolute URL path");
+    }
+    return Object.freeze({ origin: url.origin, pathPrefix: destination.pathPrefix });
+  });
+  return Object.freeze({
+    contractVersion: LOCAL_MCP_BRIDGE_CONTRACT_VERSION,
+    adapterId,
+    providerId,
+    catalogIdentity,
+    transport: "in_process",
+    authority: input.authority,
+    toolSurface: input.toolSurface,
+    mutationReplay: input.mutationReplay,
+    destinations: Object.freeze(destinations)
+  });
+}
+function isLocalMcpBridgeServer(server) {
+  const bridge = server.bridge;
+  return bridge?.contractVersion === LOCAL_MCP_BRIDGE_CONTRACT_VERSION && bridge.transport === "in_process";
+}
+function createLocalMcpBridgeFromAdapters(adapters, config, context) {
+  const matches = adapters.filter((adapter2) => adapter2.matches(config));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple local MCP bridge adapters matched: ${matches.map((entry) => entry.adapterId).join(", ")}`
+    );
+  }
+  const adapter = matches[0];
+  const server = adapter.create(config, context);
+  if (server.bridge.adapterId !== adapter.adapterId) {
+    throw new Error(`Local MCP bridge adapter ${adapter.adapterId} returned mismatched metadata`);
+  }
+  return server;
+}
+function boundedIdentity(value, name, max = 128) {
+  if (value.length === 0 || value.length > max || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error(`Local MCP bridge ${name} is invalid`);
+  }
+  return value;
+}
+
 // src/openapi.ts
 import { load as parseYaml } from "js-yaml";
 var methods = /* @__PURE__ */ new Set([
@@ -1125,6 +1198,22 @@ async function sendOpenApiRequest(options, binding, args, credential, signal) {
   const headers = buildOperationHeaders(binding, args);
   const body = buildOperationBody(binding, args, headers);
   if (credential) applyCredentialPlacements(url, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     url,
@@ -1517,7 +1606,7 @@ var mailboxFacets = (provider) => [
       provider,
       connectionRequired: true,
       delivery: "poll",
-      cursor: provider === "google-gmail" ? "history_id" : "delta_link"
+      cursor: "delta_link"
     }
   },
   {
@@ -1537,7 +1626,7 @@ var mailboxFacets = (provider) => [
       delivery: "email"
     }
   },
-  accountIdentityFacet(provider === "google-gmail" ? "google" : "microsoft")
+  accountIdentityFacet("microsoft")
 ];
 var googleDiscoveryUrl = (service, version) => `https://www.googleapis.com/discovery/v1/apis/${service}/${version}/rest`;
 var googleOAuth = (scopes) => ({
@@ -1563,21 +1652,6 @@ var GOOGLE_DRIVE_INTEGRATION_DEFINITION = {
   },
   facets: [driveKnowledgeFacet("google-drive"), accountIdentityFacet("google")]
 };
-var GOOGLE_GMAIL_INTEGRATION_DEFINITION = {
-  id: "google-gmail",
-  name: "Gmail",
-  summary: "Messages, threads, labels, drafts, and sending mail.",
-  protocol: "openapi",
-  provider: { id: "google", domain: "gmail.googleapis.com" },
-  source: { kind: "google_discovery", url: googleDiscoveryUrl("gmail", "v1") },
-  baseUrl: "https://gmail.googleapis.com/",
-  authentication: googleOAuth(["https://mail.google.com/"]),
-  healthCheck: {
-    operationKey: "gmail.users.labels.list",
-    arguments: { path: { userId: "me" } }
-  },
-  facets: mailboxFacets("google-gmail")
-};
 var MICROSOFT_GRAPH_OPENAPI_URL = "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
 var MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
 var microsoftOAuth = (scopes) => ({
@@ -1702,7 +1776,6 @@ var MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION = {
 };
 var CORE_INTEGRATION_DEFINITIONS = [
   GOOGLE_DRIVE_INTEGRATION_DEFINITION,
-  GOOGLE_GMAIL_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION,
@@ -1819,9 +1892,7 @@ function collectGoogleMethods(document, value, paths) {
     const path = stringValue2(rawMethod.path);
     const httpMethod = stringValue2(rawMethod.httpMethod)?.toLowerCase();
     if (!path || !httpMethod) continue;
-    const parameters = Object.entries(
-      isRecord3(rawMethod.parameters) ? rawMethod.parameters : {}
-    ).flatMap(([name, rawParameter]) => {
+    const parameters = Object.entries(isRecord3(rawMethod.parameters) ? rawMethod.parameters : {}).sort(([left], [right]) => left.localeCompare(right)).flatMap(([name, rawParameter]) => {
       if (!isRecord3(rawParameter)) return [];
       const location = rawParameter.location === "path" ? "path" : "query";
       return [
@@ -1838,7 +1909,10 @@ function collectGoogleMethods(document, value, paths) {
     const responseRef = isRecord3(rawMethod.response) ? stringValue2(rawMethod.response.$ref) : void 0;
     const operation = {
       operationId: stringValue2(rawMethod.id) ?? fallbackId,
-      summary: stringValue2(rawMethod.description) ?? stringValue2(rawMethod.id) ?? fallbackId,
+      // Discovery descriptions are often full documentation paragraphs. Keep
+      // them as descriptions and use the stable method identity for the short
+      // OpenGeni tool display name.
+      summary: stringValue2(rawMethod.id) ?? fallbackId,
       description: stringValue2(rawMethod.description),
       parameters,
       responses: {
@@ -1917,15 +1991,166 @@ function stringValue2(value) {
 function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+
+// src/integration-presentations.ts
+var INTEGRATION_DEFINITION_PRESENTATIONS = {
+  "google-drive": {
+    providerName: "Google",
+    icon: "files",
+    introduction: "Let agents work with files in the Google Drive account you choose.",
+    capabilities: [
+      {
+        title: "Find files and folders",
+        description: "Browse and search content in My Drive and shared drives."
+      },
+      {
+        title: "Create and update content",
+        description: "Work with files and folders through the reviewed Drive tools."
+      },
+      {
+        title: "Manage sharing",
+        description: "Review and update links, permissions, and shared-drive content."
+      }
+    ],
+    permissionSummary: "Google asks for access to the Drive account you approve, including files shared with that account.",
+    scopeLabels: {
+      "https://www.googleapis.com/auth/drive": {
+        label: "Work with Google Drive files",
+        description: "See, create, edit, organize, and share files available to this account."
+      }
+    }
+  },
+  "microsoft-outlook-mail": {
+    providerName: "Microsoft",
+    icon: "mail",
+    introduction: "Let agents work with mail in the Microsoft account you choose.",
+    capabilities: [
+      {
+        title: "Find and understand mail",
+        description: "Search messages, folders, and attachments for useful context."
+      },
+      {
+        title: "Draft and send messages",
+        description: "Prepare, update, and send mail through the reviewed Outlook tools."
+      },
+      {
+        title: "Manage mailbox settings",
+        description: "Work with supported folders, classifications, and mailbox preferences."
+      }
+    ],
+    permissionSummary: "Microsoft asks for mail and mailbox-setting access for the account you approve.",
+    scopeLabels: {
+      "Mail.ReadWrite": {
+        label: "Read and update mail",
+        description: "Work with messages, folders, and attachments in this mailbox."
+      },
+      "Mail.Send": {
+        label: "Send mail",
+        description: "Send messages as the connected Microsoft account."
+      },
+      "MailboxSettings.ReadWrite": {
+        label: "Manage mailbox settings",
+        description: "Read and update supported Outlook mailbox preferences."
+      }
+    }
+  },
+  "microsoft-outlook-calendar": {
+    providerName: "Microsoft",
+    icon: "calendar",
+    introduction: "Let agents help coordinate the calendars in your Microsoft account.",
+    capabilities: [
+      {
+        title: "Understand your schedule",
+        description: "Review calendars, events, availability, and reminders."
+      },
+      {
+        title: "Plan meetings",
+        description: "Find suitable times and coordinate calendar activity."
+      },
+      {
+        title: "Manage events",
+        description: "Create and update events through the reviewed calendar tools."
+      }
+    ],
+    permissionSummary: "Microsoft asks for permission to view and manage calendars for the account you approve.",
+    scopeLabels: {
+      "Calendars.ReadWrite": {
+        label: "View and manage calendars",
+        description: "Read, create, update, and organize calendar events."
+      }
+    }
+  },
+  "microsoft-outlook-contacts": {
+    providerName: "Microsoft",
+    icon: "contacts",
+    introduction: "Let agents work with contacts in your Microsoft account.",
+    capabilities: [
+      {
+        title: "Find people",
+        description: "Look up contacts and relevant people suggestions."
+      },
+      {
+        title: "Organize contacts",
+        description: "Work with contacts and contact folders."
+      },
+      {
+        title: "Keep details current",
+        description: "Create or update contact information through reviewed tools."
+      }
+    ],
+    permissionSummary: "Microsoft asks for contact access and people suggestions for the account you approve.",
+    scopeLabels: {
+      "Contacts.ReadWrite": {
+        label: "View and manage contacts",
+        description: "Read, create, update, and organize contacts and contact folders."
+      },
+      "People.Read.All": {
+        label: "Find relevant people",
+        description: "Use people suggestions available to the connected account."
+      }
+    }
+  },
+  "microsoft-onedrive": {
+    providerName: "Microsoft",
+    icon: "cloud",
+    introduction: "Let agents work with files in the Microsoft account you choose.",
+    capabilities: [
+      {
+        title: "Find files and folders",
+        description: "Browse drives, folders, shared items, and sites available to the account."
+      },
+      {
+        title: "Create and update content",
+        description: "Work with OneDrive and SharePoint files through reviewed tools."
+      },
+      {
+        title: "Manage sharing",
+        description: "Review and update sharing links and permissions."
+      }
+    ],
+    permissionSummary: "Microsoft asks for file and site access anywhere the connected account already has access.",
+    scopeLabels: {
+      "Files.ReadWrite.All": {
+        label: "Work with accessible files",
+        description: "Read, create, update, and organize files available to this account."
+      },
+      "Sites.ReadWrite.All": {
+        label: "Work with accessible sites",
+        description: "Read and update files in SharePoint sites available to this account."
+      }
+    }
+  }
+};
 export {
   CORE_INTEGRATION_DEFINITIONS,
   DEFAULT_INTEGRATION_RESPONSE_BYTES,
   DEFAULT_INTEGRATION_TIMEOUT_MS,
   GOOGLE_DRIVE_INTEGRATION_DEFINITION,
-  GOOGLE_GMAIL_INTEGRATION_DEFINITION,
   GraphqlMcpServer,
+  INTEGRATION_DEFINITION_PRESENTATIONS,
   IntegrationInvocationError,
   IntegrationProtocolError,
+  LOCAL_MCP_BRIDGE_CONTRACT_VERSION,
   MAX_INTEGRATION_SPEC_BYTES,
   MAX_INTEGRATION_TOOLS,
   MICROSOFT_GRAPH_BASE_URL,
@@ -1941,8 +2166,10 @@ export {
   compileGraphqlRevision,
   compileOpenApiRevision,
   createGraphqlMcpServer,
+  createLocalMcpBridgeFromAdapters,
   createOpenApiMcpServer,
   createPinnedIntegrationTransport,
+  defineLocalMcpBridgeDescriptor,
   deriveMcpNamespace,
   directIntegrationTransport,
   discoverOpenApiAuth,
@@ -1958,6 +2185,7 @@ export {
   integrationFacetDefinitions,
   invokeGraphqlOperation,
   invokeOpenApiOperation,
+  isLocalMcpBridgeServer,
   parseOpenApiDocument,
   readIntegrationResponse,
   sha256Hex,