Nylas API MCP Server

Implementation Reference

• src/tools/index.ts:368-510 (handler)

  The handler function that executes the 'search-api-docs' tool. It normalizes the query, searches hardcoded documentation strings across categories like email, calendar, etc., and returns formatted markdown results or no results message.

      async ({ query, category }) => {
        // Normalize the query for search
        const normalizedQuery = query.toLowerCase();
        
        // Define search result templates
        const searchResults: Record<string, string[]> = {
          "email": [
            `### Messages API
  The Messages API allows you to read, send, and search email messages.
  Key endpoints:
  - GET /v3/grants/{grant_id}/messages - List messages
  - GET /v3/grants/{grant_id}/messages/{message_id} - Get a specific message
  - POST /v3/grants/{grant_id}/messages - Send a message`,
            
            `### Threads API
  The Threads API allows you to manage email conversations.
  Key endpoints:
  - GET /v3/grants/{grant_id}/threads - List threads
  - GET /v3/grants/{grant_id}/threads/{thread_id} - Get a specific thread`,
            
            `### Drafts API
  The Drafts API allows you to create and manage email drafts.
  Key endpoints:
  - GET /v3/grants/{grant_id}/drafts - List drafts
  - POST /v3/grants/{grant_id}/drafts - Create a draft
  - POST /v3/grants/{grant_id}/drafts/{draft_id}/send - Send a draft`
          ],
          
          "calendar": [
            `### Calendars API
  The Calendars API allows you to manage calendar containers.
  Key endpoints:
  - GET /v3/grants/{grant_id}/calendars - List calendars
  - GET /v3/grants/{grant_id}/calendars/{calendar_id} - Get a specific calendar`,
            
            `### Events API
  The Events API allows you to create and manage calendar events.
  Key endpoints:
  - GET /v3/grants/{grant_id}/events - List events
  - POST /v3/grants/{grant_id}/events - Create an event
  - PUT /v3/grants/{grant_id}/events/{event_id} - Update an event`,
            
            `### Availability API
  The Availability API helps find available time slots.
  Key endpoints:
  - POST /v3/grants/{grant_id}/calendars/availability - Find available time slots`
          ],
          
          "contacts": [
            `### Contacts API
  The Contacts API allows you to manage contact information.
  Key endpoints:
  - GET /v3/grants/{grant_id}/contacts - List contacts
  - GET /v3/grants/{grant_id}/contacts/{contact_id} - Get a specific contact
  - POST /v3/grants/{grant_id}/contacts - Create a contact`
          ],
          
          "auth": [
            `### Authentication API
  The Authentication API handles OAuth flows.
  Key endpoints:
  - GET /v3/connect/oauth/authorize - Start OAuth flow
  - POST /v3/connect/oauth/token - Exchange code for token or refresh token`,
            
            `### Grants API
  The Grants API manages connected accounts.
  Key endpoints:
  - GET /v3/applications/{application_id}/grants - List connected accounts
  - GET /v3/applications/{application_id}/grants/{grant_id} - Get a specific connected account`
          ],
          
          "webhooks": [
            `### Webhooks API
  The Webhooks API allows setting up real-time notifications.
  Key endpoints:
  - GET /v3/applications/{application_id}/webhooks - List webhooks
  - POST /v3/applications/{application_id}/webhooks - Create a webhook
  - DELETE /v3/applications/{application_id}/webhooks/{webhook_id} - Delete a webhook`
          ]
        };
        
        // If a category is specified, search only in that category
        if (category) {
          const categoryResults = searchResults[category] || [];
          const matches = categoryResults.filter(result => 
            result.toLowerCase().includes(normalizedQuery)
          );
          
          if (matches.length > 0) {
            return {
              content: [
                {
                  type: "text",
                  text: `# Search results for "${query}" in ${category} API\n\n${matches.join('\n\n')}`
                }
              ]
            };
          } else {
            return {
              content: [
                {
                  type: "text",
                  text: `No results found for "${query}" in the ${category} API. Try a different search term or category.`
                }
              ]
            };
          }
        }
        
        // If no category is specified, search in all categories
        const allResults: string[] = [];
        
        Object.entries(searchResults).forEach(([category, results]) => {
          const categoryMatches = results.filter(result => 
            result.toLowerCase().includes(normalizedQuery)
          );
          
          if (categoryMatches.length > 0) {
            allResults.push(`## ${category.charAt(0).toUpperCase() + category.slice(1)} API\n\n${categoryMatches.join('\n\n')}`);
          }
        });
        
        if (allResults.length > 0) {
          return {
            content: [
              {
                type: "text",
                text: `# Search results for "${query}"\n\n${allResults.join('\n\n')}`
              }
            ]
          };
        } else {
          return {
            content: [
              {
                type: "text",
                text: `No results found for "${query}". Try a different search term.`
              }
            ]
          };
        }
      }
    );

• src/tools/index.ts:364-367 (schema)

  The input schema for the 'search-api-docs' tool using Zod, defining 'query' as required string and 'category' as optional enum.

  {
    query: z.string(),
    category: z.enum(["email", "calendar", "contacts", "auth", "webhooks"]).optional()
  },

• src/tools/index.ts:362-363 (registration)

  The registration of the 'search-api-docs' tool with the MCP server using server.tool(), including inline schema and handler.

  server.tool(
    "search-api-docs",