{"id":41654432,"url":"https://github.com/universal-tool-calling-protocol/elixir-utcp","last_synced_at":"2026-02-21T18:02:12.138Z","repository":{"id":317068998,"uuid":"1065857785","full_name":"universal-tool-calling-protocol/elixir-utcp","owner":"universal-tool-calling-protocol","description":"An Elixir implementation of the Universal Tool Calling Protocol ","archived":false,"fork":false,"pushed_at":"2025-11-06T11:58:11.000Z","size":301,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T13:22:15.141Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/universal-tool-calling-protocol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T15:11:13.000Z","updated_at":"2025-11-06T11:58:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"87b10f26-44b2-4269-b72f-aece849f1eaa","html_url":"https://github.com/universal-tool-calling-protocol/elixir-utcp","commit_stats":null,"previous_names":["thanos/ex_utcp","universal-tool-calling-protocol/elixir-utcp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/universal-tool-calling-protocol/elixir-utcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Felixir-utcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Felixir-utcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Felixir-utcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Felixir-utcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/universal-tool-calling-protocol","download_url":"https://codeload.github.com/universal-tool-calling-protocol/elixir-utcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Felixir-utcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28731225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-24T16:22:41.314Z","updated_at":"2026-01-24T16:22:42.455Z","avatar_url":"https://github.com/universal-tool-calling-protocol.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ExUtcp\n\n[![Hex.pm](https://img.shields.io/hexpm/v/ex_utcp.svg)](https://hex.pm/packages/ex_utcp)\n[![Hex.pm](https://img.shields.io/hexpm/dt/ex_utcp.svg)](https://hex.pm/packages/ex_utcp)\n[![Hex.pm](https://img.shields.io/hexpm/l/ex_utcp.svg)](https://hex.pm/packages/ex_utcp)\n[![HexDocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ex_utcp)\n\nElixir implementation of the Universal Tool Calling Protocol (UTCP).\n\n\n\u003cimg width=\"512\" height=\"512\" alt=\"ex_utcp-2\" src=\"https://github.com/user-attachments/assets/a4f5592e-4d16-42b2-8e98-b79bd164df8b\" /\u003e\n\n\n\n\n## Introduction\n\nThe Universal Tool Calling Protocol (UTCP) is a standard for defining and interacting with tools across communication protocols. UTCP emphasizes scalability, interoperability, and ease of use.\n\nKey characteristics:\n* **Scalability**: Handles large numbers of tools and providers without performance degradation\n* **Interoperability**: Supports multiple provider types including HTTP, [WebSockets](https://tools.ietf.org/html/rfc6455), [gRPC](https://grpc.io/), and CLI tools\n* **Ease of Use**: Built on simple, well-defined patterns\n\n## Features\n\n* Transports: HTTP, CLI, WebSocket, gRPC, GraphQL, MCP, TCP/UDP, WebRTC\n* Streaming support across all transports\n* OpenAPI Converter: Automatic API discovery and tool generation\n* Variable substitution via environment variables or `.env` files\n* In-memory repository for providers and tools\n* Authentication: API Key, Basic, OAuth2\n* Connection pooling and lifecycle management\n* Test configuration with integration test exclusion by default\n* Advanced Search: Multiple algorithms with fuzzy matching and semantic search\n* Monitoring and Metrics: Telemetry, PromEx, health checks, and performance monitoring\n* Comprehensive test suite with 497+ tests\n\n## Installation\n\nAdd `ex_utcp` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:ex_utcp, \"~\u003e 0.2.0\"}\n  ]\nend\n```\n\n## Getting Started\n\n### Basic Usage\n\n```elixir\nalias ExUtcp.{Client, Config}\n\n# Create a client configuration\nconfig = Config.new(providers_file_path: \"providers.json\")\n\n# Start a UTCP client\n{:ok, client} = Client.start_link(config)\n\n# Search for tools\n{:ok, tools} = Client.search_tools(client, \"\", 10)\n\n# Call a tool\n{:ok, result} = Client.call_tool(client, \"provider.tool_name\", %{\"arg\" =\u003e \"value\"})\n```\n\n### Programmatic Provider Registration\n\n```elixir\nalias ExUtcp.{Client, Config, Providers}\n\n# Create a client\nconfig = Config.new()\n{:ok, client} = Client.start_link(config)\n\n# Create an HTTP provider\nprovider = Providers.new_http_provider([\n  name: \"my_api\",\n  url: \"https://api.example.com/tools\",\n  http_method: \"POST\"\n])\n\n# Register the provider\n{:ok, tools} = Client.register_tool_provider(client, provider)\n\n# Call a discovered tool\n{:ok, result} = Client.call_tool(client, \"my_api.echo\", %{\"message\" =\u003e \"Hello!\"})\n```\n\n### CLI Provider Example\n\n```elixir\nalias ExUtcp.{Client, Config, Providers}\n\n# Create a client\nconfig = Config.new()\n{:ok, client} = Client.start_link(config)\n\n# Create a CLI provider\nprovider = Providers.new_cli_provider([\n  name: \"my_script\",\n  command_name: \"python my_script.py\",\n  working_dir: \"/path/to/script\"\n])\n\n# Register the provider\n{:ok, tools} = Client.register_tool_provider(client, provider)\n\n# Call a tool\n{:ok, result} = Client.call_tool(client, \"my_script.greet\", %{\"name\" =\u003e \"World\"})\n```\n\n## Configuration\n\n### Provider Configuration File\n\nCreate a `providers.json` file to define your providers:\n\n```json\n{\n  \"providers\": [\n    {\n      \"name\": \"http_api\",\n      \"type\": \"http\",\n      \"http_method\": \"POST\",\n      \"url\": \"https://api.example.com/tools\",\n      \"content_type\": \"application/json\",\n      \"headers\": {\n        \"User-Agent\": \"ExUtcp/0.2.0\"\n      },\n      \"auth\": {\n        \"type\": \"api_key\",\n        \"api_key\": \"${API_KEY}\",\n        \"location\": \"header\",\n        \"var_name\": \"Authorization\"\n      }\n    },\n    {\n      \"name\": \"cli_tool\",\n      \"type\": \"cli\",\n      \"command_name\": \"python my_tool.py\",\n      \"working_dir\": \"/opt/tools\",\n      \"env_vars\": {\n        \"PYTHONPATH\": \"/opt/tools\"\n      }\n    }\n  ]\n}\n```\n\n### Variable Substitution\n\nUTCP supports variable substitution using `${VAR}` or `$VAR` syntax:\n\n```elixir\n# Load variables from .env file\n{:ok, env_vars} = Config.load_from_env_file(\".env\")\n\nconfig = Config.new(\n  variables: env_vars,\n  providers_file_path: \"providers.json\"\n)\n```\n\n## OpenAPI Converter\n\nThe OpenAPI Converter automatically discovers and converts OpenAPI specifications into UTCP tools.\n\n### Basic Usage\n\n```elixir\nalias ExUtcp.{Client, Config}\n\n# Create a client\n{:ok, client} = Client.start_link(%{providers_file_path: nil, variables: %{}})\n\n# Convert OpenAPI spec from URL\n{:ok, tools} = Client.convert_openapi(client, \"https://api.example.com/openapi.json\")\n\n# Convert OpenAPI spec from file\n{:ok, tools} = Client.convert_openapi(client, \"path/to/spec.yaml\")\n\n# Convert with options\n{:ok, tools} = Client.convert_openapi(client, spec, %{\n  prefix: \"my_api\",\n  auth: %{type: \"api_key\", api_key: \"Bearer ${API_KEY}\"}\n})\n```\n\n### Supported Formats\n\n- OpenAPI 2.0 (Swagger)\n- OpenAPI 3.0\n- JSON and YAML specifications\n- URL and file-based specifications\n\n### Authentication Mapping\n\nThe converter automatically maps OpenAPI security schemes to UTCP authentication:\n\n- API Key authentication\n- HTTP Basic authentication\n- HTTP Bearer authentication\n- OAuth2 flows\n- OpenID Connect\n\n## Architecture\n\nThe library is organized into several main components:\n\n* ExUtcp.Client - Main client interface\n* ExUtcp.Config - Configuration management\n* ExUtcp.Providers - Provider implementations for different protocols\n* ExUtcp.Transports - Transport layer implementations\n* ExUtcp.Tools - Tool definitions and management\n* ExUtcp.Repository - Tool and provider storage\n* ExUtcp.OpenApiConverter - OpenAPI specification conversion\n\n## Implementation Status\n\n### Gap Analysis: UTCP Implementations Comparison\n\n| Feature Category | Python UTCP | Go UTCP | Elixir UTCP | Elixir Coverage |\n|------------------|-------------|---------|-------------|-----------------|\n| **Core Architecture** | | | | |\n| Core Client | Complete | Complete | Complete | 100% |\n| Configuration | Complete | Complete | Enhanced | 100% |\n| Variable Substitution | Complete | Complete | Complete | 100% |\n| **Transports** | | | | |\n| HTTP/HTTPS | Complete | Complete | Complete | 100% |\n| CLI | Complete | Complete | Complete | 100% |\n| WebSocket | Complete | Complete | Complete | 100% |\n| gRPC | Complete | Complete | Complete | 100% |\n| GraphQL | Complete | Complete | Complete | 100% |\n| MCP | Complete | Complete | Complete | 100% |\n| SSE | Complete | Complete | Complete | 100% |\n| Streamable HTTP | Complete | Complete | Complete | 100% |\n| TCP/UDP | Complete | Complete | Complete | 100% |\n| WebRTC | Complete | Complete | Complete | 100% |\n| **Authentication** | | | | |\n| API Key | Complete | Complete | Complete | 100% |\n| Basic Auth | Complete | Complete | Complete | 100% |\n| OAuth2 | Complete | Complete | Complete | 100% |\n| **Advanced Features** | | | | |\n| Streaming | Complete | Complete | Complete | 100% |\n| Connection Pooling | Complete | Complete | Complete | 100% |\n| Error Recovery | Complete | Complete | Complete | 100% |\n| OpenAPI Converter | Complete | Complete | Complete | 100% |\n| Tool Discovery | Complete | Complete | Complete | 100% |\n| Search | Advanced | Advanced | Complete | 100% |\n| **Testing** | | | | |\n| Unit Tests | Complete | Complete | Complete | 100% |\n| Integration Tests | Complete | Complete | Complete | 100% |\n| Mock Testing | Complete | Complete | Complete | 100% |\n| Test Coverage | High | High | High | 100% |\n| **Performance** | | | | |\n| Connection Management | Optimized | Optimized | Optimized | 100% |\n| Memory Usage | Optimized | Optimized | Optimized | 100% |\n| Throughput | High | High | High | 100% |\n| **Monitoring** | | | | |\n| Telemetry | Complete | Complete | Complete | 100% |\n| Metrics | Complete | Complete | Complete | 100% |\n| Health Checks | Complete | Complete | Complete | 100% |\n| Performance Monitoring | Complete | Complete | Complete | 100% |\n| **Documentation** | | | | |\n| API Docs | Complete | Complete | Complete | 100% |\n| Examples | Complete | Complete | Complete | 100% |\n| Guides | Complete | Complete | Complete | 100% |\n\n### Priority Recommendations\n\n#### High Priority\n- [x] OpenAPI Converter: Automatic API discovery and tool generation\n- [x] TCP/UDP Transport: Low-level network protocols\n- [x] Advanced Search: Sophisticated search algorithms\n- [x] Monitoring: Metrics and health checks\n- [x] WebRTC Transport: Peer-to-peer communication\n\n#### Medium Priority\n- [ ] Batch Operations: Multiple tool calls\n\n#### Low Priority\n- [ ] Custom Variable Loaders: Beyond .env files\n- [ ] API Documentation Generation\n\n### Implementation Status\n\n#### Completed Features\n- 8 transports: HTTP, CLI, WebSocket, gRPC, GraphQL, MCP, TCP/UDP, WebRTC\n- Streaming support across all transports\n- OpenAPI Converter: Automatic API discovery and tool generation\n- Authentication: API Key, Basic, OAuth2\n- Connection pooling and lifecycle management\n- Error recovery with retry logic\n- Test configuration with integration test exclusion by default\n- Advanced Search: Multiple algorithms with fuzzy matching and semantic search\n- Monitoring and Metrics: Telemetry, PromEx, health checks, and performance monitoring\n- 497+ tests with comprehensive coverage\n- Production examples for all transports\n\n#### Missing Features\n- Batch Operations: Multiple tool calls\n\n### Roadmap\n\n#### Phase 1: Core Transports (Completed)\n- [x] HTTP/HTTPS, CLI, WebSocket, gRPC, GraphQL, MCP\n\n#### Phase 2: Enhanced Features (Completed)\n- [x] OpenAPI Converter\n- [x] TCP/UDP Transport\n- [x] Advanced Search\n- [x] Monitoring and Metrics\n\n#### Phase 3: Extended Protocols (Completed)\n- [x] WebRTC Transport\n\n#### Phase 4: Enterprise Features\n- [ ] Batch Operations\n- [ ] Custom Variable Loaders\n- [ ] API Documentation Generation\n\n## Supported Transports\n\n### Implemented\n- HTTP/HTTPS: REST API integration with [OpenAPI](https://swagger.io/specification/) support\n- CLI: Command-line tool integration\n- [WebSocket](https://tools.ietf.org/html/rfc6455): Real-time communication\n- [gRPC](https://grpc.io/): High-performance RPC calls with [Protocol Buffers](https://developers.google.com/protocol-buffers)\n- [GraphQL](https://graphql.org/): GraphQL API integration with HTTP/HTTPS\n- [MCP](https://modelcontextprotocol.io/): Model Context Protocol integration with [JSON-RPC 2.0](https://www.jsonrpc.org/specification)\n- [TCP/UDP](https://tools.ietf.org/html/rfc793): Low-level network protocols with connection management\n- [WebRTC](https://www.w3.org/TR/webrtc/): Peer-to-peer communication with data channels and NAT traversal\n\n### Planned\n- Additional enterprise features and optimizations\n\n## Examples\n\nSee `examples/` directory:\n- `http_client.exs` - HTTP provider\n- `cli_client.exs` - CLI provider\n- `websocket_client.exs` - WebSocket provider\n- `grpc_client.exs` - gRPC provider\n- `graphql_example.exs` - GraphQL provider\n- `mcp_example.exs` - MCP provider\n- `tcp_udp_example.exs` - TCP/UDP provider\n- `streaming_examples.exs` - Streaming examples\n- `openapi_example.exs` - OpenAPI Converter examples\n- `search_example.exs` - Advanced search examples\n- `monitoring_example.exs` - Monitoring and metrics examples\n- `webrtc_example.exs` - WebRTC peer-to-peer examples\n\n## Testing\n\n```bash\n# Unit tests only (default - excludes integration tests)\nmix test\n\n# All tests including integration tests\nmix test --include integration\n\n# Integration tests only\nmix test --only integration\n```\n\nThe test suite is configured to exclude integration tests by default for faster development cycles. Integration tests require external services and are run separately.\n\n## Advanced Search\n\nExUtcp provides sophisticated search capabilities for discovering tools and providers:\n\n### Search Algorithms\n\n- **Exact Search**: Precise matching for tool and provider names\n- **Fuzzy Search**: Approximate matching using FuzzyCompare library for handling typos and variations\n- **Semantic Search**: Intelligent matching using Haystack full-text search and keyword analysis\n- **Combined Search**: Merges results from all algorithms for comprehensive discovery\n\n### Search Features\n\n- **Multi-field Search**: Search across tool names, descriptions, parameters, and responses\n- **Advanced Filtering**: Filter by provider, transport type, tags, and capabilities\n- **Result Ranking**: Intelligent scoring based on relevance, popularity, quality, and context\n- **Security Scanning**: TruffleHog integration for detecting sensitive data in search results\n- **Search Suggestions**: Auto-complete and suggestion system for improved user experience\n- **Similar Tool Discovery**: Find related tools based on semantic similarity\n\n### Basic Usage\n\n```elixir\n# Start client\n{:ok, client} = ExUtcp.Client.start_link()\n\n# Search with different algorithms\nexact_results = ExUtcp.Client.search_tools(client, \"get_user\", %{algorithm: :exact})\nfuzzy_results = ExUtcp.Client.search_tools(client, \"get_usr\", %{algorithm: :fuzzy, threshold: 0.6})\nsemantic_results = ExUtcp.Client.search_tools(client, \"user management\", %{algorithm: :semantic})\n\n# Advanced search with filters and security scanning\nadvanced_results = ExUtcp.Client.search_tools(client, \"api\", %{\n  algorithm: :combined,\n  filters: %{transports: [:http, :websocket], providers: [\"my_api\"]},\n  security_scan: true,\n  filter_sensitive: true,\n  limit: 10\n})\n\n# Get search suggestions\nsuggestions = ExUtcp.Client.get_search_suggestions(client, \"us\", limit: 5)\n\n# Find similar tools\nsimilar_tools = ExUtcp.Client.find_similar_tools(client, \"get_user\", limit: 3)\n```\n\n## Monitoring and Metrics\n\nExUtcp provides comprehensive monitoring capabilities for production deployments:\n\n### Monitoring Features\n\n- **Telemetry Integration**: Automatic telemetry events for all UTCP operations\n- **Prometheus Metrics**: PromEx integration for metrics collection and visualization\n- **Health Checks**: System health monitoring for transports and components\n- **Performance Monitoring**: Operation timing, statistical analysis, and alerting\n- **Custom Metrics**: Support for application-specific metrics and dashboards\n\n### Telemetry Events\n\nExUtcp emits telemetry events for:\n- Tool calls with duration, success/failure, and metadata\n- Search operations with algorithm, filters, and result counts\n- Provider registration and deregistration\n- Connection establishment and lifecycle events\n- System health and performance metrics\n\n### Basic Usage\n\n```elixir\n# Start monitoring system\nExUtcp.Monitoring.start()\n\n# Get system metrics\nmetrics = ExUtcp.Client.get_monitoring_metrics(client)\n\n# Get health status\nhealth = ExUtcp.Client.get_health_status(client)\n\n# Get performance summary\nperformance = ExUtcp.Client.get_performance_summary(client)\n\n# Record custom metrics\nExUtcp.Monitoring.Performance.record_custom_metric(\"api_requests\", :counter, 1, %{endpoint: \"/users\"})\n```\n\n### Prometheus Integration\n\nConfigure PromEx in your application:\n\n```elixir\n# config/config.exs\nconfig :ex_utcp, ExUtcp.Monitoring.PromEx,\n  disabled: false,\n  manual_metrics_start_delay: :no_delay,\n  drop_metrics_groups: [],\n  grafana: [\n    host: \"http://localhost:3000\",\n    username: \"admin\",\n    password: \"admin\"\n  ]\n```\n\n## Comparison with Python UTCP\n\nExUtcp is an independent Elixir implementation of the UTCP specification. For a detailed comparison with the official Python implementation, see our [Comparison Study](docs/COMPARISON_STUDY.md).\n\n**Key Differences**:\n- **ExUtcp**: 8 transports (includes WebSocket, gRPC, GraphQL, TCP/UDP, WebRTC)\n- **Python UTCP**: 6 transports (HTTP, SSE, CLI, MCP, Text, Streamable HTTP)\n- **ExUtcp**: Advanced search, monitoring, and health checks\n- **Python UTCP**: Plugin architecture, official implementation\n\nBoth implementations follow the UTCP specification and excel in different areas.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [UTCP Website](https://www.utcp.io/)\n- [Go Implementation](https://github.com/universal-tool-calling-protocol/go-utcp)\n- [Python Implementation](https://github.com/universal-tool-calling-protocol/python-utcp)\n- [Hex Package](https://hex.pm/packages/ex_utcp)\n- [HexDocs](https://hexdocs.pm/ex_utcp)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Felixir-utcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funiversal-tool-calling-protocol%2Felixir-utcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Felixir-utcp/lists"}