Better Notion MCP

Instructions

Implementation Reference

• src/tools/composite/workspace.ts:31-106 (handler)

  Main handler function for the 'workspace' tool. Handles 'info' action (retrieves bot user info) and 'search' action (searches workspace pages/databases with pagination, filtering, sorting).

  export async function workspace(notion: Client, input: WorkspaceInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'info': {
          const botUser = await notion.users.retrieve({ user_id: 'me' })
  
          return {
            action: 'info',
            bot: {
              id: (botUser as any).id,
              name: (botUser as any).name || 'Bot',
              type: (botUser as any).type,
              owner: (botUser as any).bot?.owner
            }
          }
        }
  
        case 'search': {
          // Query is optional - empty query returns all accessible pages
          const searchParams: any = {
            query: input.query || ''
          }
  
          if (input.filter?.object) {
            searchParams.filter = {
              value: input.filter.object,
              property: 'object'
            }
          }
  
          if (input.sort) {
            searchParams.sort = {
              direction: input.sort.direction || 'descending',
              timestamp: input.sort.timestamp || 'last_edited_time'
            }
          }
  
          // Fetch results with pagination
          const allResults = await autoPaginate((cursor) =>
            notion.search({
              ...searchParams,
              start_cursor: cursor,
              page_size: 100
            })
          )
  
          const results = input.limit ? allResults.slice(0, input.limit) : allResults
  
          return {
            action: 'search',
            query: input.query,
            total: results.length,
            results: results.map((item: any) => ({
              id: item.id,
              object: item.object,
              title:
                item.object === 'page'
                  ? item.properties?.title?.title?.[0]?.plain_text ||
                    item.properties?.Name?.title?.[0]?.plain_text ||
                    'Untitled'
                  : item.title?.[0]?.plain_text || 'Untitled',
              url: item.url,
              last_edited_time: item.last_edited_time
            }))
          }
        }
  
        default:
          throw new NotionMCPError(
            `Unknown action: ${input.action}`,
            'VALIDATION_ERROR',
            'Supported actions: info, search'
          )
      }
    })()
  }

• src/tools/composite/workspace.ts:10-25 (schema)

  TypeScript interface defining the input parameters for the workspace tool handler.

  export interface WorkspaceInput {
    action: 'info' | 'search'
  
    // Search params
    query?: string
    filter?: {
      object?: 'page' | 'data_source'
      property?: string
      value?: any
    }
    sort?: {
      direction?: 'ascending' | 'descending'
      timestamp?: 'last_edited_time' | 'created_time'
    }
    limit?: number
  }

• src/tools/registry.ts:159-189 (registration)

  Tool registration object including name, description, and JSON inputSchema for the MCP server.

  {
    name: 'workspace',
    description:
      'Workspace: info, search. Search returns pages/databases shared with integration. Use filter.object for type.',
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['info', 'search'],
          description: 'Action to perform'
        },
        query: { type: 'string', description: 'Search query' },
        filter: {
          type: 'object',
          properties: {
            object: { type: 'string', enum: ['page', 'data_source'] }
          }
        },
        sort: {
          type: 'object',
          properties: {
            direction: { type: 'string', enum: ['ascending', 'descending'] },
            timestamp: { type: 'string', enum: ['last_edited_time', 'created_time'] }
          }
        },
        limit: { type: 'number', description: 'Max results' }
      },
      required: ['action']
    }
  },

• src/tools/registry.ts:308-310 (registration)

  Dispatch case in the CallToolRequestSchema handler that invokes the workspace tool function.

  case 'workspace':
    result = await workspace(notion, args as any)
    break

• src/tools/registry.ts:25-25 (registration)

  Import statement for the workspace handler function.

  import { workspace } from './composite/workspace.js'