Notion ReadOnly MCP Server

Instructions

Implementation Reference

• src/openapi-mcp-server/mcp/proxy.ts:227-278 (handler)

  Core handler logic for executing the 'API-retrieve-a-comment' tool call: resolves OpenAPI operation, invokes Notion API via HttpClient, logs response, updates cache, and returns JSON-formatted result.

  // Find the operation in OpenAPI spec
  const operation = this.findOperation(name)
  if (!operation) {
    const error = `Method ${name} not found.`
    console.error(error)
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            status: 'error',
            message: error,
            code: 404
          }),
        },
      ],
    }
  }
  
  // Optimized parallel processing for API-get-block-children
  if (name === 'API-get-block-children') {
    // Create basic options for logging control
    const blockOptions: RecursiveExplorationOptions = {
      runInBackground: false, // Default to not showing logs for regular API calls
    };
    
    return await this.handleBlockChildrenParallel(operation, params, blockOptions);
  }
  
  // Other regular API calls
  console.log(`Notion API call: ${operation.method.toUpperCase()} ${operation.path}`)
  const response = await this.httpClient.executeOperation(operation, params)
  
  // Log response summary
  console.log('Notion API response code:', response.status)
  if (response.status !== 200) {
    console.error('Response error:', response.data)
  } else {
    console.log('Response success')
  }
  
  // Update cache with response data
  this.updateCacheFromResponse(name, response.data);
  
  // Convert response to MCP format
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(response.data),
      },
    ],

• src/openapi-mcp-server/mcp/proxy.ts:115-126 (registration)

  Registers 'API-retrieve-a-comment' tool in MCP's listTools response by constructing name from OpenAPI-derived tool definitions (toolName='API', method.name='retrieve-a-comment').

  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'],
      })
      console.log(`- ${truncatedToolName}: ${method.description}`)
    })
  })

• src/openapi-mcp-server/openapi/parser.ts:166-196 (schema)

  Generates MCP tool schema and metadata for 'API-retrieve-a-comment' from Notion OpenAPI spec operationId 'retrieve-a-comment', including inputSchema from parameters/requestBody and lookup for handler.

  convertToMCPTools(): {
    tools: Record<string, { methods: NewToolMethod[] }>
    openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }>
    zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }>
  } {
    const apiName = 'API'
  
    const openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }> = {}
    const tools: Record<string, { methods: NewToolMethod[] }> = {
      [apiName]: { methods: [] },
    }
    const zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }> = {}
    for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) {
      if (!pathItem) continue
  
      for (const [method, operation] of Object.entries(pathItem)) {
        if (!this.isOperation(method, operation)) continue
  
        const mcpMethod = this.convertOperationToMCPMethod(operation, method, path)
        if (mcpMethod) {
          const uniqueName = this.ensureUniqueName(mcpMethod.name)
          mcpMethod.name = uniqueName
          tools[apiName]!.methods.push(mcpMethod)
          openApiLookup[apiName + '-' + uniqueName] = { ...operation, method, path }
          zip[apiName + '-' + uniqueName] = { openApi: { ...operation, method, path }, mcp: mcpMethod }
        }
      }
    }
  
    return { tools, openApiLookup, zip }
  }

• src/openapi-mcp-server/mcp/proxy.ts:330-337 (helper)

  Specific caching logic for 'API-retrieve-a-comment' responses, storing individual comments in commentCache for later use.

  } else if (apiName === 'API-retrieve-a-comment' && data.results) {
    // Cache comments from result list
    data.results.forEach((comment: any) => {
      if (comment.object === 'comment' && comment.id) {
        this.commentCache.set(comment.id, comment);
      }
    });
  } else if (apiName === 'API-retrieve-a-page-property' && data.results) {

• src/openapi-mcp-server/mcp/proxy.ts:847-900 (helper)

  Supporting utility method retrieveComments that invokes the 'API-retrieve-a-comment' tool internally for recursive page exploration, with additional caching.

  private async retrieveComments(blockId: string, options: RecursiveExplorationOptions): Promise<any> {
    if (options.runInBackground) {
      console.log(`Retrieving comments: ${blockId}`);
    }
    
    // Get comments via API call
    const operation = this.findOperation('API-retrieve-a-comment');
    if (!operation) {
      if (options.runInBackground) {
        console.warn('API-retrieve-a-comment method not found.');
      }
      return Promise.resolve({ results: [] });
    }
    
    try {
      if (options.runInBackground) {
        console.log(`Notion API call: ${operation.method.toUpperCase()} ${operation.path} (blockId: ${blockId})`);
      }
      
      return this.httpClient.executeOperation(operation, { block_id: blockId })
        .then(response => {
          if (response.status !== 200) {
            if (options.runInBackground) {
              console.error('Error retrieving comments:', response.data);
            }
            return { results: [] };
          }
          
          const commentsData = response.data;
          
          // Cache comments
          if (commentsData.results) {
            commentsData.results.forEach((comment: any) => {
              if (comment.id) {
                this.commentCache.set(comment.id, comment);
              }
            });
          }
          
          return commentsData;
        })
        .catch(error => {
          if (options.runInBackground) {
            console.error('Error retrieving comments:', error);
          }
          return { results: [] };
        });
    } catch (error) {
      if (options.runInBackground) {
        console.error('Error retrieving comments:', error);
      }
      return Promise.resolve({ results: [] });
    }
  }