@notionhq/notion-mcp-server 1.8.1 → 1.9.1

package/package.json

@@ -6,7 +6,7 @@
     "mcp",
     "server"
   ],
-  "version": "1.8.1",
+  "version": "1.9.1",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -17,15 +17,17 @@
     "notion-mcp-server": "bin/cli.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@modelcontextprotocol/sdk": "^1.13.3",
     "axios": "^1.8.4",
     "express": "^4.21.2",
     "form-data": "^4.0.1",
     "mustache": "^4.2.0",
+    "node-fetch": "^3.3.2",
     "openapi-client-axios": "^7.5.5",
     "openapi-schema-validator": "^12.1.3",
     "openapi-types": "^12.1.3",
     "which": "^5.0.0",
+    "yargs": "^17.7.2",
     "zod": "3.24.1"
   },
   "devDependencies": {

package/scripts/start-server.ts

@@ -1,23 +1,238 @@
 import path from 'node:path'
 import { fileURLToPath } from 'url'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'
+import { randomUUID, randomBytes } from 'node:crypto'
+import express from 'express'
 
 import { initProxy, ValidationError } from '../src/init-server'
 
-export async function startServer(args: string[] = process.argv.slice(2)) {
+export async function startServer(args: string[] = process.argv) {
   const filename = fileURLToPath(import.meta.url)
   const directory = path.dirname(filename)
   const specPath = path.resolve(directory, '../scripts/notion-openapi.json')
   
   const baseUrl = process.env.BASE_URL ?? undefined
 
-  const proxy = await initProxy(specPath, baseUrl)
-  await proxy.connect(new StdioServerTransport())
+  // Parse command line arguments manually (similar to slack-mcp approach)
+  function parseArgs() {
+    const args = process.argv.slice(2);
+    let transport = 'stdio'; // default
+    let port = 3000;
+    let authToken: string | undefined;
 
-  return proxy.getServer()
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--transport' && i + 1 < args.length) {
+        transport = args[i + 1];
+        i++; // skip next argument
+      } else if (args[i] === '--port' && i + 1 < args.length) {
+        port = parseInt(args[i + 1], 10);
+        i++; // skip next argument
+      } else if (args[i] === '--auth-token' && i + 1 < args.length) {
+        authToken = args[i + 1];
+        i++; // skip next argument
+      } else if (args[i] === '--help' || args[i] === '-h') {
+        console.log(`
+Usage: notion-mcp-server [options]
+
+Options:
+  --transport <type>     Transport type: 'stdio' or 'http' (default: stdio)
+  --port <number>        Port for HTTP server when using Streamable HTTP transport (default: 3000)
+  --auth-token <token>   Bearer token for HTTP transport authentication (optional)
+  --help, -h             Show this help message
+
+Environment Variables:
+  NOTION_TOKEN           Notion integration token (recommended)
+  OPENAPI_MCP_HEADERS    JSON string with Notion API headers (alternative)
+  AUTH_TOKEN             Bearer token for HTTP transport authentication (alternative to --auth-token)
+
+Examples:
+  notion-mcp-server                                    # Use stdio transport (default)
+  notion-mcp-server --transport stdio                  # Use stdio transport explicitly
+  notion-mcp-server --transport http                   # Use Streamable HTTP transport on port 3000
+  notion-mcp-server --transport http --port 8080       # Use Streamable HTTP transport on port 8080
+  notion-mcp-server --transport http --auth-token mytoken # Use Streamable HTTP transport with custom auth token
+  AUTH_TOKEN=mytoken notion-mcp-server --transport http # Use Streamable HTTP transport with auth token from env var
+`);
+        process.exit(0);
+      }
+      // Ignore unrecognized arguments (like command name passed by Docker)
+    }
+
+    return { transport: transport.toLowerCase(), port, authToken };
+  }
+
+  const options = parseArgs()
+  const transport = options.transport
+
+  if (transport === 'stdio') {
+    // Use stdio transport (default)
+    const proxy = await initProxy(specPath, baseUrl)
+    await proxy.connect(new StdioServerTransport())
+    return proxy.getServer()
+  } else if (transport === 'http') {
+    // Use Streamable HTTP transport
+    const app = express()
+    app.use(express.json())
+
+    // Generate or use provided auth token (from CLI arg or env var)
+    const authToken = options.authToken || process.env.AUTH_TOKEN || randomBytes(32).toString('hex')
+    if (!options.authToken && !process.env.AUTH_TOKEN) {
+      console.log(`Generated auth token: ${authToken}`)
+      console.log(`Use this token in the Authorization header: Bearer ${authToken}`)
+    }
+
+    // Authorization middleware
+    const authenticateToken = (req: express.Request, res: express.Response, next: express.NextFunction): void => {
+      const authHeader = req.headers['authorization']
+      const token = authHeader && authHeader.split(' ')[1] // Bearer TOKEN
+
+      if (!token) {
+        res.status(401).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32001,
+            message: 'Unauthorized: Missing bearer token',
+          },
+          id: null,
+        })
+        return
+      }
+
+      if (token !== authToken) {
+        res.status(403).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32002,
+            message: 'Forbidden: Invalid bearer token',
+          },
+          id: null,
+        })
+        return
+      }
+
+      next()
+    }
+
+    // Health endpoint (no authentication required)
+    app.get('/health', (req, res) => {
+      res.status(200).json({
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        transport: 'http',
+        port: options.port
+      })
+    })
+
+    // Apply authentication to all /mcp routes
+    app.use('/mcp', authenticateToken)
+
+    // Map to store transports by session ID
+    const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {}
+
+    // Handle POST requests for client-to-server communication
+    app.post('/mcp', async (req, res) => {
+      try {
+        // Check for existing session ID
+        const sessionId = req.headers['mcp-session-id'] as string | undefined
+        let transport: StreamableHTTPServerTransport
+
+        if (sessionId && transports[sessionId]) {
+          // Reuse existing transport
+          transport = transports[sessionId]
+        } else if (!sessionId && isInitializeRequest(req.body)) {
+          // New initialization request
+          transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sessionId) => {
+              // Store the transport by session ID
+              transports[sessionId] = transport
+            }
+          })
+
+          // Clean up transport when closed
+          transport.onclose = () => {
+            if (transport.sessionId) {
+              delete transports[transport.sessionId]
+            }
+          }
+
+          const proxy = await initProxy(specPath, baseUrl)
+          await proxy.connect(transport)
+        } else {
+          // Invalid request
+          res.status(400).json({
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              message: 'Bad Request: No valid session ID provided',
+            },
+            id: null,
+          })
+          return
+        }
+
+        // Handle the request
+        await transport.handleRequest(req, res, req.body)
+      } catch (error) {
+        console.error('Error handling MCP request:', error)
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: {
+              code: -32603,
+              message: 'Internal server error',
+            },
+            id: null,
+          })
+        }
+      }
+    })
+
+    // Handle GET requests for server-to-client notifications via Streamable HTTP
+    app.get('/mcp', async (req, res) => {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send('Invalid or missing session ID')
+        return
+      }
+      
+      const transport = transports[sessionId]
+      await transport.handleRequest(req, res)
+    })
+
+    // Handle DELETE requests for session termination
+    app.delete('/mcp', async (req, res) => {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send('Invalid or missing session ID')
+        return
+      }
+      
+      const transport = transports[sessionId]
+      await transport.handleRequest(req, res)
+    })
+
+    const port = options.port
+    app.listen(port, '0.0.0.0', () => {
+      console.log(`MCP Server listening on port ${port}`)
+      console.log(`Endpoint: http://0.0.0.0:${port}/mcp`)
+      console.log(`Health check: http://0.0.0.0:${port}/health`)
+      console.log(`Authentication: Bearer token required`)
+      if (options.authToken) {
+        console.log(`Using provided auth token`)
+      }
+    })
+
+    // Return a dummy server for compatibility
+    return { close: () => {} }
+  } else {
+    throw new Error(`Unsupported transport: ${transport}. Use 'stdio' or 'http'.`)
+  }
 }
 
-startServer().catch(error => {
+startServer(process.argv).catch(error => {
   if (error instanceof ValidationError) {
     console.error('Invalid OpenAPI 3.1 specification:')
     error.errors.forEach(err => console.error(err))

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

@@ -257,6 +257,70 @@ describe('MCPProxy', () => {
       )
       expect(consoleSpy).toHaveBeenCalledWith('OPENAPI_MCP_HEADERS environment variable must be a JSON object, got:', 'string')
     })
+
+    it('should use NOTION_TOKEN when OPENAPI_MCP_HEADERS is not set', () => {
+      delete process.env.OPENAPI_MCP_HEADERS
+      process.env.NOTION_TOKEN = 'ntn_test_token_123'
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {
+            'Authorization': 'Bearer ntn_test_token_123',
+            'Notion-Version': '2022-06-28'
+          },
+        }),
+        expect.anything(),
+      )
+    })
+
+    it('should prioritize OPENAPI_MCP_HEADERS over NOTION_TOKEN when both are set', () => {
+      process.env.OPENAPI_MCP_HEADERS = JSON.stringify({
+        Authorization: 'Bearer custom_token',
+        'Custom-Header': 'custom_value',
+      })
+      process.env.NOTION_TOKEN = 'ntn_test_token_123'
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer custom_token',
+            'Custom-Header': 'custom_value',
+          },
+        }),
+        expect.anything(),
+      )
+    })
+
+    it('should return empty object when neither OPENAPI_MCP_HEADERS nor NOTION_TOKEN are set', () => {
+      delete process.env.OPENAPI_MCP_HEADERS
+      delete process.env.NOTION_TOKEN
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {},
+        }),
+        expect.anything(),
+      )
+    })
+
+    it('should use NOTION_TOKEN when OPENAPI_MCP_HEADERS is empty object', () => {
+      process.env.OPENAPI_MCP_HEADERS = '{}'
+      process.env.NOTION_TOKEN = 'ntn_test_token_123'
+
+      const proxy = new MCPProxy('test-proxy', mockOpenApiSpec)
+      expect(HttpClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: {
+            'Authorization': 'Bearer ntn_test_token_123',
+            'Notion-Version': '2022-06-28'
+          },
+        }),
+        expect.anything(),
+      )
+    })
   })
   describe('connect', () => {
     it('should connect to transport', async () => {

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

@@ -124,22 +124,34 @@ export class MCPProxy {
   }
 
   private parseHeadersFromEnv(): Record<string, string> {
+    // First try OPENAPI_MCP_HEADERS (existing behavior)
     const headersJson = process.env.OPENAPI_MCP_HEADERS
-    if (!headersJson) {
-      return {}
+    if (headersJson) {
+      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)
+        } else if (Object.keys(headers).length > 0) {
+          // Only use OPENAPI_MCP_HEADERS if it contains actual headers
+          return headers
+        }
+        // If OPENAPI_MCP_HEADERS is empty object, fall through to try NOTION_TOKEN
+      } catch (error) {
+        console.warn('Failed to parse OPENAPI_MCP_HEADERS environment variable:', error)
+        // Fall through to try NOTION_TOKEN
+      }
     }
 
-    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 {}
+    // Alternative: try NOTION_TOKEN
+    const notionToken = process.env.NOTION_TOKEN
+    if (notionToken) {
+      return {
+        'Authorization': `Bearer ${notionToken}`,
+        'Notion-Version': '2022-06-28'
       }
-      return headers
-    } catch (error) {
-      console.warn('Failed to parse OPENAPI_MCP_HEADERS environment variable:', error)
-      return {}
     }
+
+    return {}
   }
 
   private getContentType(headers: Headers): 'text' | 'image' | 'binary' {

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

@@ -185,6 +185,7 @@ export class OpenAPIToMCPConverter {
         if (mcpMethod) {
           const uniqueName = this.ensureUniqueName(mcpMethod.name)
           mcpMethod.name = uniqueName
+          mcpMethod.description = this.getDescription(operation.summary || operation.description || '')
           tools[apiName]!.methods.push(mcpMethod)
           openApiLookup[apiName + '-' + uniqueName] = { ...operation, method, path }
           zip[apiName + '-' + uniqueName] = { openApi: { ...operation, method, path }, mcp: mcpMethod }
@@ -212,7 +213,7 @@ export class OpenAPIToMCPConverter {
           type: 'function',
           function: {
             name: operation.operationId!,
-            description: operation.summary || operation.description || '',
+            description: this.getDescription(operation.summary || operation.description || ''),
             parameters: parameters as FunctionParameters,
           },
         }
@@ -238,7 +239,7 @@ export class OpenAPIToMCPConverter {
         const parameters = this.convertOperationToJsonSchema(operation, method, path)
         const tool: Tool = {
           name: operation.operationId!,
-          description: operation.summary || operation.description || '',
+          description: this.getDescription(operation.summary || operation.description || ''),
           input_schema: parameters as Tool['input_schema'],
         }
         tools.push(tool)
@@ -516,4 +517,8 @@ export class OpenAPIToMCPConverter {
     this.nameCounter += 1
     return this.nameCounter.toString().padStart(4, '0')
   }
+
+  private getDescription(description: string): string {
+    return "Notion | " + description
+  }
 }