@deimoscloud/coreai 0.1.0

package/src/adapters/mcp/mapper.ts

@@ -0,0 +1,536 @@
+/**
+ * MCP Tool Mapper
+ *
+ * Maps MCP server tools to adapter interface methods.
+ * Provides both pre-defined mappings for known servers and
+ * heuristic-based auto-discovery for unknown servers.
+ */
+
+import type { AdapterType } from '../types.js';
+import type { McpTool } from './types.js';
+
+/**
+ * Mapping from an MCP tool to an adapter method
+ */
+export interface ToolMapping {
+  /**
+   * The MCP tool name
+   */
+  toolName: string;
+
+  /**
+   * The adapter type this tool maps to
+   */
+  adapterType: AdapterType;
+
+  /**
+   * The adapter method this tool implements
+   */
+  method: string;
+
+  /**
+   * Parameter mapping from adapter method params to MCP tool args
+   */
+  parameterMap?: Record<string, string>;
+
+  /**
+   * How to extract the result from the MCP tool response
+   */
+  resultExtractor?: (result: unknown) => unknown;
+
+  /**
+   * Confidence score (0-1) for auto-discovered mappings
+   */
+  confidence?: number;
+}
+
+/**
+ * Registry of known MCP server tool mappings
+ */
+export interface ServerMapping {
+  /**
+   * Server identifier patterns (name or npm package)
+   */
+  patterns: string[];
+
+  /**
+   * Tool mappings for this server
+   */
+  mappings: ToolMapping[];
+}
+
+/**
+ * Known server mappings registry
+ */
+const KNOWN_SERVER_MAPPINGS: ServerMapping[] = [
+  // GitHub MCP Server (@modelcontextprotocol/server-github)
+  {
+    patterns: ['@modelcontextprotocol/server-github', 'github', 'mcp-server-github'],
+    mappings: [
+      // Git Provider mappings
+      {
+        toolName: 'create_pull_request',
+        adapterType: 'git',
+        method: 'createPullRequest',
+        parameterMap: {
+          title: 'title',
+          body: 'description',
+          head: 'source_branch',
+          base: 'target_branch',
+        },
+      },
+      {
+        toolName: 'get_pull_request',
+        adapterType: 'git',
+        method: 'getPullRequest',
+        parameterMap: {
+          pull_number: 'idOrNumber',
+        },
+      },
+      {
+        toolName: 'list_pull_requests',
+        adapterType: 'git',
+        method: 'listPullRequests',
+        parameterMap: {
+          state: 'status',
+        },
+      },
+      {
+        toolName: 'merge_pull_request',
+        adapterType: 'git',
+        method: 'mergePullRequest',
+        parameterMap: {
+          pull_number: 'idOrNumber',
+        },
+      },
+      {
+        toolName: 'create_review',
+        adapterType: 'git',
+        method: 'addReview',
+        parameterMap: {
+          pull_number: 'idOrNumber',
+          event: 'decision',
+          body: 'body',
+        },
+      },
+      // Issue Tracker mappings (GitHub Issues)
+      {
+        toolName: 'get_issue',
+        adapterType: 'issue_tracker',
+        method: 'getIssue',
+        parameterMap: {
+          issue_number: 'idOrKey',
+        },
+      },
+      {
+        toolName: 'list_issues',
+        adapterType: 'issue_tracker',
+        method: 'listIssues',
+        parameterMap: {
+          state: 'status',
+          assignee: 'assignee',
+          labels: 'labels',
+        },
+      },
+      {
+        toolName: 'create_issue',
+        adapterType: 'issue_tracker',
+        method: 'createIssue',
+        parameterMap: {
+          title: 'title',
+          body: 'description',
+          assignees: 'assignee',
+          labels: 'labels',
+        },
+      },
+      {
+        toolName: 'update_issue',
+        adapterType: 'issue_tracker',
+        method: 'updateIssue',
+        parameterMap: {
+          issue_number: 'idOrKey',
+          title: 'title',
+          body: 'description',
+          state: 'status',
+        },
+      },
+      {
+        toolName: 'add_issue_comment',
+        adapterType: 'issue_tracker',
+        method: 'addComment',
+        parameterMap: {
+          issue_number: 'idOrKey',
+          body: 'comment',
+        },
+      },
+    ],
+  },
+
+  // Jira MCP Server (if available)
+  {
+    patterns: ['jira', 'mcp-server-jira', 'atlassian-jira'],
+    mappings: [
+      {
+        toolName: 'get_issue',
+        adapterType: 'issue_tracker',
+        method: 'getIssue',
+        parameterMap: {
+          issue_key: 'idOrKey',
+        },
+      },
+      {
+        toolName: 'search_issues',
+        adapterType: 'issue_tracker',
+        method: 'listIssues',
+      },
+      {
+        toolName: 'create_issue',
+        adapterType: 'issue_tracker',
+        method: 'createIssue',
+        parameterMap: {
+          summary: 'title',
+          description: 'description',
+        },
+      },
+      {
+        toolName: 'update_issue',
+        adapterType: 'issue_tracker',
+        method: 'updateIssue',
+        parameterMap: {
+          issue_key: 'idOrKey',
+          summary: 'title',
+          description: 'description',
+        },
+      },
+      {
+        toolName: 'transition_issue',
+        adapterType: 'issue_tracker',
+        method: 'transitionIssue',
+        parameterMap: {
+          issue_key: 'idOrKey',
+          transition_id: 'status',
+        },
+      },
+      {
+        toolName: 'add_comment',
+        adapterType: 'issue_tracker',
+        method: 'addComment',
+        parameterMap: {
+          issue_key: 'idOrKey',
+          body: 'comment',
+        },
+      },
+    ],
+  },
+
+  // Confluence MCP Server (if available)
+  {
+    patterns: ['confluence', 'mcp-server-confluence', 'atlassian-confluence'],
+    mappings: [
+      {
+        toolName: 'get_page',
+        adapterType: 'documentation',
+        method: 'getPage',
+        parameterMap: {
+          page_id: 'id',
+        },
+      },
+      {
+        toolName: 'get_page_content',
+        adapterType: 'documentation',
+        method: 'getPageContent',
+        parameterMap: {
+          page_id: 'id',
+        },
+      },
+      {
+        toolName: 'search_pages',
+        adapterType: 'documentation',
+        method: 'searchPages',
+        parameterMap: {
+          query: 'query',
+          space_key: 'space',
+        },
+      },
+    ],
+  },
+
+  // Filesystem MCP Server
+  {
+    patterns: ['filesystem', 'mcp-server-filesystem', '@modelcontextprotocol/server-filesystem'],
+    mappings: [
+      {
+        toolName: 'read_file',
+        adapterType: 'state',
+        method: 'read',
+        parameterMap: {
+          path: 'path',
+        },
+      },
+      {
+        toolName: 'write_file',
+        adapterType: 'state',
+        method: 'write',
+        parameterMap: {
+          path: 'path',
+          content: 'content',
+        },
+      },
+      {
+        toolName: 'list_directory',
+        adapterType: 'state',
+        method: 'list',
+        parameterMap: {
+          path: 'path',
+        },
+      },
+      {
+        toolName: 'create_directory',
+        adapterType: 'state',
+        method: 'mkdir',
+        parameterMap: {
+          path: 'path',
+        },
+      },
+    ],
+  },
+];
+
+/**
+ * Find mappings for a known server
+ */
+export function findKnownServerMappings(serverName: string): ToolMapping[] {
+  const normalizedName = serverName.toLowerCase();
+
+  for (const server of KNOWN_SERVER_MAPPINGS) {
+    for (const pattern of server.patterns) {
+      if (
+        normalizedName.includes(pattern.toLowerCase()) ||
+        pattern.toLowerCase().includes(normalizedName)
+      ) {
+        return server.mappings;
+      }
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Auto-discover mappings for tools based on naming conventions
+ */
+export function autoDiscoverMappings(tools: McpTool[]): ToolMapping[] {
+  const mappings: ToolMapping[] = [];
+
+  for (const tool of tools) {
+    const discovered = discoverToolMapping(tool);
+    if (discovered) {
+      mappings.push(discovered);
+    }
+  }
+
+  return mappings;
+}
+
+/**
+ * Try to discover a mapping for a single tool
+ */
+function discoverToolMapping(tool: McpTool): ToolMapping | null {
+  const name = tool.name.toLowerCase();
+  const desc = (tool.description ?? '').toLowerCase();
+
+  // Issue tracker patterns
+  if (matchesPatterns(name, desc, ['issue', 'ticket', 'bug', 'task'])) {
+    return discoverIssueTrackerMapping(tool);
+  }
+
+  // Git provider patterns
+  if (matchesPatterns(name, desc, ['pull_request', 'pr', 'merge', 'branch', 'commit', 'review'])) {
+    return discoverGitMapping(tool);
+  }
+
+  // Documentation patterns
+  if (matchesPatterns(name, desc, ['page', 'doc', 'wiki', 'content', 'article'])) {
+    return discoverDocumentationMapping(tool);
+  }
+
+  // State/filesystem patterns
+  if (matchesPatterns(name, desc, ['file', 'directory', 'folder', 'read', 'write', 'path'])) {
+    return discoverStateMapping(tool);
+  }
+
+  return null;
+}
+
+/**
+ * Check if name or description matches any patterns
+ */
+function matchesPatterns(name: string, description: string, patterns: string[]): boolean {
+  return patterns.some((p) => name.includes(p) || description.includes(p));
+}
+
+/**
+ * Discover issue tracker mapping
+ */
+function discoverIssueTrackerMapping(tool: McpTool): ToolMapping | null {
+  const name = tool.name.toLowerCase();
+
+  const methodPatterns: Record<string, string> = {
+    get_issue: 'getIssue',
+    get_ticket: 'getIssue',
+    list_issues: 'listIssues',
+    search_issues: 'listIssues',
+    create_issue: 'createIssue',
+    create_ticket: 'createIssue',
+    update_issue: 'updateIssue',
+    transition_issue: 'transitionIssue',
+    move_issue: 'transitionIssue',
+    add_comment: 'addComment',
+    comment_issue: 'addComment',
+  };
+
+  for (const [pattern, method] of Object.entries(methodPatterns)) {
+    if (name.includes(pattern) || name === pattern.replace(/_/g, '')) {
+      return {
+        toolName: tool.name,
+        adapterType: 'issue_tracker',
+        method,
+        confidence: 0.7,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Discover git provider mapping
+ */
+function discoverGitMapping(tool: McpTool): ToolMapping | null {
+  const name = tool.name.toLowerCase();
+
+  const methodPatterns: Record<string, string> = {
+    get_pull_request: 'getPullRequest',
+    get_pr: 'getPullRequest',
+    list_pull_requests: 'listPullRequests',
+    list_prs: 'listPullRequests',
+    create_pull_request: 'createPullRequest',
+    create_pr: 'createPullRequest',
+    merge_pull_request: 'mergePullRequest',
+    merge_pr: 'mergePullRequest',
+    add_review: 'addReview',
+    create_review: 'addReview',
+    request_reviewers: 'requestReviewers',
+  };
+
+  for (const [pattern, method] of Object.entries(methodPatterns)) {
+    if (name.includes(pattern) || name === pattern.replace(/_/g, '')) {
+      return {
+        toolName: tool.name,
+        adapterType: 'git',
+        method,
+        confidence: 0.7,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Discover documentation provider mapping
+ */
+function discoverDocumentationMapping(tool: McpTool): ToolMapping | null {
+  const name = tool.name.toLowerCase();
+
+  const methodPatterns: Record<string, string> = {
+    get_page: 'getPage',
+    get_doc: 'getPage',
+    get_page_content: 'getPageContent',
+    get_content: 'getPageContent',
+    search_pages: 'searchPages',
+    search_docs: 'searchPages',
+    list_pages: 'listPages',
+  };
+
+  for (const [pattern, method] of Object.entries(methodPatterns)) {
+    if (name.includes(pattern) || name === pattern.replace(/_/g, '')) {
+      return {
+        toolName: tool.name,
+        adapterType: 'documentation',
+        method,
+        confidence: 0.7,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Discover state provider mapping
+ */
+function discoverStateMapping(tool: McpTool): ToolMapping | null {
+  const name = tool.name.toLowerCase();
+
+  const methodPatterns: Record<string, string> = {
+    read_file: 'read',
+    read: 'read',
+    get_file: 'read',
+    write_file: 'write',
+    write: 'write',
+    save_file: 'write',
+    list_directory: 'list',
+    list_files: 'list',
+    ls: 'list',
+    delete_file: 'delete',
+    remove_file: 'delete',
+    create_directory: 'mkdir',
+    mkdir: 'mkdir',
+  };
+
+  for (const [pattern, method] of Object.entries(methodPatterns)) {
+    if (name.includes(pattern) || name === pattern.replace(/_/g, '')) {
+      return {
+        toolName: tool.name,
+        adapterType: 'state',
+        method,
+        confidence: 0.7,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all mappings for a server (known + auto-discovered)
+ */
+export function getMappingsForServer(serverName: string, tools: McpTool[]): ToolMapping[] {
+  // First try known mappings
+  const knownMappings = findKnownServerMappings(serverName);
+
+  if (knownMappings.length > 0) {
+    // Filter to only tools that exist
+    const toolNames = new Set(tools.map((t) => t.name));
+    return knownMappings.filter((m) => toolNames.has(m.toolName));
+  }
+
+  // Fall back to auto-discovery
+  return autoDiscoverMappings(tools);
+}
+
+/**
+ * Group mappings by adapter type
+ */
+export function groupMappingsByAdapter(mappings: ToolMapping[]): Map<AdapterType, ToolMapping[]> {
+  const grouped = new Map<AdapterType, ToolMapping[]>();
+
+  for (const mapping of mappings) {
+    const existing = grouped.get(mapping.adapterType) ?? [];
+    existing.push(mapping);
+    grouped.set(mapping.adapterType, existing);
+  }
+
+  return grouped;
+}