MCP YAML API

Instructions

Implementation Reference

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

  The MCP callTool request handler that executes the 'getUsers' tool by finding its API configuration and invoking the ApiClient to perform the API call based on the tool name.

  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-37 (schema)

  Builds the tool definitions including inputSchema for 'getUsers' from API config, with specific debug logging for this tool.

  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-38 (registration)

  Registers the listTools handler which exposes the 'getUsers' tool schema to MCP clients.

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

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

  Helper function that performs the actual API call for the 'getUsers' tool using fetch, interpolating parameters, handling body and headers from the apiConfig.

  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 };
    }
  }