Xano MCP Server

Instructions

Implementation Reference

• src/index.ts:572-637 (handler)

  The main execution logic for the get-api-spec tool: fetches API group details, Swagger spec via link, processes to markdown or JSON.
  async ({ apigroup_id, format }) => { console.error(`[Tool] Executing get-api-spec for API group ID: ${apigroup_id} with format: ${format}`); try { // Step 1: Get the API group details to find the Swagger spec link const apiGroup = await makeXanoRequest<XanoApiGroup>(`/workspace/${XANO_WORKSPACE}/apigroup/${apigroup_id}`); if (!apiGroup.swagger || !apiGroup.documentation || !apiGroup.documentation.link) { return { content: [ { type: "text", text: `API group (ID: ${apigroup_id}) does not have Swagger documentation available.` } ], isError: true }; } console.error(`[Tool] Found Swagger spec link: ${apiGroup.documentation.link}`); // Step 2: Fetch the Swagger JSON specification const swaggerResponse = await fetch(apiGroup.documentation.link); if (!swaggerResponse.ok) { throw new Error(`Failed to fetch Swagger spec: ${swaggerResponse.statusText}`); } const swaggerSpec = await swaggerResponse.json(); console.error(`[Tool] Successfully retrieved Swagger specification`); // Step 3: Process the spec based on format if (format === "json") { // Return the full JSON specification return { content: [ { type: "text", text: `# ${apiGroup.name} API Specification (Full JSON)\n\n\`\`\`json\n${JSON.stringify(swaggerSpec, null, 2)}\n\`\`\`` } ] }; } else { // Process the Swagger spec into a minified markdown format const markdown = processSwaggerToMarkdown(swaggerSpec, apiGroup.name); return { content: [ { type: "text", text: markdown } ] }; } } catch (error) { console.error(`[Error] Failed to get API spec: ${error instanceof Error ? error.message : String(error)}`); return { content: [ { type: "text", text: `Error getting API specification: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } }
• src/index.ts:568-571 (schema)

  Zod input schema defining parameters: apigroup_id (string) and format (enum markdown/json, default markdown).
  { apigroup_id: z.string().describe("ID of the API group to get specification for"), format: z.enum(["markdown", "json"]).default("markdown").describe("Output format: 'markdown' for concise documentation or 'json' for full specification") },
• src/index.ts:565-638 (registration)

  Registration of the 'get-api-spec' tool on the MCP server using server.tool, including name, description, schema, and handler.
  server.tool( "get-api-spec", "Get and convert Swagger specification for an API group to a minified markdown format", { apigroup_id: z.string().describe("ID of the API group to get specification for"), format: z.enum(["markdown", "json"]).default("markdown").describe("Output format: 'markdown' for concise documentation or 'json' for full specification") }, async ({ apigroup_id, format }) => { console.error(`[Tool] Executing get-api-spec for API group ID: ${apigroup_id} with format: ${format}`); try { // Step 1: Get the API group details to find the Swagger spec link const apiGroup = await makeXanoRequest<XanoApiGroup>(`/workspace/${XANO_WORKSPACE}/apigroup/${apigroup_id}`); if (!apiGroup.swagger || !apiGroup.documentation || !apiGroup.documentation.link) { return { content: [ { type: "text", text: `API group (ID: ${apigroup_id}) does not have Swagger documentation available.` } ], isError: true }; } console.error(`[Tool] Found Swagger spec link: ${apiGroup.documentation.link}`); // Step 2: Fetch the Swagger JSON specification const swaggerResponse = await fetch(apiGroup.documentation.link); if (!swaggerResponse.ok) { throw new Error(`Failed to fetch Swagger spec: ${swaggerResponse.statusText}`); } const swaggerSpec = await swaggerResponse.json(); console.error(`[Tool] Successfully retrieved Swagger specification`); // Step 3: Process the spec based on format if (format === "json") { // Return the full JSON specification return { content: [ { type: "text", text: `# ${apiGroup.name} API Specification (Full JSON)\n\n\`\`\`json\n${JSON.stringify(swaggerSpec, null, 2)}\n\`\`\`` } ] }; } else { // Process the Swagger spec into a minified markdown format const markdown = processSwaggerToMarkdown(swaggerSpec, apiGroup.name); return { content: [ { type: "text", text: markdown } ] }; } } catch (error) { console.error(`[Error] Failed to get API spec: ${error instanceof Error ? error.message : String(error)}`); return { content: [ { type: "text", text: `Error getting API specification: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } );
• src/index.ts:641-715 (helper)

  Supporting function that processes Swagger/OpenAPI spec into a concise markdown documentation with API info, common responses, endpoints table, and auth schemes.
  function processSwaggerToMarkdown(swaggerSpec: any, apiGroupName: string): string { try { console.error(`[Process] Converting Swagger spec to markdown for: ${apiGroupName}`); // Extract basic API information const info = swaggerSpec.info || {}; const server = swaggerSpec.servers?.[0]?.url || 'https://'; const baseUrl = server; // Build the markdown content let markdown = `# ${apiGroupName} API\n\n`; markdown += `## API Info\n`; markdown += `- Title: ${info.title || apiGroupName}\n`; markdown += `- Version: ${info.version || 'N/A'}\n`; markdown += `- Base URL: ${baseUrl}\n\n`; // Common responses markdown += `## Responses\n`; markdown += `| Code | Description |\n`; markdown += `|------|-------------|\n`; markdown += `| 200 | Success! |\n`; markdown += `| 400 | Input Error |\n`; markdown += `| 401 | Unauthorized|\n`; markdown += `| 403 | Access Denied|\n`; markdown += `| 404 | Not Found |\n`; markdown += `| 429 | Rate Limited|\n`; markdown += `| 500 | Server Error|\n\n`; // Process endpoints markdown += `## Endpoints\n\n`; const paths = swaggerSpec.paths || {}; const pathKeys = Object.keys(paths).sort(); for (const path of pathKeys) { const pathInfo = paths[path]; const methods = Object.keys(pathInfo).filter(m => ['get', 'post', 'put', 'delete', 'patch'].includes(m.toLowerCase())); for (const method of methods) { const operation = pathInfo[method]; markdown += `### ${method.toUpperCase()} ${path}\n`; markdown += `${operation.summary || 'No summary'}\n`; // Parameters const parameters = operation.parameters || []; if (parameters.length > 0) { markdown += `| Param | In | Req | Type |\n`; markdown += `|-------|----|-----|------|\n`; for (const param of parameters) { markdown += `| ${param.name} | ${param.in} | ${param.required ? 'Y' : 'N'} | ${param.schema?.type || 'unknown'} |\n`; } } markdown += '\n'; } } // Authentication const securitySchemes = swaggerSpec.components?.securitySchemes || {}; if (Object.keys(securitySchemes).length > 0) { markdown += `## Auth\n`; for (const name in securitySchemes) { const scheme = securitySchemes[name]; markdown += `- ${name}: ${scheme.type}`; if (scheme.scheme) markdown += ` (${scheme.scheme})`; markdown += '\n'; } } console.error(`[Process] Successfully converted Swagger spec to markdown`); return markdown; } catch (error) { console.error(`[Error] Error processing Swagger to Markdown: ${error instanceof Error ? error.message : String(error)}`); return `# Error\n\n${error instanceof Error ? error.message : String(error)}`; } }