MCP YAML API

Instructions

Implementation Reference

• src/lib/mcp.ts:42-63 (handler)

  The call tool handler that executes any tool, including 'getUserWithPathParameters'. It matches the tool name to an API config and invokes the API client with the provided arguments.

    const apiClient = new ApiClient();
    this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
      
      const tool = this.tools.find(t => t.name === request.params.name)
      if (!tool) { throw new Error(`Tool ${request.params.name} not found`) }
  
      const apiConfig = this.apis.find((api: ApiConfig) => api.name === tool.name)
      if (!apiConfig) { throw new Error(`API configuration for tool ${tool.name} not found`)}
      
      const response = await apiClient.callApi(apiConfig, request.params.arguments);
      console.error("Response:", response);
      
      return {
        content: [
          {
            type: 'text',
            text: typeof response === 'string' ? response : JSON.stringify(response, null, 2),
          },
        ],
      };
    });
  }

• src/lib/tools-builder.ts:5-38 (schema)

  Generates input schemas for all tools by parsing URL path/query parameters and body properties from the API configuration. Used to create the tool definition for 'getUserWithPathParameters'.

  export const buildToolsFromApiConfigArray = (apiConfigArray: any[]): any[] =>
    apiConfigArray.map((apiConfig: any) => {
      // Get parameters and query from a url like http://localhost:3000/users/{id}?page={page}&limit={limit}
      const parametersAndQuerys = getUrlParametersAndQuerys(apiConfig.url);
      const method = apiConfig.method?.toUpperCase();
      const body: ApiBodyProperty[] | undefined = apiConfig.options?.body;
      const schema = getBodyProperties(body);
  
      const properties  = { ...parametersAndQuerys, ...schema }
      if(apiConfig.name === 'getUsers' ) {
        // console.error('parametersAndQuerys', parametersAndQuerys)
        // console.error('schema', getPropertiesFromSchema(schema))
        console.error('parametersAndQuerys', parametersAndQuerys)
        console.error('body', body)
        console.error('properties', properties)
      }
  
      return {
        name: apiConfig.name,
        description: apiConfig.description,
        inputSchema: {
          type: "object",
          properties: properties,
          required: (body || []).filter((p: ApiBodyProperty) => p.required).map((p: ApiBodyProperty) => p.name),
        },
        annotations: {
          title: apiConfig.description,
          readOnlyHint: method === "GET",
          destructiveHint: method === "DELETE",
          idempotentHint: method === "GET" || method === "DELETE",
          openWorldHint: true,
        },
      };
    });

• src/lib/mcp.ts:35-39 (registration)

  Registers the listTools handler, which returns the list of available tools including 'getUserWithPathParameters'.

  private registerListToolsHandler() {
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return { tools: this.tools };
    });
  }

• src/lib/mcp.ts:21-33 (registration)

  In the McpServer constructor, builds the tools array from API configs (including schema and name for getUserWithPathParameters) and sets up the MCP server with tools capability, registering handlers.

    this.tools = buildToolsFromApiConfigArray(this.apis);
    this.server = new Server({
      name: this.metadata.name || 'mcp-yaml-api',
      description: this.metadata.description || 'MCP Yaml API',
      version: this.metadata.version || '1.0.0'
    }, {
      capabilities: {
        tools: {}
      }
    });
    this.registerListToolsHandler();
    this.registerCallToolHandler();
  }

• src/lib/api-client.ts:8-62 (helper)

  The API client that performs the actual HTTP request for the tool, handling path parameter replacement, body construction, headers, etc. Invoked by the tool handler for 'getUserWithPathParameters'.

  async callApi(apiConfig: ApiConfig, args?: Record<string, any>): Promise<any> {
    const { url, method, options } = apiConfig;
  
    let endpoint = url;
    let headers: Record<string, string> = {};
    let body: Record<string, any> = {};
  
    // Interpolación de path & query params
    if (endpoint && args) {
      endpoint = endpoint.replace(/\{(\w+)\}/g, (_: string, key: string) => args[key] ?? `{${key}}`);
    }
  
    // Headers
    if (options?.headers) {
      for (const [k, v] of Object.entries(options.headers)) {
        headers[k] = String(v);
      }
    }
    // API Token
    if ('api-token' in apiConfig && apiConfig['api-token']) {
      headers['Authorization'] = `Bearer ${process.env.API_TOKEN || ''}`;
    }
  
    // Body
    if (options?.body) {
      for (const b of options.body) {
        if (args && args[b.name] !== undefined) {
          body[b.name] = args[b.name];
        } else if (b.default !== undefined) {
          body[b.name] = b.default;
        }
      }
    }
  
    const fetchOptions: RequestInit = {
      method: method,
      headers,
    };
    
    if (["POST", "PUT", "PATCH"].includes((method || '').toUpperCase())) {
      fetchOptions.body = JSON.stringify(body);
    }
  
    try {
      const response = await fetch(endpoint, fetchOptions);
      const contentType = response.headers.get('content-type') || '';
      if (contentType.includes('application/json')) {
        return await response.json();
      } else {
        return await response.text();
      }
    } catch (error: any) {
      return { error: error.message };
    }
  }