simplifier-mcp

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { SimplifierClient } from "../client/simplifier-client.js"; import { GetPromptResult } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; /** * Generates the prompt content for creating a connector from an API specification or description. * * This function creates a comprehensive, multi-phase prompt that guides the LLM through: * 1. Fetching and analyzing the API specification (OpenAPI/Swagger) or informal description * 2. Analyzing available endpoints * 3. Presenting endpoints for user selection * 4. Creating the connector, connector calls, and datatypes * * @param openapiInput - The API specification URL, OpenAPI/Swagger spec content (YAML/JSON), or informal REST API description * @param connectorName - Optional custom connector name * @returns The prompt text */ export function generateOpenAPIConnectorPromptText( openapiInput: string, connectorName?: string ): string { const finalConnectorName = connectorName || '<will be derived from API specification>'; const isUrl = openapiInput.startsWith('http://') || openapiInput.startsWith('https://'); return `# Create Simplifier Connector from API Specification or Description ## Objective Create a complete Simplifier connector with connector calls and datatypes based on an API specification (OpenAPI/Swagger YAML/JSON) or an informal REST API description. ## Phase 1: Fetch and Analyze the API Specification or Description ${isUrl ? `1. Fetch the API specification or description from: ${openapiInput} - Use appropriate tools (curl, wget, or web fetch) to download the content - If it's a structured format (YAML/JSON), parse it accordingly - If it's an informal description, read and analyze the text` : `1. Analyze the provided API specification or description: - If structured format (OpenAPI/Swagger): Parse the YAML/JSON structure - If informal description: Read and extract the REST API information - Identify the format and proceed accordingly` } 2. Extract key information: - API title and description - Base URL / servers - Authentication requirements (API keys, OAuth, etc.) - Version information ## Phase 2: Authentication Fetch the existing Login Methods with simplifier://loginmethods. Match the Login Methods by type with the authentication requirements described in the API specification or description. In case the API requires an OAuth Token, then fetch the OAuth Clients from simplifier://oauthclients. In case the user does not select an existing Login Method in Phase 3.1, we will present the OAuth Clients to the user. List the Login Methods and show them to the user before Phase 3.1. The authentication requirements can be complex. We will guide the user through this flow of steps: 1. Present existing Login Methods and let the user select one, or skip this step 2. In case of OAuth (and if no Login Method has been selected in the step before), then present the existing OAuth Clients and let the user select one, or skip this step 3. In case of Basic Auth (and if no Login Method has been selected or created in the steps before) then aks the user about username/password or skip this step 4. In case of need of an API Key in a Header (and if no Login Method has been selected or created in the steps before) ask the user for the API Key or skip this step Details about step 4: In case the API needs an API-key, that has to be passed as a query parameter, then each connector call needs the additional input parameter configured. Only in case the API needs an API-key, that has to be passed as a header, then create a Login Method of type token with a custom header name according to the API key header name. Assign the eventually created or selected Login Method to the connector in the end. ## Phase 3: User Selections for Authentication ### 3.1 Ask user for Login Method In case existing Login Methods, that fit by name and by type (e.g. Token, OAuth or UserCredentials), are found with simplifier://loginmethods, then ask the user, whether and which Login Method to assign in the end: "Shall one of the existing Login Methods be used?" ### 3.2 Ask user about creating an OAuth Login Method In case OAuth is required and no fitting Login Method is existing, but auth clients are existing (simplifier://oauthclients), then present the list of oauth clients to the user and ask whether and based on which client a Login Method should be created: "Shall a Login Method ${finalConnectorName}OAuthLM be created based on one of these OAuth Clients?" ### 3.3 Ask user about creating Login Method for Basic Auth In case we have not yet handeled authentication and the API supports Basic Auth, then create a login method with the name ${finalConnectorName}BasicLM of the type UserCredentials and ask the user for username and password. Also give the option, that the user can later create and assign a login method himself: "Enter Username and Password to create the Login Mehtod ${finalConnectorName}BasicLM or alternatively later create and assign a Login Method yourself." ### 3.4 Ask user about creating Login Method for API Key In case the API needs an API-key, that has to be passed as a header, then create a Login Method of type token with a custom header name according to the API key header name. Ask the user for the API-key - otherwise the user can update the key in the login method himself: "Give the API key for the Login Method" ## Phase 4: Analyze and Present Endpoints Analyze all available endpoints from the API specification or description and present them to the user in this format: \`\`\` Available Endpoints: ================== 1. [GET] /users - List all users Parameters: page (query, optional), limit (query, optional) Response: Array of User objects 2. [POST] /users - Create a new user Body: User object (name, email, role) Response: Created User object with ID 3. [GET] /users/{id} - Get user by ID Parameters: id (path, required) Response: Single User object ... (continue for all endpoints) Authentication: Bearer Token (API Key in header) Base URL: https://api.example.com/v1 \`\`\` ## Phase 5: User Selection for Endpoints After presenting the endpoints, ask the user: "Which endpoints would you like to implement? You can specify: - A comma separated list of endoints - All endpoints (type 'all') - Endpoint patterns (e.g., all GET endpoints, all /users endpoints)" Wait for user response before proceeding to Phase 4. ## Phase 6: Create Connector and Components Once the user has selected endpoints, create: ### 6.1 Connector Configuration - **Name**: ${finalConnectorName} - **Namespace**: con/${finalConnectorName} - **Base URL**: From API specification or description - **Authentication**: Configure based on authentication requirements - **Headers**: Any required default headers ### 6.2 For Each Selected Endpoint: #### Create Request/Response Datatypes: - Analyze request body schema → Create request datatype - Analyze response schema → Create response datatype - Handle nested objects → Create additional datatypes as needed - Use Simplifier base types (String, Integer, Boolean, Date, Float, Any) for primitives - Create struct types for complex objects - Create collection types for arrays #### Create Connector Call: - **Name**: Descriptive name (e.g., "getUserById", "createUser") - **HTTP Method**: From API specification or description - **Path**: From API specification or description (with path parameters) - **Parameters**: Query, path, header parameters from the specification or description - **Request Body**: Link to request datatype - **Response**: Link to response datatype - **Documentation**: From API specification or description ### 6.3 Create All Components: Use the Simplifier MCP tools to create: 1. All datatypes (in dependency order - base types first) 2. The connector 3. All connector calls ### 6.4 Provide Summary: Generate a summary report: \`\`\` ✅ Connector Created: ${finalConnectorName} 📦 Datatypes Created: <count> datatypes in namespace con/${finalConnectorName} 🔌 Connector Calls Created: <count> calls 📚 Documentation: <brief description> Next Steps: - Test the connector calls in Simplifier - Configure authentication credentials - Add error handling as needed \`\`\` ## Important Guidelines: 1. **Datatype Creation Order**: Create datatypes in the correct order (dependencies first) 2. **Naming Conventions**: Use clear, consistent naming (e.g., UserRequest, UserResponse) 3. **Error Handling**: Note which endpoints may need special error handling 4. **Authentication**: Clearly document authentication requirements 5. **Validation**: Ensure all required fields are marked as required in datatypes 6. **Documentation**: Include API descriptions in all components ## Available Tools: You have access to these Simplifier MCP tools: - \`datatype-update\`: Create/update datatypes - \`connector-update\`: Create/update connectors - \`connector-call-update\`: Create/update connector calls Use the resources to check existing connectors and datatypes in the namespace. --- **Start with Phase 1**: ${isUrl ? 'Fetch' : 'Analyze'} the API specification or description and extract key information.`; } /** * The prompt callback for the MCP server. * Handles requests to create a Simplifier connector from an API specification or description. */ export function openAPIConnectorPromptCallback(args: { openapi_url_or_spec: string; connector_name?: string | undefined; }): GetPromptResult { const promptText = generateOpenAPIConnectorPromptText( args.openapi_url_or_spec, args.connector_name ); return { description: 'Multi-phase workflow for creating a Simplifier connector from an API specification (OpenAPI/Swagger) or informal REST API description', messages: [ { role: 'user' as const, content: { type: 'text' as const, text: promptText } } ] }; } /** * Registers the API connector creation prompt with the MCP server. * This prompt supports both structured API specifications (OpenAPI/Swagger) and informal REST API descriptions. * * @param server - The MCP server instance * @param _simplifier - The Simplifier API client (unused for now, kept for consistency) */ export function registerOpenAPIConnectorPrompt( server: McpServer, _simplifier: SimplifierClient ): void { server.prompt( 'create-connector-from-openapi', 'Guided workflow to create a Simplifier connector from an API specification (OpenAPI/Swagger) or informal REST API description. Analyzes endpoints, lets you select which to implement, and creates the connector with calls and datatypes.', { openapi_url_or_spec: z.string().describe( 'API specification URL, OpenAPI/Swagger spec content (YAML/JSON), or an informal textual description of a REST API' ), connector_name: z.string().optional().describe( 'Custom name for the connector (optional, defaults to the API title from the specification or a suitable name from the description)' ) }, openAPIConnectorPromptCallback ); }