Nylas API MCP Server

Implementation Reference

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

  Registers the 'search-api-docs' tool with the MCP server using server.tool(), including schema and handler.
  server.tool( "search-api-docs", { query: z.string(), category: z.enum(["email", "calendar", "contacts", "auth", "webhooks"]).optional() }, 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)

  Input schema for the search-api-docs tool using Zod, defining 'query' as required string and optional 'category' enum.
  { query: z.string(), category: z.enum(["email", "calendar", "contacts", "auth", "webhooks"]).optional() },
• src/tools/index.ts:368-509 (handler)

  Handler function that implements the tool logic: normalizes query, uses predefined API doc snippets per category, filters matches, returns formatted text content with results or no results found.
  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.` } ] }; } }