@lanes-sh/link 0.1.0

package/src/connectivity/transports/http/index.ts

@@ -0,0 +1,255 @@
+import type { McpOpenAPITool, ParameterMapper } from 'mcp-from-openapi';
+import { shortenName } from '../mcp/index.ts';
+import {
+  READ_BUNDLE,
+  WRITE_BUNDLE,
+  type Connector,
+  type ConnectorContext,
+  type DiscoveredCapability,
+  type ToolResult,
+} from '#connectivity';
+
+/**
+ * The `http` connector — a REST API described by OpenAPI.
+ *
+ * This is what stops the next service without an MCP server becoming another
+ * 612 lines. An operation becomes a capability mechanically: `mcp-from-openapi`
+ * resolves `$ref`s and `allOf`, merges path, query, header, and body parameters
+ * into one input schema, and hands back a mapper describing where each argument
+ * belongs in the request. We contribute the bundle split, the filtering, and
+ * the auth — never per-endpoint translation.
+ */
+
+export interface HttpConnectorOptions {
+  readonly baseUrl: string;
+  /** URL or filesystem path to an OpenAPI 3.x document. */
+  readonly openapi: string;
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * `*` matches any run of characters; anything else is literal.
+ *
+ * Matched against operationId, path, and tags, because which of those an
+ * operator reaches for depends entirely on how the vendor wrote their spec.
+ */
+export function globMatches(pattern: string, value: string): boolean {
+  if (!pattern.includes('*')) return pattern === value;
+  const expression = pattern
+    .split('*')
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*');
+  return new RegExp(`^${expression}$`, 'i').test(value);
+}
+
+/**
+ * The HTTP method decides the bundle.
+ *
+ * A spec yields meaningful read/write groups with no curation, which is what
+ * lets `connect` grant something sensible by default on an API nobody has
+ * hand-classified. GET and HEAD are the only verbs that are reliably safe.
+ */
+export function bundleForMethod(method: string): string {
+  return /^(get|head)$/i.test(method) ? READ_BUNDLE : WRITE_BUNDLE;
+}
+
+function selected(tool: McpOpenAPITool, options: HttpConnectorOptions): boolean {
+  const candidates = [
+    tool.metadata.operationId ?? '',
+    tool.metadata.path,
+    tool.name,
+    ...(tool.metadata.tags ?? []),
+  ].filter(Boolean);
+
+  const matches = (patterns: readonly string[]): boolean =>
+    patterns.some((pattern) => candidates.some((candidate) => globMatches(pattern, candidate)));
+
+  if (options.exclude?.length && matches(options.exclude)) return false;
+  if (options.include?.length) return matches(options.include);
+  return true;
+}
+
+export function createHttpConnector(options: HttpConnectorOptions): Connector {
+  let generated: McpOpenAPITool[] | undefined;
+
+  const load = async (): Promise<McpOpenAPITool[]> => {
+    if (generated) return generated;
+
+    // Imported here rather than at the top of the file, so a process that
+    // never opens a connector never loads it. `mcp-from-openapi` brings a
+    // swagger parser and a YAML parser of its own, around two and a half
+    // megabytes with its transitive tree.
+    //
+    // Measured, and worth being accurate about: this buys **no** startup time
+    // that a stopwatch can see — `audit verify` runs in 0.16s either way. It is
+    // here for the same reason `deployments/target.ts` imports its cloud
+    // adapters inside their branch: code that cannot run should not be loaded,
+    // so a parser bug or a supply-chain problem in it cannot reach a process
+    // that was never going to call it. The types above are `import type` and
+    // cost nothing either way.
+    const { OpenAPIToolGenerator } = await import('mcp-from-openapi');
+
+    // `fromURL` performs SSRF checks on the spec URL, which matters because the
+    // URL comes from an operator-supplied manifest and this process can reach
+    // the local network.
+    const generator = /^https?:/i.test(options.openapi)
+      ? await OpenAPIToolGenerator.fromURL(options.openapi)
+      : await OpenAPIToolGenerator.fromFile(options.openapi);
+
+    generated = await generator.generateTools();
+    return generated;
+  };
+
+  return {
+    kind: 'http',
+
+    async discover(context): Promise<DiscoveredCapability[]> {
+      const tools = await load();
+      const chosen = tools.filter((tool) => selected(tool, options));
+      const names = chosen.map((tool) => tool.name);
+
+      return chosen.map((tool) => {
+        // Google's operationIds are already namespaced — `gmail.users.labels.list`
+        // — so without this the wire name becomes `gmail_gmail_users_labels_list`.
+        // Same fix, and the same reason, as the Notion tools named `notion-*`.
+        const name = shortenName(context.manifest.id, tool.name, names);
+
+        // Appended, never substituted. A generated description says what the
+        // arguments are and nothing about what the capability is *for*, because
+        // the vendor wrote the document for someone who already knows the
+        // product. The manifest is not the authority on the first half, so it
+        // adds to it rather than replacing it.
+        const described =
+          tool.description || `${tool.metadata.method.toUpperCase()} ${tool.metadata.path}`;
+        const hint = context.manifest.hints?.[name];
+
+        return {
+          name,
+          description: hint ? `${described}\n\n${hint}` : described,
+          inputSchema: tool.inputSchema as unknown as Record<string, unknown>,
+          bundle: bundleForMethod(tool.metadata.method),
+          // Everything needed to rebuild the request without re-reading the spec,
+          // so a cold instance serves from the cache alone.
+          target: {
+            path: tool.metadata.path,
+            method: tool.metadata.method,
+            mapper: tool.mapper as unknown as Record<string, unknown>[],
+          },
+        };
+      });
+    },
+
+    async invoke(capability, args, context: ConnectorContext): Promise<ToolResult> {
+      const method = String(capability.target?.['method'] ?? 'get').toUpperCase();
+      const template = String(capability.target?.['path'] ?? '');
+      const mapper = (capability.target?.['mapper'] ?? []) as ParameterMapper[];
+
+      const url = new URL(options.baseUrl.replace(/\/$/, '') + buildPath(template, args, mapper));
+      const headers = new Headers({ accept: 'application/json' });
+      const body = collect(args, mapper, 'body');
+
+      for (const [key, value] of Object.entries(collect(args, mapper, 'query'))) {
+        if (value === undefined) continue;
+
+        // An array is repeated, not joined. OpenAPI's default for a query
+        // parameter is `style: form, explode: true`, which means one occurrence
+        // per element — and `String(['From','Subject'])` produces the single
+        // value `From,Subject` instead. That failed silently and specifically:
+        // Gmail's `metadataHeaders` matched no header name at all, so asking
+        // for From and Subject returned a message with an empty header list
+        // and no error to explain it.
+        if (Array.isArray(value)) {
+          for (const element of value) {
+            if (element !== undefined && element !== null) url.searchParams.append(key, String(element));
+          }
+          continue;
+        }
+
+        url.searchParams.set(key, String(value));
+      }
+      for (const [key, value] of Object.entries(collect(args, mapper, 'header'))) {
+        if (value !== undefined) headers.set(key, String(value));
+      }
+
+      const hasBody = Object.keys(body).length > 0;
+      if (hasBody) headers.set('content-type', 'application/json');
+
+      // Auth is attached by core, from the manifest's auth kind or its strategy.
+      // A connector never sees a raw credential.
+      const request = await context.authorize(
+        new Request(url.href, {
+          method,
+          headers,
+          ...(hasBody ? { body: JSON.stringify(body) } : {}),
+          signal: context.provider.signal,
+        }),
+      );
+
+      const doFetch = options.fetch ?? globalThis.fetch;
+      const response = await doFetch(request);
+
+      // Cloned so a verifier can read the body without consuming it for us.
+      await context.verify?.(response.clone() as unknown as Response);
+
+      const text = await response.text();
+      if (!response.ok) {
+        return {
+          content: [{ type: 'text', text: `${response.status} ${response.statusText}\n${text}` }],
+          isError: true,
+        };
+      }
+
+      // A write that answers 204 has confirmed itself, but an empty string is not
+      // a confirmation an agent can read — it is indistinguishable from a call
+      // that did nothing, and settling it cost a second, read-only call. Every
+      // other transport synthesises a receipt for this reason: `{ deleted: true,
+      // uid, … }` in dav, `{ written: true, path, bytes }` in fs. This one is
+      // generic and has no such knowledge to draw on, so it claims only what the
+      // status licenses — that the request succeeded. A body that exists, `{}`
+      // included, is an answer rather than an absent one and passes through.
+      if (text.trim() === '') {
+        return {
+          content: [
+            { type: 'text', text: JSON.stringify({ ok: true, status: response.status }, null, 2) },
+          ],
+        };
+      }
+
+      return { content: [{ type: 'text', text }] };
+    },
+  };
+}
+
+/** Substitute `{param}` placeholders from the arguments the mapper marks as path. */
+function buildPath(
+  template: string,
+  args: Readonly<Record<string, unknown>>,
+  mapper: readonly ParameterMapper[],
+): string {
+  const values = collect(args, mapper, 'path');
+
+  return template.replace(/\{([^}]+)\}/g, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}"`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+/** Pull the arguments belonging to one part of the request. */
+function collect(
+  args: Readonly<Record<string, unknown>>,
+  mapper: readonly ParameterMapper[],
+  location: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+
+  for (const entry of mapper) {
+    if (entry.type !== location) continue;
+    const value = args[entry.inputKey];
+    if (value !== undefined) out[entry.key] = value;
+  }
+
+  return out;
+}

package/src/connectivity/transports/imap/attachment.ts

@@ -0,0 +1,166 @@
+import PostalMime from 'postal-mime';
+import type { MailboxAttachmentSource } from '#connectivity/mail';
+import { quoted, type ImapClient, type ImapSession } from './client.ts';
+import { asText, itemValue } from './parser.ts';
+import { decodeMailboxName, encodeMailboxName } from './utf7.ts';
+
+/**
+ * Re-attaching an attachment that is already in the mailbox.
+ *
+ * This is the source worth having most, and the one the reported failure
+ * actually needed: a PDF arrived by mail, and forwarding it should not require
+ * the bytes to make a round trip through the model. Here they never leave the
+ * process.
+ *
+ * A message is named by its RFC 2822 `Message-ID` rather than by UID, because
+ * that is what `get_message` and `search_messages` already report and it does not
+ * oblige the caller to also remember which folder the message was in. The cost is
+ * a search: INBOX first, since that is where it almost always is, then the rest
+ * of the folders in the order the server lists them.
+ *
+ * Kept out of `commands.ts` because that file is near the size budget and this is
+ * a self-contained question — which bytes, given a Message-ID — rather than
+ * another operation.
+ */
+
+/** Mailboxes we never search: a copy of the message is not the message. */
+const SKIP_FLAGS = new Set(['\\trash', '\\junk']);
+
+export function mailboxAttachments(client: ImapClient): MailboxAttachmentSource {
+  return async ({ messageId, attachmentId }) =>
+    client.run(async (session) => {
+      const bytes = await findMessageBytes(session, messageId);
+      if (!bytes) {
+        throw new Error(
+          `No message with Message-ID ${messageId} in this account, so its attachment cannot be re-attached.`,
+        );
+      }
+
+      const mail = await PostalMime.parse(bytes);
+      const attachments = mail.attachments;
+
+      if (attachments.length === 0) {
+        throw new Error(`Message ${messageId} has no attachments.`);
+      }
+
+      const chosen = pick(attachments, attachmentId, messageId);
+
+      return {
+        bytes:
+          typeof chosen.content === 'string'
+            ? new TextEncoder().encode(chosen.content)
+            : new Uint8Array(chosen.content),
+        filename: chosen.filename ?? null,
+        contentType: chosen.mimeType ?? null,
+      };
+    });
+}
+
+type ParsedAttachment = Awaited<ReturnType<typeof PostalMime.parse>>['attachments'][number];
+
+/**
+ * Which of a message's attachments was meant.
+ *
+ * By filename, or by 1-based position, or — when the message carries exactly one
+ * — by there being no ambiguity to resolve. An unmatched name lists what is
+ * actually there, because the alternative is a caller guessing twice.
+ */
+function pick(
+  attachments: readonly ParsedAttachment[],
+  attachmentId: string | undefined,
+  messageId: string,
+): ParsedAttachment {
+  const names = attachments.map((entry, index) => entry.filename ?? `#${index + 1}`);
+
+  if (attachmentId === undefined) {
+    if (attachments.length === 1) return attachments[0]!;
+    throw new Error(
+      `Message ${messageId} has ${attachments.length} attachments, so attachment_id is needed. They are: ${names.join(', ')}.`,
+    );
+  }
+
+  const exact = attachments.find((entry) => entry.filename === attachmentId);
+  if (exact) return exact;
+
+  const insensitive = attachments.find(
+    (entry) => entry.filename?.toLowerCase() === attachmentId.toLowerCase(),
+  );
+  if (insensitive) return insensitive;
+
+  const position = Number(attachmentId);
+  if (Number.isInteger(position) && position >= 1 && position <= attachments.length) {
+    return attachments[position - 1]!;
+  }
+
+  throw new Error(
+    `Message ${messageId} has no attachment "${attachmentId}". They are: ${names.join(', ')}.`,
+  );
+}
+
+/** INBOX, then every other mailbox, until one holds this Message-ID. */
+async function findMessageBytes(
+  session: ImapSession,
+  messageId: string,
+): Promise<Uint8Array | null> {
+  for (const mailbox of await searchOrder(session)) {
+    const bytes = await fetchByMessageId(session, mailbox, messageId);
+    if (bytes) return bytes;
+  }
+  return null;
+}
+
+async function searchOrder(session: ImapSession): Promise<string[]> {
+  const result = await session.command('LIST "" "*"');
+
+  const mailboxes: string[] = [];
+  for (const tokens of result.untagged) {
+    if (asText(tokens[1]) !== 'LIST') continue;
+
+    const flags = tokens[2]?.kind === 'list' ? tokens[2].items : [];
+    if (flags.some((flag) => SKIP_FLAGS.has(asText(flag)?.toLowerCase() ?? ''))) continue;
+    // `\Noselect` names a folder that only holds other folders; EXAMINE fails on
+    // it, which would abort the walk before reaching the mailbox we want.
+    if (flags.some((flag) => asText(flag)?.toLowerCase() === '\\noselect')) continue;
+
+    const name = decodeMailboxName(asText(tokens[4]) ?? '');
+    if (name) mailboxes.push(name);
+  }
+
+  const rest = mailboxes.filter((name) => name.toUpperCase() !== 'INBOX');
+  return ['INBOX', ...rest];
+}
+
+async function fetchByMessageId(
+  session: ImapSession,
+  mailbox: string,
+  messageId: string,
+): Promise<Uint8Array | null> {
+  try {
+    // EXAMINE and BODY.PEEK throughout: looking for something to attach must not
+    // mark mail as read, which is the same rule every read path here follows.
+    await session.command(`EXAMINE ${quoted(encodeMailboxName(mailbox))}`);
+  } catch {
+    return null;
+  }
+
+  // Angle brackets stripped because servers disagree about whether the stored
+  // header value includes them, and HEADER matching is a substring test.
+  const bare = messageId.replace(/^</, '').replace(/>$/, '');
+  const found = await session.command(`UID SEARCH HEADER MESSAGE-ID ${quoted(bare)}`);
+
+  const uid = found.untagged
+    .filter((tokens) => asText(tokens[1]) === 'SEARCH')
+    .flatMap((tokens) => tokens.slice(2).map((token) => Number(asText(token))))
+    .find((value) => Number.isFinite(value));
+
+  if (uid === undefined) return null;
+
+  const fetched = await session.command(`UID FETCH ${uid} (BODY.PEEK[])`);
+  const record = fetched.untagged.find(
+    (tokens) => asText(tokens[2]) === 'FETCH' && tokens[3]?.kind === 'list',
+  );
+  if (!record || record[3]?.kind !== 'list') return null;
+
+  const body = itemValue(record[3].items, 'BODY');
+  return body?.kind === 'literal' ? body.bytes : null;
+}

package/src/connectivity/transports/imap/capabilities.ts

@@ -0,0 +1,158 @@
+import { READ_BUNDLE, WRITE_BUNDLE, type DiscoveredCapability } from '#connectivity';
+import { attachmentsJsonSchema } from '#connectivity/mail';
+import {
+  OPERATIONS,
+  SETTABLE_FLAGS,
+  SPECIAL_USE_FLAGS,
+  mailboxArgument,
+  object,
+} from './operations.ts';
+
+/**
+ * What an IMAP connection exposes, as data.
+ *
+ * Fixed rather than discovered: IMAP describes its *extensions* through
+ * CAPABILITY but never its operations, so the set is RFC 3501's rather than the
+ * vendor's. Two of them are conditional — `MOVE` is an extension a server may
+ * not have, and sending needs an SMTP block in the manifest.
+ */
+export function imapCapabilities(input: {
+  readonly supportsMove: boolean;
+  readonly canSend: boolean;
+}): DiscoveredCapability[] {
+  const capabilities: DiscoveredCapability[] = [
+        {
+          name: OPERATIONS.listMailboxes,
+          description:
+            'List mailboxes (folders) in the account, with the flags that say what each is for.',
+          bundle: READ_BUNDLE,
+          inputSchema: object({
+            pattern: {
+              type: 'string',
+              default: '*',
+              description: 'IMAP LIST pattern — "*" for everything, "INBOX/*" for one subtree.',
+            },
+          }),
+          target: { operation: OPERATIONS.listMailboxes },
+        },
+        {
+          name: OPERATIONS.searchMessages,
+          description:
+            'Search a mailbox and return message summaries, most recent first. Reading does not mark anything as read.',
+          bundle: READ_BUNDLE,
+          inputSchema: object({
+            mailbox: mailboxArgument,
+            from: { type: 'string', description: 'Substring of the From header.' },
+            to: { type: 'string', description: 'Substring of the To header.' },
+            subject: { type: 'string', description: 'Substring of the Subject header.' },
+            text: { type: 'string', description: 'Substring of headers or body.' },
+            since: { type: 'string', description: 'On or after this date (YYYY-MM-DD).' },
+            before: { type: 'string', description: 'Before this date (YYYY-MM-DD).' },
+            unseen: { type: 'boolean', description: 'Only messages not yet read.' },
+            flagged: { type: 'boolean', description: 'Only flagged messages.' },
+            limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
+          }),
+          target: { operation: OPERATIONS.searchMessages },
+        },
+        {
+          name: OPERATIONS.getMessage,
+          description:
+            'Fetch one message in full: headers, body text, and a list of its attachments. Does not mark it read.',
+          bundle: READ_BUNDLE,
+          inputSchema: object(
+            {
+              mailbox: mailboxArgument,
+              uid: { type: 'integer', description: 'UID as search_messages reports it.' },
+              include_body: { type: 'boolean', default: true },
+            },
+            ['uid'],
+          ),
+          target: { operation: OPERATIONS.getMessage },
+        },
+        {
+          name: OPERATIONS.markMessages,
+          description: 'Add or remove flags on messages — read, flagged, answered, draft.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object(
+            {
+              mailbox: mailboxArgument,
+              uids: { type: 'array', items: { type: 'integer' }, minItems: 1, maxItems: 200 },
+              add_flags: { type: 'array', items: { enum: [...SETTABLE_FLAGS] } },
+              remove_flags: { type: 'array', items: { enum: [...SETTABLE_FLAGS] } },
+            },
+            ['uids'],
+          ),
+          target: { operation: OPERATIONS.markMessages },
+        },
+      ];
+
+
+  if (input.supportsMove) {
+        capabilities.push({
+          name: OPERATIONS.moveMessages,
+          description:
+            'Move messages to another mailbox — archiving, filing, or marking as junk. ' +
+            'Give either destination (an exact name from list_mailboxes) or destination_flag, ' +
+            'never both. Prefer the flag: mailbox names are localised and vary by provider, ' +
+            'so destination_flag: "\\Junk" is how a message is reported as junk portably.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object(
+            {
+              mailbox: mailboxArgument,
+              uids: { type: 'array', items: { type: 'integer' }, minItems: 1, maxItems: 200 },
+              destination: { type: 'string', description: 'Target mailbox, by exact name.' },
+              destination_flag: {
+                type: 'string',
+                enum: [...SPECIAL_USE_FLAGS],
+                description:
+                  'Target mailbox by its RFC 6154 special-use attribute, resolved against ' +
+                  'what the server advertises. Survives a mailbox being named Spam, Junk, or ' +
+                  'Junk E-mail.',
+              },
+            },
+            // `destination` is no longer required, because `destination_flag`
+            // satisfies the same need; the handler refuses neither-and-both.
+            // JSON Schema could express that with `oneOf`, and does not here:
+            // `sanitizeSchema` flattens what it does not recognise, and a
+            // constraint that survives to some clients and not others is worse
+            // than one enforced in exactly one place.
+            ['uids'],
+          ),
+          target: { operation: OPERATIONS.moveMessages },
+        });
+      }
+
+
+  if (input.canSend) {
+        capabilities.push({
+          name: OPERATIONS.sendMessage,
+          description:
+            'Send a message, with attachments, filing a copy in the Sent mailbox. Attachments are named by reference — a path, an HTTPS URL, or another message in this mailbox — and this endpoint reads the bytes itself, so never encode a file into the call.',
+          bundle: WRITE_BUNDLE,
+          inputSchema: object(
+            {
+              to: { type: 'array', items: { type: 'string' }, minItems: 1 },
+              cc: { type: 'array', items: { type: 'string' } },
+              bcc: { type: 'array', items: { type: 'string' } },
+              subject: { type: 'string' },
+              text: { type: 'string' },
+              html: { type: 'string' },
+              in_reply_to: {
+                type: 'string',
+                description: 'Message-ID being replied to, which threads the reply.',
+              },
+              from_name: {
+                type: 'string',
+                description:
+                  "Name to show beside the address, e.g. \"Ada Lovelace\". Defaults to this connection's from_name; without either, recipients see a bare address.",
+              },
+              attachments: attachmentsJsonSchema,
+            },
+            ['to', 'subject'],
+          ),
+          target: { operation: OPERATIONS.sendMessage },
+        });
+      }
+
+  return capabilities;
+}