@utcp/http: HTTP Communication Protocol Plugin for UTCP

The @utcp/http package provides the HTTP communication protocol implementation for the Universal Tool Calling Protocol (UTCP) client. It enables the UtcpClient to interact with RESTful HTTP/HTTPS APIs, supporting various authentication methods, URL path parameters, and automatic tool discovery from UTCP Manuals or OpenAPI specifications.

Features

HTTP CallTemplate: Defines the specific configuration for HTTP-based tools (HttpCallTemplate), including HTTP method, URL, content type, authentication, and headers.
HttpCommunicationProtocol: Implements the CommunicationProtocol interface for HTTP interactions:
- Tool Discovery: Automatically registers tools from remote UTCP Manuals or OpenAPI (v2/v3) specifications (JSON/YAML).
- Tool Execution: Handles GET, POST, PUT, DELETE, PATCH requests with:
  - URL path parameter substitution ({param_name}).
  - Query parameter handling.
  - Request body mapping (body_field).
  - Custom header fields.
- Authentication Support: Integrates ApiKeyAuth (header, query, cookie), BasicAuth, and OAuth2Auth (client credentials flow with token caching and refresh).
- Security: Enforces HTTPS or localhost connections for discovery and tool calls to prevent Man-in-the-Middle (MITM) attacks.
OpenApiConverter: A utility for parsing OpenAPI specifications and transforming them into UTCP Tool definitions that leverage HttpCallTemplate.

Installation

bun add @utcp/http @utcp/core axios js-yaml

Note: @utcp/core is a peer dependency, and axios and js-yaml are direct dependencies required for HTTP communication and OpenAPI parsing.

Usage

To use the HTTP plugin, you must register its capabilities with the core UtcpClient at application startup. This is typically done by calling the registerHttpPlugin() function exported from @utcp/http.

// From your application's entry point

import { UtcpClient } from '@utcp/core/client/utcp_client';
import { UtcpClientConfigSchema } from '@utcp/core/client/utcp_client_config';
import { registerHttpPlugin } from '@utcp/http'; // Import the registration function

// --- IMPORTANT: Register the HTTP plugin once at the start of your application ---
registerHttpPlugin();
// -------------------------------------------------------------------------------

async function main() {
  const client = await UtcpClient.create(
    UtcpClientConfigSchema.parse({
      // Define variables for substitution in call templates (e.g., for API keys)
      variables: {
        OPENLIBRARY_API_KEY_1: 'your-openlibrary-key' // Example for OpenAPI-derived template
      },
      // Manually define HTTP call templates in the config to be registered at startup
      manual_call_templates: [
        {
          name: 'openlibrary_api',
          call_template_type: 'http',
          url: 'https://openlibrary.org/static/openapi.json', // URL pointing to an OpenAPI spec
          http_method: 'GET'
          // Auth fields would be auto-generated by OpenApiConverter, but variables must be supplied
        }
      ],
      // Or load variables from .env files
      load_variables_from: [
        { type: 'dotenv', env_file_path: './.env' }
      ]
    })
  );

  console.log('HTTP Plugin active. Searching for tools...');

  // Search for tools (e.g., from the OpenLibrary API)
  const bookSearchTools = await client.searchTools('search for books by author');
  console.log('Found OpenLibrary tools:', bookSearchTools.map(t => t.name));

  // Example: Call a tool (e.g., 'openlibrary_api.read_search_authors_json_search_authors_json_get')
  if (bookSearchTools.length > 0) {
    try {
      const toolToCall = bookSearchTools.find(t => t.name.includes('search_authors'));
      if (toolToCall) {
        console.log(`Calling tool: ${toolToCall.name}`);
        const result = await client.callTool(toolToCall.name, { q: 'J. K. Rowling' });
        console.log('Tool call result:', result);
      } else {
        console.warn('No author search tool found for example call.');
      }
    } catch (error) {
      console.error('Error calling HTTP tool:', error);
    }
  }

  await client.close(); // Clean up HTTP client sessions, OAuth tokens, etc.
}

main().catch(console.error);

Development

Refer to the root README.md for monorepo development and testing instructions.