@langchain/openai
Version:
OpenAI integrations for LangChain.js
1 lines • 9.21 kB
Source Map (JSON)
{"version":3,"file":"mcp.cjs","names":["filter: McpToolFilter","allowedTools: string[] | McpToolFilter | undefined","requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined","options: McpRemoteServerOptions | McpConnectorOptions","baseConfig: McpTool"],"sources":["../../src/tools/mcp.ts"],"sourcesContent":["import { OpenAI as OpenAIClient } from \"openai\";\nimport type { ServerTool } from \"@langchain/core/tools\";\n\n/**\n * Available connector IDs for OpenAI's built-in service connectors.\n * These are OpenAI-maintained MCP wrappers for popular services.\n */\nexport type McpConnectorId =\n | \"connector_dropbox\"\n | \"connector_gmail\"\n | \"connector_googlecalendar\"\n | \"connector_googledrive\"\n | \"connector_microsoftteams\"\n | \"connector_outlookcalendar\"\n | \"connector_outlookemail\"\n | \"connector_sharepoint\";\n\n/**\n * Filter object to specify which tools are allowed.\n */\nexport interface McpToolFilter {\n /**\n * List of allowed tool names.\n */\n toolNames?: string[];\n /**\n * Indicates whether or not a tool modifies data or is read-only.\n * If an MCP server is annotated with `readOnlyHint`, it will match this filter.\n */\n readOnly?: boolean;\n}\n\n/**\n * Filter object for approval requirements.\n */\nexport interface McpApprovalFilter {\n /**\n * Tools that always require approval before execution.\n */\n always?: McpToolFilter;\n /**\n * Tools that never require approval.\n */\n never?: McpToolFilter;\n}\n\n/**\n * Base options shared between remote MCP servers and connectors.\n */\ninterface McpBaseOptions {\n /**\n * A label for this MCP server, used to identify it in tool calls.\n */\n serverLabel: string;\n /**\n * List of allowed tool names or a filter object.\n * Use this to limit which tools from the MCP server are available to the model.\n */\n allowedTools?: string[] | McpToolFilter;\n /**\n * An OAuth access token for authentication with the MCP server.\n * Your application must handle the OAuth authorization flow and provide the token here.\n */\n authorization?: string;\n /**\n * Optional HTTP headers to send to the MCP server.\n * Use for authentication or other purposes.\n */\n headers?: Record<string, string>;\n /**\n * Specify which of the MCP server's tools require approval before execution.\n * - `\"always\"`: All tools require approval\n * - `\"never\"`: No tools require approval\n * - `McpApprovalFilter`: Fine-grained control over which tools require approval\n *\n * @default \"always\" (approval required for all tools)\n */\n requireApproval?: \"always\" | \"never\" | McpApprovalFilter;\n /**\n * Optional description of the MCP server, used to provide more context to the model.\n */\n serverDescription?: string;\n}\n\n/**\n * Options for connecting to a remote MCP server via URL.\n */\nexport interface McpRemoteServerOptions extends McpBaseOptions {\n /**\n * The URL for the MCP server.\n * The server must implement the Streamable HTTP or HTTP/SSE transport protocol.\n */\n serverUrl: string;\n}\n\n/**\n * Options for connecting to an OpenAI-maintained service connector.\n */\nexport interface McpConnectorOptions extends McpBaseOptions {\n /**\n * Identifier for the service connector.\n * These are OpenAI-maintained MCP wrappers for popular services.\n *\n * Available connectors:\n * - `connector_dropbox`: Dropbox file access\n * - `connector_gmail`: Gmail email access\n * - `connector_googlecalendar`: Google Calendar access\n * - `connector_googledrive`: Google Drive file access\n * - `connector_microsoftteams`: Microsoft Teams access\n * - `connector_outlookcalendar`: Outlook Calendar access\n * - `connector_outlookemail`: Outlook Email access\n * - `connector_sharepoint`: SharePoint file access\n */\n connectorId: McpConnectorId;\n}\n\n/**\n * OpenAI MCP tool type for the Responses API.\n */\nexport type McpTool = OpenAIClient.Responses.Tool.Mcp;\n\n/**\n * Converts a McpToolFilter to the API format.\n */\nfunction convertToolFilter(\n filter: McpToolFilter\n): OpenAIClient.Responses.Tool.Mcp.McpToolFilter {\n return {\n tool_names: filter.toolNames,\n read_only: filter.readOnly,\n };\n}\n\n/**\n * Converts allowed_tools option to API format.\n */\nfunction convertAllowedTools(\n allowedTools: string[] | McpToolFilter | undefined\n): Array<string> | OpenAIClient.Responses.Tool.Mcp.McpToolFilter | undefined {\n if (!allowedTools) return undefined;\n if (Array.isArray(allowedTools)) return allowedTools;\n return convertToolFilter(allowedTools);\n}\n\n/**\n * Converts require_approval option to API format.\n */\nfunction convertRequireApproval(\n requireApproval: \"always\" | \"never\" | McpApprovalFilter | undefined\n):\n | OpenAIClient.Responses.Tool.Mcp.McpToolApprovalFilter\n | \"always\"\n | \"never\"\n | undefined {\n if (!requireApproval) return undefined;\n if (typeof requireApproval === \"string\") return requireApproval;\n return {\n always: requireApproval.always\n ? convertToolFilter(requireApproval.always)\n : undefined,\n never: requireApproval.never\n ? convertToolFilter(requireApproval.never)\n : undefined,\n };\n}\n\n/**\n * Creates an MCP tool that connects to a remote MCP server or OpenAI service connector.\n * This allows OpenAI models to access external tools and services via the Model Context Protocol.\n *\n * There are two ways to use MCP tools:\n * 1. **Remote MCP servers**: Connect to any server on the public Internet that implements\n * the MCP protocol using `serverUrl`.\n * 2. **Connectors**: Use OpenAI-maintained MCP wrappers for popular services like\n * Google Workspace or Dropbox using `connectorId`.\n *\n * @see {@link https://platform.openai.com/docs/guides/tools-remote-mcp | OpenAI MCP Documentation}\n *\n * @param options - Configuration options for the MCP tool\n * @returns An MCP tool definition to be passed to the OpenAI Responses API\n *\n * @example\n * ```typescript\n * import { ChatOpenAI, tools } from \"@langchain/openai\";\n *\n * const model = new ChatOpenAI({ model: \"gpt-4o\" });\n *\n * // Using a remote MCP server\n * const response = await model.invoke(\"Roll 2d4+1\", {\n * tools: [tools.mcp({\n * serverLabel: \"dmcp\",\n * serverDescription: \"A D&D MCP server for dice rolling\",\n * serverUrl: \"https://dmcp-server.deno.dev/sse\",\n * requireApproval: \"never\",\n * })],\n * });\n *\n * // Using a connector (e.g., Google Calendar)\n * const calendarResponse = await model.invoke(\"What's on my calendar today?\", {\n * tools: [tools.mcp({\n * serverLabel: \"google_calendar\",\n * connectorId: \"connector_googlecalendar\",\n * authorization: \"<oauth-access-token>\",\n * requireApproval: \"never\",\n * })],\n * });\n *\n * // With tool filtering - only allow specific tools\n * const filteredResponse = await model.invoke(\"Roll some dice\", {\n * tools: [tools.mcp({\n * serverLabel: \"dmcp\",\n * serverUrl: \"https://dmcp-server.deno.dev/sse\",\n * allowedTools: [\"roll\"], // Only allow the \"roll\" tool\n * requireApproval: \"never\",\n * })],\n * });\n *\n * // With fine-grained approval control\n * const controlledResponse = await model.invoke(\"Search and modify files\", {\n * tools: [tools.mcp({\n * serverLabel: \"deepwiki\",\n * serverUrl: \"https://mcp.deepwiki.com/mcp\",\n * requireApproval: {\n * never: { toolNames: [\"ask_question\", \"read_wiki_structure\"] },\n * // All other tools will require approval\n * },\n * })],\n * });\n * ```\n */\nexport function mcp(options: McpRemoteServerOptions): ServerTool;\nexport function mcp(options: McpConnectorOptions): ServerTool;\nexport function mcp(\n options: McpRemoteServerOptions | McpConnectorOptions\n): ServerTool {\n const baseConfig: McpTool = {\n type: \"mcp\",\n server_label: options.serverLabel,\n allowed_tools: convertAllowedTools(options.allowedTools),\n authorization: options.authorization,\n headers: options.headers,\n require_approval: convertRequireApproval(options.requireApproval),\n server_description: options.serverDescription,\n };\n\n if (\"serverUrl\" in options) {\n return {\n ...baseConfig,\n server_url: options.serverUrl,\n } satisfies McpTool;\n }\n\n return {\n ...baseConfig,\n connector_id: options.connectorId,\n } satisfies McpTool;\n}\n"],"mappings":";;;;;AA4HA,SAAS,kBACPA,QAC+C;AAC/C,QAAO;EACL,YAAY,OAAO;EACnB,WAAW,OAAO;CACnB;AACF;;;;AAKD,SAAS,oBACPC,cAC2E;AAC3E,KAAI,CAAC,aAAc,QAAO;AAC1B,KAAI,MAAM,QAAQ,aAAa,CAAE,QAAO;AACxC,QAAO,kBAAkB,aAAa;AACvC;;;;AAKD,SAAS,uBACPC,iBAKY;AACZ,KAAI,CAAC,gBAAiB,QAAO;AAC7B,KAAI,OAAO,oBAAoB,SAAU,QAAO;AAChD,QAAO;EACL,QAAQ,gBAAgB,SACpB,kBAAkB,gBAAgB,OAAO,GACzC;EACJ,OAAO,gBAAgB,QACnB,kBAAkB,gBAAgB,MAAM,GACxC;CACL;AACF;AAoED,SAAgB,IACdC,SACY;CACZ,MAAMC,aAAsB;EAC1B,MAAM;EACN,cAAc,QAAQ;EACtB,eAAe,oBAAoB,QAAQ,aAAa;EACxD,eAAe,QAAQ;EACvB,SAAS,QAAQ;EACjB,kBAAkB,uBAAuB,QAAQ,gBAAgB;EACjE,oBAAoB,QAAQ;CAC7B;AAED,KAAI,eAAe,QACjB,QAAO;EACL,GAAG;EACH,YAAY,QAAQ;CACrB;AAGH,QAAO;EACL,GAAG;EACH,cAAc,QAAQ;CACvB;AACF"}