@tryfinch/finch-api-mcp 6.26.0 → 6.28.0

package/src/compat.ts

@@ -0,0 +1,429 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Endpoint } from './tools';
+
+export interface ClientCapabilities {
+  topLevelUnions: boolean;
+  validJson: boolean;
+  refs: boolean;
+  unions: boolean;
+  formats: boolean;
+  toolNameLength: number | undefined;
+}
+
+export const defaultClientCapabilities: ClientCapabilities = {
+  topLevelUnions: true,
+  validJson: true,
+  refs: true,
+  unions: true,
+  formats: true,
+  toolNameLength: undefined,
+};
+
+/**
+ * Attempts to parse strings into JSON objects
+ */
+export function parseEmbeddedJSON(args: Record<string, unknown>, schema: Record<string, unknown>) {
+  let updated = false;
+  const newArgs: Record<string, unknown> = Object.assign({}, args);
+
+  for (const [key, value] of Object.entries(newArgs)) {
+    if (typeof value === 'string') {
+      try {
+        const parsed = JSON.parse(value);
+        newArgs[key] = parsed;
+        updated = true;
+      } catch (e) {
+        // Not valid JSON, leave as is
+      }
+    }
+  }
+
+  if (updated) {
+    return newArgs;
+  }
+
+  return args;
+}
+
+export type JSONSchema = {
+  type?: string;
+  properties?: Record<string, JSONSchema>;
+  required?: string[];
+  anyOf?: JSONSchema[];
+  $ref?: string;
+  $defs?: Record<string, JSONSchema>;
+  [key: string]: any;
+};
+
+/**
+ * Truncates tool names to the specified length while ensuring uniqueness.
+ * If truncation would cause duplicate names, appends a number to make them unique.
+ */
+export function truncateToolNames(names: string[], maxLength: number): Map<string, string> {
+  if (maxLength <= 0) {
+    return new Map();
+  }
+
+  const renameMap = new Map<string, string>();
+  const usedNames = new Set<string>();
+
+  const toTruncate = names.filter((name) => name.length > maxLength);
+
+  if (toTruncate.length === 0) {
+    return renameMap;
+  }
+
+  const willCollide =
+    new Set(toTruncate.map((name) => name.slice(0, maxLength - 1))).size < toTruncate.length;
+
+  if (!willCollide) {
+    for (const name of toTruncate) {
+      const truncatedName = name.slice(0, maxLength);
+      renameMap.set(name, truncatedName);
+    }
+  } else {
+    const baseLength = maxLength - 1;
+
+    for (const name of toTruncate) {
+      const baseName = name.slice(0, baseLength);
+      let counter = 1;
+
+      while (usedNames.has(baseName + counter)) {
+        counter++;
+      }
+
+      const finalName = baseName + counter;
+      renameMap.set(name, finalName);
+      usedNames.add(finalName);
+    }
+  }
+
+  return renameMap;
+}
+
+/**
+ * Removes top-level unions from a tool by splitting it into multiple tools,
+ * one for each variant in the union.
+ */
+export function removeTopLevelUnions(tool: Tool): Tool[] {
+  const inputSchema = tool.inputSchema as JSONSchema;
+  const variants = inputSchema.anyOf;
+
+  if (!variants || !Array.isArray(variants) || variants.length === 0) {
+    return [tool];
+  }
+
+  const defs = inputSchema.$defs || {};
+
+  return variants.map((variant, index) => {
+    const variantSchema: JSONSchema = {
+      ...inputSchema,
+      ...variant,
+      type: 'object',
+      properties: {
+        ...(inputSchema.properties || {}),
+        ...(variant.properties || {}),
+      },
+    };
+
+    delete variantSchema.anyOf;
+
+    if (!variantSchema['description']) {
+      variantSchema['description'] = tool.description;
+    }
+
+    const usedDefs = findUsedDefs(variant, defs);
+    if (Object.keys(usedDefs).length > 0) {
+      variantSchema.$defs = usedDefs;
+    } else {
+      delete variantSchema.$defs;
+    }
+
+    return {
+      ...tool,
+      name: `${tool.name}_${toSnakeCase(variant['title'] || `variant${index + 1}`)}`,
+      description: variant['description'] || tool.description,
+      inputSchema: variantSchema,
+    } as Tool;
+  });
+}
+
+function findUsedDefs(schema: JSONSchema, defs: Record<string, JSONSchema>): Record<string, JSONSchema> {
+  const usedDefs: Record<string, JSONSchema> = {};
+
+  if (typeof schema !== 'object' || schema === null) {
+    return usedDefs;
+  }
+
+  if (schema.$ref) {
+    const refParts = schema.$ref.split('/');
+    if (refParts[0] === '#' && refParts[1] === '$defs' && refParts[2]) {
+      const defName = refParts[2];
+      const def = defs[defName];
+      if (def) {
+        usedDefs[defName] = def;
+        Object.assign(usedDefs, findUsedDefs(def, defs));
+      }
+    }
+    return usedDefs;
+  }
+
+  for (const key in schema) {
+    if (key !== '$defs' && typeof schema[key] === 'object' && schema[key] !== null) {
+      Object.assign(usedDefs, findUsedDefs(schema[key] as JSONSchema, defs));
+    }
+  }
+
+  return usedDefs;
+}
+
+/**
+ * Inlines all $refs in a schema, eliminating $defs.
+ * If a circular reference is detected, the circular property is removed.
+ */
+export function inlineRefs(schema: JSONSchema): JSONSchema {
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+
+  const clonedSchema = { ...schema };
+  const defs: Record<string, JSONSchema> = schema.$defs || {};
+
+  delete clonedSchema.$defs;
+
+  const result = inlineRefsRecursive(clonedSchema, defs, new Set<string>());
+  // The top level can never be null
+  return result === null ? {} : result;
+}
+
+function inlineRefsRecursive(
+  schema: JSONSchema,
+  defs: Record<string, JSONSchema>,
+  refPath: Set<string>,
+): JSONSchema | null {
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map((item) => {
+      const processed = inlineRefsRecursive(item, defs, refPath);
+      return processed === null ? {} : processed;
+    }) as JSONSchema;
+  }
+
+  const result = { ...schema };
+
+  if ('$ref' in result && typeof result.$ref === 'string') {
+    if (result.$ref.startsWith('#/$defs/')) {
+      const refName = result.$ref.split('/').pop() as string;
+      const def = defs[refName];
+
+      // If we've already seen this ref in our path, we have a circular reference
+      if (refPath.has(result.$ref)) {
+        // For circular references, we completely remove the property
+        // by returning null. The parent will remove it.
+        return null;
+      }
+
+      if (def) {
+        const newRefPath = new Set(refPath);
+        newRefPath.add(result.$ref);
+
+        const inlinedDef = inlineRefsRecursive({ ...def }, defs, newRefPath);
+
+        if (inlinedDef === null) {
+          return { ...result };
+        }
+
+        // Merge the inlined definition with the original schema's properties
+        // but preserve things like description, etc.
+        const { $ref, ...rest } = result;
+        return { ...inlinedDef, ...rest };
+      }
+    }
+
+    // Keep external refs as-is
+    return result;
+  }
+
+  for (const key in result) {
+    if (result[key] && typeof result[key] === 'object') {
+      const processed = inlineRefsRecursive(result[key] as JSONSchema, defs, refPath);
+      if (processed === null) {
+        // Remove properties that would cause circular references
+        delete result[key];
+      } else {
+        result[key] = processed;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Removes anyOf fields from a schema, using only the first variant.
+ */
+export function removeAnyOf(schema: JSONSchema): JSONSchema {
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map((item) => removeAnyOf(item)) as JSONSchema;
+  }
+
+  const result = { ...schema };
+
+  if ('anyOf' in result && Array.isArray(result.anyOf) && result.anyOf.length > 0) {
+    const firstVariant = result.anyOf[0];
+
+    if (firstVariant && typeof firstVariant === 'object') {
+      // Special handling for properties to ensure deep merge
+      if (firstVariant.properties && result.properties) {
+        result.properties = {
+          ...result.properties,
+          ...(firstVariant.properties as Record<string, JSONSchema>),
+        };
+      } else if (firstVariant.properties) {
+        result.properties = { ...firstVariant.properties };
+      }
+
+      for (const key in firstVariant) {
+        if (key !== 'properties') {
+          result[key] = firstVariant[key];
+        }
+      }
+    }
+
+    delete result.anyOf;
+  }
+
+  for (const key in result) {
+    if (result[key] && typeof result[key] === 'object') {
+      result[key] = removeAnyOf(result[key] as JSONSchema);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Removes format fields from a schema and appends them to the description.
+ */
+export function removeFormats(schema: JSONSchema, formatsCapability: boolean): JSONSchema {
+  if (formatsCapability) {
+    return schema;
+  }
+
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+
+  if (Array.isArray(schema)) {
+    return schema.map((item) => removeFormats(item, formatsCapability)) as JSONSchema;
+  }
+
+  const result = { ...schema };
+
+  if ('format' in result && typeof result['format'] === 'string') {
+    const formatStr = `(format: "${result['format']}")`;
+
+    if ('description' in result && typeof result['description'] === 'string') {
+      result['description'] = `${result['description']} ${formatStr}`;
+    } else {
+      result['description'] = formatStr;
+    }
+
+    delete result['format'];
+  }
+
+  for (const key in result) {
+    if (result[key] && typeof result[key] === 'object') {
+      result[key] = removeFormats(result[key] as JSONSchema, formatsCapability);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Applies all compatibility transformations to the endpoints based on the provided capabilities.
+ */
+export function applyCompatibilityTransformations(
+  endpoints: Endpoint[],
+  capabilities: ClientCapabilities,
+): Endpoint[] {
+  let transformedEndpoints = [...endpoints];
+
+  // Handle top-level unions first as this changes tool names
+  if (!capabilities.topLevelUnions) {
+    const newEndpoints: Endpoint[] = [];
+
+    for (const endpoint of transformedEndpoints) {
+      const variantTools = removeTopLevelUnions(endpoint.tool);
+
+      if (variantTools.length === 1) {
+        newEndpoints.push(endpoint);
+      } else {
+        for (const variantTool of variantTools) {
+          newEndpoints.push({
+            ...endpoint,
+            tool: variantTool,
+          });
+        }
+      }
+    }
+
+    transformedEndpoints = newEndpoints;
+  }
+
+  if (capabilities.toolNameLength) {
+    const toolNames = transformedEndpoints.map((endpoint) => endpoint.tool.name);
+    const renameMap = truncateToolNames(toolNames, capabilities.toolNameLength);
+
+    transformedEndpoints = transformedEndpoints.map((endpoint) => ({
+      ...endpoint,
+      tool: {
+        ...endpoint.tool,
+        name: renameMap.get(endpoint.tool.name) ?? endpoint.tool.name,
+      },
+    }));
+  }
+
+  if (!capabilities.refs || !capabilities.unions || !capabilities.formats) {
+    transformedEndpoints = transformedEndpoints.map((endpoint) => {
+      let schema = endpoint.tool.inputSchema as JSONSchema;
+
+      if (!capabilities.refs) {
+        schema = inlineRefs(schema);
+      }
+
+      if (!capabilities.unions) {
+        schema = removeAnyOf(schema);
+      }
+
+      if (!capabilities.formats) {
+        schema = removeFormats(schema, capabilities.formats);
+      }
+
+      return {
+        ...endpoint,
+        tool: {
+          ...endpoint.tool,
+          inputSchema: schema as typeof endpoint.tool.inputSchema,
+        },
+      };
+    });
+  }
+
+  return transformedEndpoints;
+}
+
+function toSnakeCase(str: string): string {
+  return str
+    .replace(/\s+/g, '_')
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+}

package/src/index.ts

@@ -1,115 +1,28 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
 import { init, server } from './server';
-import { endpoints, Filter, query } from './tools';
+import { Endpoint, endpoints, Filter, query } from './tools';
+import { applyCompatibilityTransformations } from './compat';
+import { parseOptions } from './options';
 
 async function main() {
-  const opts = yargs(hideBin(process.argv))
-    .option('tool', {
-      type: 'string',
-      array: true,
-      description: 'Include tools matching the specified names',
-    })
-    .option('resource', {
-      type: 'string',
-      array: true,
-      description: 'Include tools matching the specified resources',
-    })
-    .option('operation', {
-      type: 'string',
-      array: true,
-      choices: ['read', 'write'],
-      description: 'Include tools matching the specified operations',
-    })
-    .option('tag', {
-      type: 'string',
-      array: true,
-      description: 'Include tools with the specified tags',
-    })
-    .option('no-tool', {
-      type: 'string',
-      array: true,
-      description: 'Exclude tools matching the specified names',
-    })
-    .option('no-resource', {
-      type: 'string',
-      array: true,
-      description: 'Exclude tools matching the specified resources',
-    })
-    .option('no-operation', {
-      type: 'string',
-      array: true,
-      description: 'Exclude tools matching the specified operations',
-    })
-    .option('no-tag', {
-      type: 'string',
-      array: true,
-      description: 'Exclude tools with the specified tags',
-    })
-    .option('list', {
-      type: 'boolean',
-      description: 'List all tools and exit',
-    })
-    .help();
-
-  for (const [command, desc] of examples()) {
-    opts.example(command, desc);
-  }
-
-  const argv = opts.parseSync();
+  const { filters, capabilities, list } = parseOptionsOrError();
 
-  if (argv.list) {
+  if (list) {
     listAllTools();
     return;
   }
-  const filters: Filter[] = [];
-
-  for (const tag of argv.tag || []) {
-    filters.push({ type: 'tag', op: 'include', value: tag });
-  }
-
-  for (const tag of argv.noTag || []) {
-    filters.push({ type: 'tag', op: 'exclude', value: tag });
-  }
-
-  for (const resource of argv.resource || []) {
-    filters.push({ type: 'resource', op: 'include', value: resource });
-  }
-
-  for (const resource of argv.noResource || []) {
-    filters.push({ type: 'resource', op: 'exclude', value: resource });
-  }
-
-  for (const tool of argv.tool || []) {
-    filters.push({ type: 'tool', op: 'include', value: tool });
-  }
-
-  for (const tool of argv.noTool || []) {
-    filters.push({ type: 'tool', op: 'exclude', value: tool });
-  }
-
-  for (const operation of argv.operation || []) {
-    filters.push({ type: 'operation', op: 'include', value: operation });
-  }
 
-  for (const operation of argv.noOperation || []) {
-    filters.push({ type: 'operation', op: 'exclude', value: operation });
-  }
-
-  const filteredEndpoints = query(filters, endpoints);
+  const filteredEndpoints = filterEndpointsOrError(filters, endpoints);
 
-  if (filteredEndpoints.length === 0) {
-    console.error('No tools match the provided filters.');
-    process.exit(1);
-  }
+  // Apply compatibility transformations
+  const transformedEndpoints = applyCompatibilityTransformations(filteredEndpoints, capabilities);
 
   console.error(
-    `MCP Server starting with ${filteredEndpoints.length} tools:`,
-    filteredEndpoints.map((e) => e.tool.name),
+    `MCP Server starting with ${transformedEndpoints.length} tools:`,
+    transformedEndpoints.map((e) => e.tool.name),
   );
 
-  init({ server, endpoints: filteredEndpoints });
+  init({ server, endpoints: transformedEndpoints });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -123,6 +36,33 @@ if (require.main === module) {
   });
 }
 
+function parseOptionsOrError() {
+  try {
+    return parseOptions();
+  } catch (error) {
+    console.error('Error parsing options:', error);
+    process.exit(1);
+  }
+}
+
+function filterEndpointsOrError(filters: Filter[], endpoints: Endpoint[]) {
+  try {
+    const filteredEndpoints = query(filters, endpoints);
+    if (filteredEndpoints.length === 0) {
+      console.error('No tools match the provided filters.');
+      process.exit(1);
+    }
+    return filteredEndpoints;
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Error filtering tools:', error.message);
+    } else {
+      console.error('Error filtering tools:', error);
+    }
+    process.exit(1);
+  }
+}
+
 function listAllTools() {
   if (endpoints.length === 0) {
     console.error('No tools available.');
@@ -164,27 +104,3 @@ function listAllTools() {
     console.error('');
   }
 }
-
-function examples(): [string, string][] {
-  const firstEndpoint = endpoints[0]!;
-  const secondEndpoint =
-    endpoints.find((e) => e.metadata.resource !== firstEndpoint.metadata.resource) || endpoints[1];
-  const tag = endpoints.find((e) => e.metadata.tags.length > 0)?.metadata.tags[0];
-  const otherEndpoint = secondEndpoint || firstEndpoint;
-
-  return [
-    [
-      `--tool="${firstEndpoint.tool.name}" ${secondEndpoint ? `--tool="${secondEndpoint.tool.name}"` : ''}`,
-      'Include tools by name',
-    ],
-    [
-      `--resource="${firstEndpoint.metadata.resource}" --operation="read"`,
-      'Filter by resource and operation',
-    ],
-    [
-      `--resource="${otherEndpoint.metadata.resource}*" --no-tool="${otherEndpoint.tool.name}"`,
-      'Use resource wildcards and exclusions',
-    ],
-    ...(tag ? [[`--tag="${tag}"`, 'Filter based on tags'] as [string, string]] : []),
-  ];
-}