@notionhq/notion-mcp-server 1.0.0

package/src/openapi-mcp-server/client/http-client.ts

@@ -0,0 +1,192 @@
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+import OpenAPIClientAxios from 'openapi-client-axios'
+import type { AxiosInstance } from 'axios'
+import FormData from 'form-data'
+import fs from 'fs'
+import { isFileUploadParameter } from '../openapi/file-upload'
+
+export type HttpClientConfig = {
+  baseUrl: string
+  headers?: Record<string, string>
+}
+
+export type HttpClientResponse<T = any> = {
+  data: T
+  status: number
+  headers: Headers
+}
+
+export class HttpClientError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public data: any,
+    public headers?: Headers,
+  ) {
+    super(`${status} ${message}`)
+    this.name = 'HttpClientError'
+  }
+}
+
+export class HttpClient {
+  private api: Promise<AxiosInstance>
+  private client: OpenAPIClientAxios
+
+  constructor(config: HttpClientConfig, openApiSpec: OpenAPIV3.Document | OpenAPIV3_1.Document) {
+    // @ts-expect-error
+    this.client = new (OpenAPIClientAxios.default ?? OpenAPIClientAxios)({
+      definition: openApiSpec,
+      axiosConfigDefaults: {
+        baseURL: config.baseUrl,
+        headers: {
+          'Content-Type': 'application/json',
+          ...config.headers,
+        },
+      },
+    })
+    this.api = this.client.init()
+  }
+
+  private async prepareFileUpload(operation: OpenAPIV3.OperationObject, params: Record<string, any>): Promise<FormData | null> {
+    console.error('prepareFileUpload', { operation, params })
+    const fileParams = isFileUploadParameter(operation)
+    if (fileParams.length === 0) return null
+
+    const formData = new FormData()
+
+    // Handle file uploads
+    for (const param of fileParams) {
+      console.error(`extracting ${param}`, {params})
+      const filePath = params[param]
+      if (!filePath) {
+        throw new Error(`File path must be provided for parameter: ${param}`)
+      }
+      switch (typeof filePath) {
+        case 'string':
+          addFile(param, filePath)
+          break
+        case 'object':
+          if(Array.isArray(filePath)) {
+            let fileCount = 0
+            for(const file of filePath) {
+              addFile(param, file)
+              fileCount++
+            }
+            break
+          }
+          //deliberate fallthrough
+        default:
+          throw new Error(`Unsupported file type: ${typeof filePath}`)
+      }
+      function addFile(name: string, filePath: string) {
+          try {
+            const fileStream = fs.createReadStream(filePath)
+            formData.append(name, fileStream)
+        } catch (error) {
+          throw new Error(`Failed to read file at ${filePath}: ${error}`)
+        }
+      }
+    }
+
+    // Add non-file parameters to form data
+    for (const [key, value] of Object.entries(params)) {
+      if (!fileParams.includes(key)) {
+        formData.append(key, value)
+      }
+    }
+
+    return formData
+  }
+
+  /**
+   * Execute an OpenAPI operation
+   */
+  async executeOperation<T = any>(
+    operation: OpenAPIV3.OperationObject & { method: string; path: string },
+    params: Record<string, any> = {},
+  ): Promise<HttpClientResponse<T>> {
+    const api = await this.api
+    const operationId = operation.operationId
+    if (!operationId) {
+      throw new Error('Operation ID is required')
+    }
+
+    // Handle file uploads if present
+    const formData = await this.prepareFileUpload(operation, params)
+
+    // Separate parameters based on their location
+    const urlParameters: Record<string, any> = {}
+    const bodyParams: Record<string, any> = formData || { ...params }
+
+    // Extract path and query parameters based on operation definition
+    if (operation.parameters) {
+      for (const param of operation.parameters) {
+        if ('name' in param && param.name && param.in) {
+          if (param.in === 'path' || param.in === 'query') {
+            if (params[param.name] !== undefined) {
+              urlParameters[param.name] = params[param.name]
+              if (!formData) {
+                delete bodyParams[param.name]
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Add all parameters as url parameters if there is no requestBody defined
+    if (!operation.requestBody && !formData) {
+      for (const key in bodyParams) {
+        if (bodyParams[key] !== undefined) {
+          urlParameters[key] = bodyParams[key]
+          delete bodyParams[key]
+        }
+      }
+    }
+
+    const operationFn = (api as any)[operationId]
+    if (!operationFn) {
+      throw new Error(`Operation ${operationId} not found`)
+    }
+
+    try {
+      // If we have form data, we need to set the correct headers
+      const hasBody = Object.keys(bodyParams).length > 0
+      const headers = formData
+        ? formData.getHeaders()
+        : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }
+      const requestConfig = {
+        headers: {
+          ...headers,
+        },
+      }
+
+      // first argument is url parameters, second is body parameters
+      console.error('calling operation', { operationId, urlParameters, bodyParams, requestConfig })
+      const response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)
+
+      // Convert axios headers to Headers object
+      const responseHeaders = new Headers()
+      Object.entries(response.headers).forEach(([key, value]) => {
+        if (value) responseHeaders.append(key, value.toString())
+      })
+
+      return {
+        data: response.data,
+        status: response.status,
+        headers: responseHeaders,
+      }
+    } catch (error: any) {
+      if (error.response) {
+        console.error('Error in http client', error)
+        const headers = new Headers()
+        Object.entries(error.response.headers).forEach(([key, value]) => {
+          if (value) headers.append(key, value.toString())
+        })
+
+        throw new HttpClientError(error.response.statusText || 'Request failed', error.response.status, error.response.data, headers)
+      }
+      throw error
+    }
+  }
+}

package/src/openapi-mcp-server/index.ts

@@ -0,0 +1,3 @@
+export { OpenAPIToMCPConverter } from './openapi/parser'
+export { HttpClient } from './client/http-client'
+export type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'

package/src/openapi-mcp-server/mcp/__tests__/proxy.test.ts

@@ -0,0 +1,270 @@
+import { MCPProxy } from '../proxy'
+import { OpenAPIV3 } from 'openapi-types'
+import { HttpClient } from '../../client/http-client'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+
+// Mock the dependencies
+vi.mock('../../client/http-client')
+vi.mock('@modelcontextprotocol/sdk/server/index.js')
+
+describe('MCPProxy', () => {
+  let proxy: MCPProxy
+  let mockOpenApiSpec: OpenAPIV3.Document
+
+  beforeEach(() => {
+    // Reset all mocks
+    vi.clearAllMocks()
+
+    // Setup minimal OpenAPI spec for testing
+    mockOpenApiSpec = {
+      openapi: '3.0.0',
+      servers: [{ url: 'http://localhost:3000' }],
+      info: {
+        title: 'Test API',
+        version: '1.0.0',
+      },
+      paths: {
+        '/test': {
+          get: {
+            operationId: 'getTest',
+            responses: {
+              '200': {
+                description: 'Success',
+              },
+            },
+          },
+        },
+      },
+    }
+
+    proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+  })
+
+  describe('listTools handler', () => {
+    it('should return converted tools from OpenAPI spec', async () => {
+      const server = (proxy as any).server
+      const listToolsHandler = server.setRequestHandler.mock.calls[0].filter((x: unknown) => typeof x === 'function')[0]
+      const result = await listToolsHandler()
+
+      expect(result).toHaveProperty('tools')
+      expect(Array.isArray(result.tools)).toBe(true)
+    })
+
+    it('should truncate tool names exceeding 64 characters', async () => {
+      // Setup OpenAPI spec with long tool names
+      mockOpenApiSpec.paths = {
+        '/test': {
+          get: {
+            operationId: 'a'.repeat(65),
+            responses: {
+              '200': {
+                description: 'Success'
+              }
+            }
+          }
+        }
+      }
+      proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      const server = (proxy as any).server
+      const listToolsHandler = server.setRequestHandler.mock.calls[0].filter((x: unknown) => typeof x === 'function')[0];
+      const result = await listToolsHandler()
+
+      expect(result.tools[0].name.length).toBeLessThanOrEqual(64)
+    })
+  })
+
+  describe('callTool handler', () => {
+    it('should execute operation and return formatted response', async () => {
+      // Mock HttpClient response
+      const mockResponse = {
+        data: { message: 'success' },
+        status: 200,
+        headers: new Headers({
+          'content-type': 'application/json',
+        }),
+      }
+      ;(HttpClient.prototype.executeOperation as ReturnType<typeof vi.fn>).mockResolvedValue(mockResponse)
+
+      // Set up the openApiLookup with our test operation
+      ;(proxy as any).openApiLookup = {
+        'API-getTest': {
+          operationId: 'getTest',
+          responses: { '200': { description: 'Success' } },
+          method: 'get',
+          path: '/test',
+        },
+      }
+
+      const server = (proxy as any).server
+      const handlers = server.setRequestHandler.mock.calls.flatMap((x: unknown[]) => x).filter((x: unknown) => typeof x === 'function')
+      const callToolHandler = handlers[1]
+
+      const result = await callToolHandler({
+        params: {
+          name: 'API-getTest',
+          arguments: {},
+        },
+      })
+
+      expect(result).toEqual({
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ message: 'success' }),
+          },
+        ],
+      })
+    })
+
+    it('should throw error for non-existent operation', async () => {
+      const server = (proxy as any).server
+      const handlers = server.setRequestHandler.mock.calls.flatMap((x: unknown[]) => x).filter((x: unknown) => typeof x === 'function')
+      const callToolHandler = handlers[1]
+
+      await expect(
+        callToolHandler({
+          params: {
+            name: 'nonExistentMethod',
+            arguments: {},
+          },
+        }),
+      ).rejects.toThrow('Method nonExistentMethod not found')
+    })
+
+    it('should handle tool names exceeding 64 characters', async () => {
+      // Mock HttpClient response
+      const mockResponse = {
+        data: { message: 'success' },
+        status: 200,
+        headers: new Headers({
+          'content-type': 'application/json'
+        })
+      };
+      (HttpClient.prototype.executeOperation as ReturnType<typeof vi.fn>).mockResolvedValue(mockResponse);
+
+      // Set up the openApiLookup with a long tool name
+      const longToolName = 'a'.repeat(65)
+      const truncatedToolName = longToolName.slice(0, 64)
+      ;(proxy as any).openApiLookup = {
+        [truncatedToolName]: {
+          operationId: longToolName,
+          responses: { '200': { description: 'Success' } },
+          method: 'get',
+          path: '/test'
+        }
+      };
+
+      const server = (proxy as any).server;
+      const handlers = server.setRequestHandler.mock.calls.flatMap((x: unknown[]) => x).filter((x: unknown) => typeof x === 'function');
+      const callToolHandler = handlers[1];
+
+      const result = await callToolHandler({
+        params: {
+          name: truncatedToolName,
+          arguments: {}
+        }
+      })
+
+      expect(result).toEqual({
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ message: 'success' })
+          }
+        ]
+      })
+    })
+  })
+
+  describe('getContentType', () => {
+    it('should return correct content type for different headers', () => {
+      const getContentType = (proxy as any).getContentType.bind(proxy)
+
+      expect(getContentType(new Headers({ 'content-type': 'text/plain' }))).toBe('text')
+      expect(getContentType(new Headers({ 'content-type': 'application/json' }))).toBe('text')
+      expect(getContentType(new Headers({ 'content-type': 'image/jpeg' }))).toBe('image')
+      expect(getContentType(new Headers({ 'content-type': 'application/octet-stream' }))).toBe('binary')
+      expect(getContentType(new Headers())).toBe('binary')
+    })
+  })
+
+  describe('parseHeadersFromEnv', () => {
+    const originalEnv = process.env
+
+    beforeEach(() => {
+      process.env = { ...originalEnv }
+    })
+
+    afterEach(() => {
+      process.env = originalEnv
+    })
+
+    it('should parse valid JSON headers from env', () => {
+      process.env.OPENAPI_MCP_HEADERS = JSON.stringify({
+        Authorization: 'Bearer token123',
+        'X-Custom-Header': 'test',
+      })
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer token123',
+            'X-Custom-Header': 'test',
+          },
+        }),
+        expect.anything(),
+      )
+    })
+
+    it('should return empty object when env var is not set', () => {
+      delete process.env.OPENAPI_MCP_HEADERS
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {},
+        }),
+        expect.anything(),
+      )
+    })
+
+    it('should return empty object and warn on invalid JSON', () => {
+      const consoleSpy = vi.spyOn(console, 'warn')
+      process.env.OPENAPI_MCP_HEADERS = 'invalid json'
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {},
+        }),
+        expect.anything(),
+      )
+      expect(consoleSpy).toHaveBeenCalledWith('Failed to parse OPENAPI_MCP_HEADERS environment variable:', expect.any(Error))
+    })
+
+    it('should return empty object and warn on non-object JSON', () => {
+      const consoleSpy = vi.spyOn(console, 'warn')
+      process.env.OPENAPI_MCP_HEADERS = '"string"'
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {},
+        }),
+        expect.anything(),
+      )
+      expect(consoleSpy).toHaveBeenCalledWith('OPENAPI_MCP_HEADERS environment variable must be a JSON object, got:', 'string')
+    })
+  })
+  describe('connect', () => {
+    it('should connect to transport', async () => {
+      const mockTransport = {} as Transport
+      await proxy.connect(mockTransport)
+
+      const server = (proxy as any).server
+      expect(server.connect).toHaveBeenCalledWith(mockTransport)
+    })
+  })
+})

package/src/openapi-mcp-server/mcp/proxy.ts

@@ -0,0 +1,170 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { CallToolRequestSchema, JSONRPCResponse, ListToolsRequestSchema, Tool } from '@modelcontextprotocol/sdk/types.js'
+import { JSONSchema7 as IJsonSchema } from 'json-schema'
+import { OpenAPIToMCPConverter } from '../openapi/parser'
+import { HttpClient, HttpClientError } from '../client/http-client'
+import { OpenAPIV3 } from 'openapi-types'
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+
+type PathItemObject = OpenAPIV3.PathItemObject & {
+  get?: OpenAPIV3.OperationObject
+  put?: OpenAPIV3.OperationObject
+  post?: OpenAPIV3.OperationObject
+  delete?: OpenAPIV3.OperationObject
+  patch?: OpenAPIV3.OperationObject
+}
+
+type NewToolDefinition = {
+  methods: Array<{
+    name: string
+    description: string
+    inputSchema: IJsonSchema & { type: 'object' }
+    returnSchema?: IJsonSchema
+  }>
+}
+
+// import this class, extend and return server
+export class MCPProxy {
+  private server: Server
+  private httpClient: HttpClient
+  private tools: Record<string, NewToolDefinition>
+  private openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }>
+
+  constructor(name: string, openApiSpec: OpenAPIV3.Document) {
+    this.server = new Server({ name, version: '1.0.0' }, { capabilities: { tools: {} } })
+    const baseUrl = openApiSpec.servers?.[0].url
+    if (!baseUrl) {
+      throw new Error('No base URL found in OpenAPI spec')
+    }
+    this.httpClient = new HttpClient(
+      {
+        baseUrl,
+        headers: this.parseHeadersFromEnv(),
+      },
+      openApiSpec,
+    )
+
+    // Convert OpenAPI spec to MCP tools
+    const converter = new OpenAPIToMCPConverter(openApiSpec)
+    const { tools, openApiLookup } = converter.convertToMCPTools()
+    this.tools = tools
+    this.openApiLookup = openApiLookup
+
+    this.setupHandlers()
+  }
+
+  private setupHandlers() {
+    // Handle tool listing
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const tools: Tool[] = []
+
+      // Add methods as separate tools to match the MCP format
+      Object.entries(this.tools).forEach(([toolName, def]) => {
+        def.methods.forEach(method => {
+          const toolNameWithMethod = `${toolName}-${method.name}`;
+          const truncatedToolName = this.truncateToolName(toolNameWithMethod);
+          tools.push({
+            name: truncatedToolName,
+            description: method.description,
+            inputSchema: method.inputSchema as Tool['inputSchema'],
+          })
+        })
+      })
+
+      return { tools }
+    })
+
+    // Handle tool calling
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      console.error('calling tool', request.params)
+      const { name, arguments: params } = request.params
+
+      // Find the operation in OpenAPI spec
+      const operation = this.findOperation(name)
+      console.error('operations', this.openApiLookup)
+      if (!operation) {
+        throw new Error(`Method ${name} not found`)
+      }
+
+      try {
+        // Execute the operation
+        const response = await this.httpClient.executeOperation(operation, params)
+
+        // Convert response to MCP format
+        return {
+          content: [
+            {
+              type: 'text', // currently this is the only type that seems to be used by mcp server
+              text: JSON.stringify(response.data), // TODO: pass through the http status code text?
+            },
+          ],
+        }
+      } catch (error) {
+        console.error('Error in tool call', error)
+        if (error instanceof HttpClientError) {
+          console.error('HttpClientError encountered, returning structured error', error)
+          const data = error.data?.response?.data ?? error.data ?? {}
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify({
+                  status: 'error', // TODO: get this from http status code?
+                  ...(typeof data === 'object' ? data : { data: data }),
+                }),
+              },
+            ],
+          }
+        }
+        throw error
+      }
+    })
+  }
+
+  private findOperation(operationId: string): (OpenAPIV3.OperationObject & { method: string; path: string }) | null {
+    return this.openApiLookup[operationId] ?? null
+  }
+
+  private parseHeadersFromEnv(): Record<string, string> {
+    const headersJson = process.env.OPENAPI_MCP_HEADERS
+    if (!headersJson) {
+      return {}
+    }
+
+    try {
+      const headers = JSON.parse(headersJson)
+      if (typeof headers !== 'object' || headers === null) {
+        console.warn('OPENAPI_MCP_HEADERS environment variable must be a JSON object, got:', typeof headers)
+        return {}
+      }
+      return headers
+    } catch (error) {
+      console.warn('Failed to parse OPENAPI_MCP_HEADERS environment variable:', error)
+      return {}
+    }
+  }
+
+  private getContentType(headers: Headers): 'text' | 'image' | 'binary' {
+    const contentType = headers.get('content-type')
+    if (!contentType) return 'binary'
+
+    if (contentType.includes('text') || contentType.includes('json')) {
+      return 'text'
+    } else if (contentType.includes('image')) {
+      return 'image'
+    }
+    return 'binary'
+  }
+
+  private truncateToolName(name: string): string {
+    if (name.length <= 64) {
+      return name;
+    }
+    return name.slice(0, 64);
+  }
+
+  async connect(transport: Transport) {
+    // The SDK will handle stdio communication
+    await this.server.connect(transport)
+  }
+}