[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-universal-tool-calling-protocol--python-utcp":3,"tool-universal-tool-calling-protocol--python-utcp":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":79,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":87,"forks":88,"last_commit_at":89,"license":90,"difficulty_score":91,"env_os":92,"env_gpu":93,"env_ram":93,"env_deps":94,"category_tags":105,"github_topics":106,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":115,"updated_at":116,"faqs":117,"releases":158},3758,"universal-tool-calling-protocol\u002Fpython-utcp","python-utcp","Official python implementation of UTCP. UTCP is an open standard that lets AI agents call any API directly, without extra middleware.","python-utcp 是通用工具调用协议（UTCP）的官方 Python 实现，旨在让 AI 智能体能够直接调用各类 API，无需依赖额外的中间件。它主要解决了当前 AI 生态中工具接入标准不一、集成流程繁琐以及扩展性受限的痛点，通过统一的开放标准简化了智能体与外部服务的交互过程。\n\n这款工具非常适合需要构建灵活 AI 应用的开发者及研究人员使用。无论是希望快速对接 HTTP 接口、命令行工具，还是探索 Model Context Protocol (MCP) 的专业工程师，都能从中受益。\n\npython-utcp 的核心亮点在于其模块化与插件化架构。它将核心逻辑与通信协议分离，支持通过插件轻松扩展 HTTP、SSE、CLI、MCP 等多种通信方式，甚至允许开发者自定义存储和搜索策略。这种设计不仅确保了系统在面对大量工具时的高性能与可扩展性，还极大地提升了互操作性。基于简洁明确的 Pydantic 数据模型，python-utcp 降低了开发门槛，让构建安全、可扩展的 AI 工具链变得更加直观高效。","# Universal Tool Calling Protocol (UTCP)\n\n[![Follow Org](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Ffollowers\u002Funiversal-tool-calling-protocol?label=Follow%20Org&logo=github)](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol)\n[![PyPI Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Funiversal-tool-calling-protocol_python-utcp_readme_00190256c29b.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Futcp)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Funiversal-tool-calling-protocol\u002Fpython-utcp)](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fblob\u002Fmain\u002FLICENSE)\n[![CDTM S23](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCDTM-S23-0b84f3)](https:\u002F\u002Fcdtm.com\u002F)\n\n## Introduction\n\nThe Universal Tool Calling Protocol (UTCP) is a secure, scalable standard for defining and interacting with tools across a wide variety of communication protocols. UTCP 1.0.0 introduces a modular core with a plugin-based architecture, making it more extensible, testable, and easier to package.\n\nIn contrast to other protocols, UTCP places a strong emphasis on:\n\n*   **Scalability**: UTCP is designed to handle a large number of tools and providers without compromising performance.\n*   **Extensibility**: A pluggable architecture allows developers to easily add new communication protocols, tool storage mechanisms, and search strategies without modifying the core library.\n*   **Interoperability**: With a growing ecosystem of protocol plugins (including HTTP, SSE, CLI, and more), UTCP can integrate with almost any existing service or infrastructure.\n*   **Ease of Use**: The protocol is built on simple, well-defined Pydantic models, making it easy for developers to implement and use.\n\n\n![MCP vs. UTCP](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Funiversal-tool-calling-protocol_python-utcp_readme_d966f4184ea9.png)\n\n## Repository Structure\n\nThis repository contains the complete UTCP Python implementation:\n\n- **[`core\u002F`](core\u002F)** - Core `utcp` package with foundational components ([README](core\u002FREADME.md))\n- **[`plugins\u002Fcommunication_protocols\u002F`](plugins\u002Fcommunication_protocols\u002F)** - Protocol-specific plugins:\n  - [`http\u002F`](plugins\u002Fcommunication_protocols\u002Fhttp\u002F) - HTTP\u002FREST, SSE, streaming, OpenAPI ([README](plugins\u002Fcommunication_protocols\u002Fhttp\u002FREADME.md))\n  - [`cli\u002F`](plugins\u002Fcommunication_protocols\u002Fcli\u002F) - Command-line tools ([README](plugins\u002Fcommunication_protocols\u002Fcli\u002FREADME.md))\n  - [`mcp\u002F`](plugins\u002Fcommunication_protocols\u002Fmcp\u002F) - Model Context Protocol ([README](plugins\u002Fcommunication_protocols\u002Fmcp\u002FREADME.md))\n  - [`text\u002F`](plugins\u002Fcommunication_protocols\u002Ftext\u002F) - File-based tools ([README](plugins\u002Fcommunication_protocols\u002Ftext\u002FREADME.md))\n  - [`socket\u002F`](plugins\u002Fcommunication_protocols\u002Fsocket\u002F) - TCP\u002FUDP (🚧 In Progress)\n  - [`gql\u002F`](plugins\u002Fcommunication_protocols\u002Fgql\u002F) - GraphQL (🚧 In Progress)\n\n## Architecture Overview\n\nUTCP uses a modular architecture with a core library and protocol plugins:\n\n### Core Package (`utcp`)\n\nThe [`core\u002F`](core\u002F) directory contains the foundational components:\n- **Data Models**: Pydantic models for `Tool`, `CallTemplate`, `UtcpManual`, and `Auth`\n- **Client Interface**: Main `UtcpClient` for tool interaction\n- **Plugin System**: Extensible interfaces for protocols, repositories, and search\n- **Default Implementations**: Built-in tool storage and search strategies\n\n## Quick Start\n\n### Installation\n\nInstall the core library and any required protocol plugins:\n\n```bash\n# Install core + HTTP plugin (most common)\npip install utcp utcp-http\n\n# Install additional plugins as needed\npip install utcp-cli utcp-mcp utcp-text\n```\n\n### Basic Usage\n\n```python\nfrom utcp.utcp_client import UtcpClient\n\n# Create client with HTTP API\nclient = await UtcpClient.create(config={\n    \"manual_call_templates\": [{\n        \"name\": \"my_api\",\n        \"call_template_type\": \"http\",\n        \"url\": \"https:\u002F\u002Fapi.example.com\u002Futcp\"\n    }]\n})\n\n# Call a tool\nresult = await client.call_tool(\"my_api.get_data\", {\"id\": \"123\"})\n```\n\n## Protocol Plugins\n\nUTCP supports multiple communication protocols through dedicated plugins:\n\n| Plugin | Description | Status | Documentation |\n|--------|-------------|--------|---------------|\n| [`utcp-http`](plugins\u002Fcommunication_protocols\u002Fhttp\u002F) | HTTP\u002FREST APIs, SSE, streaming | ✅ Stable | [HTTP Plugin README](plugins\u002Fcommunication_protocols\u002Fhttp\u002FREADME.md) |\n| [`utcp-cli`](plugins\u002Fcommunication_protocols\u002Fcli\u002F) | Command-line tools | ✅ Stable | [CLI Plugin README](plugins\u002Fcommunication_protocols\u002Fcli\u002FREADME.md) |\n| [`utcp-mcp`](plugins\u002Fcommunication_protocols\u002Fmcp\u002F) | Model Context Protocol | ✅ Stable | [MCP Plugin README](plugins\u002Fcommunication_protocols\u002Fmcp\u002FREADME.md) |\n| [`utcp-text`](plugins\u002Fcommunication_protocols\u002Ftext\u002F) | Local file-based tools | ✅ Stable | [Text Plugin README](plugins\u002Fcommunication_protocols\u002Ftext\u002FREADME.md) |\n| [`utcp-websocket`](plugins\u002Fcommunication_protocols\u002Fwebsocket\u002F) | WebSocket real-time bidirectional communication | ✅ Stable | [WebSocket Plugin README](plugins\u002Fcommunication_protocols\u002Fwebsocket\u002FREADME.md) |\n| [`utcp-socket`](plugins\u002Fcommunication_protocols\u002Fsocket\u002F) | TCP\u002FUDP protocols | 🚧 In Progress | [Socket Plugin README](plugins\u002Fcommunication_protocols\u002Fsocket\u002FREADME.md) |\n| [`utcp-gql`](plugins\u002Fcommunication_protocols\u002Fgql\u002F) | GraphQL APIs | 🚧 In Progress | [GraphQL Plugin README](plugins\u002Fcommunication_protocols\u002Fgql\u002FREADME.md) |\n\nFor development, you can install the packages in editable mode from the cloned repository:\n\n```bash\n# Clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp.git\ncd python-utcp\n\n# Install the core package in editable mode with dev dependencies\npip install -e \"core[dev]\"\n\n# Install a specific protocol plugin in editable mode\npip install -e plugins\u002Fcommunication_protocols\u002Fhttp\n```\n\n## Migration Guide from 0.x to 1.0.0\n\nVersion 1.0.0 introduces several breaking changes. Follow these steps to migrate your project.\n\n1.  **Update Dependencies**: Install the new `utcp` core package and the specific protocol plugins you use (e.g., `utcp-http`, `utcp-cli`).\n2.  **Configuration**:\n    *   **Configuration Object**: `UtcpClient` is initialized with a `UtcpClientConfig` object, dict or a path to a JSON file containing the configuration.\n    *   **Manual Call Templates**: The `providers_file_path` option is removed. Instead of a file path, you now provide a list of `manual_call_templates` directly within the `UtcpClientConfig`.\n    *   **Terminology**: The term `provider` has been replaced with `call_template`, and `provider_type` is now `call_template_type`.\n    *   **Streamable HTTP**: The `call_template_type` `http_stream` has been renamed to `streamable_http`.\n3.  **Update Imports**: Change your imports to reflect the new modular structure. For example, `from utcp.client.transport_interfaces.http_transport import HttpProvider` becomes `from utcp_http.http_call_template import HttpCallTemplate`.\n4.  **Tool Search**: If you were using the default search, the new strategy is `TagAndDescriptionWordMatchStrategy`. This is the new default and requires no changes unless you were implementing a custom strategy.\n5.  **Tool Naming**: Tool names are now namespaced as `manual_name.tool_name`. The client handles this automatically.\n6.  **Variable Substitution Namespacing**: Variables that are substituted in different `call_templates`, are first namespaced with the name of the manual with the `_` duplicated. So a key in a tool call template called `API_KEY` from the manual `manual_1` would be converted to `manual__1_API_KEY`.\n\n## Usage Examples\n\n### 1. Using the UTCP Client\n\n**`config.json`** (Optional)\n\nYou can define a comprehensive client configuration in a JSON file. All of these fields are optional.\n\n```json\n{\n  \"variables\": {\n    \"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"\n  },\n  \"load_variables_from\": [\n    {\n      \"variable_loader_type\": \"dotenv\",\n      \"env_file_path\": \".env\"\n    }\n  ],\n  \"tool_repository\": {\n    \"tool_repository_type\": \"in_memory\"\n  },\n  \"tool_search_strategy\": {\n    \"tool_search_strategy_type\": \"tag_and_description_word_match\"\n  },\n  \"manual_call_templates\": [\n    {\n        \"name\": \"openlibrary\",\n        \"call_template_type\": \"http\",\n        \"http_method\": \"GET\",\n        \"url\": \"${URL}\",\n        \"content_type\": \"application\u002Fjson\"\n    },\n  ],\n  \"post_processing\": [\n    {\n        \"tool_post_processor_type\": \"filter_dict\",\n        \"only_include_keys\": [\"name\", \"key\"],\n        \"only_include_tools\": [\"openlibrary.read_search_authors_json_search_authors_json_get\"]\n    }\n  ]\n}\n```\n\n**`client.py`**\n\n```python\nimport asyncio\nfrom utcp.utcp_client import UtcpClient\nfrom utcp.data.utcp_client_config import UtcpClientConfig\n\nasync def main():\n    # The UtcpClient can be created with a config file path, a dict, or a UtcpClientConfig object.\n\n    # Option 1: Initialize from a config file path\n    # client_from_file = await UtcpClient.create(config=\".\u002Fconfig.json\")\n\n    # Option 2: Initialize from a dictionary\n    client_from_dict = await UtcpClient.create(config={\n        \"variables\": {\n            \"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"\n        },\n        \"load_variables_from\": [\n            {\n                \"variable_loader_type\": \"dotenv\",\n                \"env_file_path\": \".env\"\n            }\n        ],\n        \"tool_repository\": {\n            \"tool_repository_type\": \"in_memory\"\n        },\n        \"tool_search_strategy\": {\n            \"tool_search_strategy_type\": \"tag_and_description_word_match\"\n        },\n        \"manual_call_templates\": [\n            {\n                \"name\": \"openlibrary\",\n                \"call_template_type\": \"http\",\n                \"http_method\": \"GET\",\n                \"url\": \"${URL}\",\n                \"content_type\": \"application\u002Fjson\"\n            }\n        ],\n        \"post_processing\": [\n            {\n                \"tool_post_processor_type\": \"filter_dict\",\n                \"only_include_keys\": [\"name\", \"key\"],\n                \"only_include_tools\": [\"openlibrary.read_search_authors_json_search_authors_json_get\"]\n            }\n        ]\n    })\n\n    # Option 3: Initialize with a full-featured UtcpClientConfig object\n    from utcp_http.http_call_template import HttpCallTemplate\n    from utcp.data.variable_loader import VariableLoaderSerializer\n    from utcp.interfaces.tool_post_processor import ToolPostProcessorConfigSerializer\n\n    config_obj = UtcpClientConfig(\n        variables={\"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"},\n        load_variables_from=[\n            VariableLoaderSerializer().validate_dict({\n                \"variable_loader_type\": \"dotenv\", \"env_file_path\": \".env\"\n            })\n        ],\n        manual_call_templates=[\n            HttpCallTemplate(\n                name=\"openlibrary\",\n                call_template_type=\"http\",\n                http_method=\"GET\",\n                url=\"${URL}\",\n                content_type=\"application\u002Fjson\"\n            )\n        ],\n        post_processing=[\n            ToolPostProcessorConfigSerializer().validate_dict({\n                \"tool_post_processor_type\": \"filter_dict\",\n                \"only_include_keys\": [\"name\", \"key\"],\n                \"only_include_tools\": [\"openlibrary.read_search_authors_json_search_authors_json_get\"]\n            })\n        ]\n    )\n    client = await UtcpClient.create(config=config_obj)\n\n    # Call a tool. The name is namespaced: `manual_name.tool_name`\n    result = await client.call_tool(\n        tool_name=\"openlibrary.read_search_authors_json_search_authors_json_get\",\n        tool_args={\"q\": \"J. K. Rowling\"}\n    )\n\n    print(result)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 2. Providing a UTCP Manual\n\nA `UTCPManual` describes the tools you offer. The key change is replacing `tool_provider` with `tool_call_template`.\n\n**`server.py`**\n\nUTCP decorator version:\n\n```python\nfrom fastapi import FastAPI\nfrom utcp_http.http_call_template import HttpCallTemplate\nfrom utcp.data.utcp_manual import UtcpManual\nfrom utcp.python_specific_tooling.tool_decorator import utcp_tool\n\napp = FastAPI()\n\n# The discovery endpoint returns the tool manual\n@app.get(\"\u002Futcp\")\ndef utcp_discovery():\n    return UtcpManual.create_from_decorators(manual_version=\"1.0.0\")\n\n# The actual tool endpoint\n@utcp_tool(tool_call_template=HttpCallTemplate(\n    name=\"get_weather\",\n    url=f\"https:\u002F\u002Fexample.com\u002Fapi\u002Fweather\",\n    http_method=\"GET\"\n), tags=[\"weather\"])\n@app.get(\"\u002Fapi\u002Fweather\")\ndef get_weather(location: str):\n    return {\"temperature\": 22.5, \"conditions\": \"Sunny\"}\n```\n\n\nNo UTCP dependencies server version:\n\n```python\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n# The discovery endpoint returns the tool manual\n@app.get(\"\u002Futcp\")\ndef utcp_discovery():\n    return {\n        \"manual_version\": \"1.0.0\",\n        \"utcp_version\": \"1.0.2\",\n        \"tools\": [\n            {\n                \"name\": \"get_weather\",\n                \"description\": \"Get current weather for a location\",\n                \"tags\": [\"weather\"],\n                \"inputs\": {\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"location\": {\"type\": \"string\"}\n                    }\n                },\n                \"outputs\": {\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"temperature\": {\"type\": \"number\"},\n                        \"conditions\": {\"type\": \"string\"}\n                    }\n                },\n                \"tool_call_template\": {\n                    \"call_template_type\": \"http\",\n                    \"url\": \"https:\u002F\u002Fexample.com\u002Fapi\u002Fweather\",\n                    \"http_method\": \"GET\"\n                }\n            }\n        ]\n    }\n\n# The actual tool endpoint\n@app.get(\"\u002Fapi\u002Fweather\")\ndef get_weather(location: str):\n    return {\"temperature\": 22.5, \"conditions\": \"Sunny\"}\n```\n\n### 3. Full examples\n\nYou can find full examples in the [examples repository](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Futcp-examples).\n\n## Protocol Specification\n\n### `UtcpManual` and `Tool` Models\n\nThe `tool_provider` object inside a `Tool` has been replaced by `tool_call_template`.\n\n```json\n{\n  \"manual_version\": \"string\",\n  \"utcp_version\": \"string\",\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"description\": \"string\",\n      \"inputs\": { ... },\n      \"outputs\": { ... },\n      \"tags\": [\"string\"],\n      \"tool_call_template\": {\n        \"call_template_type\": \"http\",\n        \"url\": \"https:\u002F\u002F...\",\n        \"http_method\": \"GET\"\n      }\n    }\n  ]\n}\n```\n\n## Call Template Configuration Examples\n\nConfiguration examples for each protocol. Remember to replace `provider_type` with `call_template_type`.\n\n### HTTP Call Template\n\n```json\n{\n  \"name\": \"my_rest_api\",\n  \"call_template_type\": \"http\", \u002F\u002F Required\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fusers\u002F{user_id}\", \u002F\u002F Required\n  \"http_method\": \"POST\", \u002F\u002F Required, default: \"GET\"\n  \"content_type\": \"application\u002Fjson\", \u002F\u002F Optional, default: \"application\u002Fjson\"\n  \"allowed_communication_protocols\": [\"http\"], \u002F\u002F Optional, defaults to [call_template_type]. Restricts which protocols tools can use.\n  \"auth\": { \u002F\u002F Optional, authentication for the HTTP request (example using ApiKeyAuth for Bearer token)\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer $API_KEY\", \u002F\u002F Required\n    \"var_name\": \"Authorization\", \u002F\u002F Optional, default: \"X-Api-Key\"\n    \"location\": \"header\" \u002F\u002F Optional, default: \"header\"\n  },\n  \"auth_tools\": { \u002F\u002F Optional, authentication for converted tools, if this call template points to an openapi spec that should be automatically converted to a utcp manual (applied only to endpoints requiring auth per OpenAPI spec)\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer $TOOL_API_KEY\", \u002F\u002F Required\n    \"var_name\": \"Authorization\", \u002F\u002F Optional, default: \"X-Api-Key\"\n    \"location\": \"header\" \u002F\u002F Optional, default: \"header\"\n  },\n  \"headers\": { \u002F\u002F Optional\n    \"X-Custom-Header\": \"value\"\n  },\n  \"body_field\": \"body\", \u002F\u002F Optional, default: \"body\"\n  \"header_fields\": [\"user_id\"] \u002F\u002F Optional\n}\n```\n\n### SSE (Server-Sent Events) Call Template\n\n```json\n{\n  \"name\": \"my_sse_stream\",\n  \"call_template_type\": \"sse\", \u002F\u002F Required\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fevents\", \u002F\u002F Required\n  \"event_type\": \"message\", \u002F\u002F Optional\n  \"reconnect\": true, \u002F\u002F Optional, default: true\n  \"retry_timeout\": 30000, \u002F\u002F Optional, default: 30000 (ms)\n  \"auth\": { \u002F\u002F Optional, example using BasicAuth\n    \"auth_type\": \"basic\",\n    \"username\": \"${USERNAME}\", \u002F\u002F Required\n    \"password\": \"${PASSWORD}\" \u002F\u002F Required\n  },\n  \"headers\": { \u002F\u002F Optional\n    \"X-Client-ID\": \"12345\"\n  },\n  \"body_field\": null, \u002F\u002F Optional\n  \"header_fields\": [] \u002F\u002F Optional\n}\n```\n\n### Streamable HTTP Call Template\n\nNote the name change from `http_stream` to `streamable_http`.\n\n```json\n{\n  \"name\": \"streaming_data_source\",\n  \"call_template_type\": \"streamable_http\", \u002F\u002F Required\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fstream\", \u002F\u002F Required\n  \"http_method\": \"POST\", \u002F\u002F Optional, default: \"GET\"\n  \"content_type\": \"application\u002Foctet-stream\", \u002F\u002F Optional, default: \"application\u002Foctet-stream\"\n  \"chunk_size\": 4096, \u002F\u002F Optional, default: 4096\n  \"timeout\": 60000, \u002F\u002F Optional, default: 60000 (ms)\n  \"auth\": null, \u002F\u002F Optional\n  \"headers\": {}, \u002F\u002F Optional\n  \"body_field\": \"data\", \u002F\u002F Optional\n  \"header_fields\": [] \u002F\u002F Optional\n}\n```\n\n### CLI Call Template\n\n```json\n{\n  \"name\": \"multi_step_cli_tool\",\n  \"call_template_type\": \"cli\", \u002F\u002F Required\n  \"commands\": [ \u002F\u002F Required - sequential command execution\n    {\n      \"command\": \"git clone UTCP_ARG_repo_url_UTCP_END temp_repo\",\n      \"append_to_final_output\": false\n    },\n    {\n      \"command\": \"cd temp_repo && find . -name '*.py' | wc -l\"\n      \u002F\u002F Last command output returned by default\n    }\n  ],\n  \"env_vars\": { \u002F\u002F Optional\n    \"GIT_AUTHOR_NAME\": \"UTCP Bot\",\n    \"API_KEY\": \"${MY_API_KEY}\"\n  },\n  \"working_dir\": \"\u002Ftmp\", \u002F\u002F Optional\n  \"auth\": null \u002F\u002F Optional (always null for CLI)\n}\n```\n\n**CLI Protocol Features:**\n- **Multi-command execution**: Commands run sequentially in single subprocess\n- **Cross-platform**: PowerShell on Windows, Bash on Unix\u002FLinux\u002FmacOS  \n- **State preservation**: Directory changes (`cd`) persist between commands\n- **Argument placeholders**: `UTCP_ARG_argname_UTCP_END` format\n- **Output referencing**: Access previous outputs with `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`\n- **Flexible output control**: Choose which command outputs to include in final result\n\n### Text Call Template\n\n```json\n{\n  \"name\": \"my_text_manual\",\n  \"call_template_type\": \"text\", \u002F\u002F Required\n  \"file_path\": \".\u002Fmanuals\u002Fmy_manual.json\", \u002F\u002F Required\n  \"auth\": null, \u002F\u002F Optional (always null for Text)\n  \"auth_tools\": { \u002F\u002F Optional, authentication for generated tools from OpenAPI specs\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer ${API_TOKEN}\",\n    \"var_name\": \"Authorization\",\n    \"location\": \"header\"\n  }\n}\n```\n\n### MCP (Model Context Protocol) Call Template\n\n```json\n{\n  \"name\": \"my_mcp_server\",\n  \"call_template_type\": \"mcp\", \u002F\u002F Required\n  \"config\": { \u002F\u002F Required\n    \"mcpServers\": {\n      \"server_name\": {\n        \"transport\": \"stdio\",\n        \"command\": [\"python\", \"-m\", \"my_mcp_server\"]\n      }\n    }\n  },\n  \"auth\": { \u002F\u002F Optional, example using OAuth2\n    \"auth_type\": \"oauth2\",\n    \"token_url\": \"https:\u002F\u002Fauth.example.com\u002Ftoken\", \u002F\u002F Required\n    \"client_id\": \"${CLIENT_ID}\", \u002F\u002F Required\n    \"client_secret\": \"${CLIENT_SECRET}\", \u002F\u002F Required\n    \"scope\": \"read:tools\" \u002F\u002F Optional\n  }\n}\n```\n\n## Security: Protocol Restrictions\n\nUTCP provides fine-grained control over which communication protocols each manual can use through the `allowed_communication_protocols` field. This prevents potentially dangerous protocol escalation (e.g., an HTTP-based manual accidentally calling CLI tools).\n\n### Default Behavior (Secure by Default)\n\nWhen `allowed_communication_protocols` is not set or is empty, a manual can only register and call tools that use the **same protocol type** as the manual itself:\n\n```python\nfrom utcp_http.http_call_template import HttpCallTemplate\n\n# This manual can ONLY register\u002Fcall HTTP tools (default restriction)\nhttp_manual = HttpCallTemplate(\n    name=\"my_api\",\n    call_template_type=\"http\",\n    url=\"https:\u002F\u002Fapi.example.com\u002Futcp\"\n    # allowed_communication_protocols not set → defaults to [\"http\"]\n)\n```\n\n### Allowing Multiple Protocols\n\nTo allow a manual to work with tools from multiple protocols, explicitly set `allowed_communication_protocols`:\n\n```python\nfrom utcp_http.http_call_template import HttpCallTemplate\n\n# This manual can register\u002Fcall both HTTP and CLI tools\nmulti_protocol_manual = HttpCallTemplate(\n    name=\"flexible_manual\",\n    call_template_type=\"http\",\n    url=\"https:\u002F\u002Fapi.example.com\u002Futcp\",\n    allowed_communication_protocols=[\"http\", \"cli\"]  # Explicitly allow both\n)\n```\n\n### JSON Configuration\n\n```json\n{\n  \"name\": \"my_api\",\n  \"call_template_type\": \"http\",\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Futcp\",\n  \"allowed_communication_protocols\": [\"http\", \"cli\", \"mcp\"]\n}\n```\n\n### Behavior Summary\n\n| `allowed_communication_protocols` | Manual Type | Allowed Tool Protocols |\n|----------------------------------|-------------|------------------------|\n| Not set \u002F `null` | `\"http\"` | Only `\"http\"` |\n| `[]` (empty) | `\"http\"` | Only `\"http\"` |\n| `[\"http\", \"cli\"]` | `\"http\"` | `\"http\"` and `\"cli\"` |\n| `[\"http\", \"cli\", \"mcp\"]` | `\"cli\"` | `\"http\"`, `\"cli\"`, and `\"mcp\"` |\n\n### Registration Filtering\n\nDuring `register_manual()`, tools that don't match the allowed protocols are automatically filtered out with a warning:\n\n```\nWARNING - Tool 'dangerous_tool' uses communication protocol 'cli' which is not in \nallowed protocols ['http'] for manual 'my_api'. Tool will not be registered.\n```\n\n### Call-Time Validation\n\nEven if a tool somehow exists in the repository, calling it will fail if its protocol is not allowed:\n\n```python\n# Raises ValueError: Tool 'my_api.some_cli_tool' uses communication protocol 'cli' \n# which is not allowed by manual 'my_api'. Allowed protocols: ['http']\nawait client.call_tool(\"my_api.some_cli_tool\", {\"arg\": \"value\"})\n```\n\n## Testing\n\nThe testing structure has been updated to reflect the new core\u002Fplugin split.\n\n### Running Tests\n\nTo run all tests for the core library and all plugins:\n```bash\n# Ensure you have installed all dev dependencies\npython -m pytest\n```\n\nTo run tests for a specific package (e.g., the core library):\n```bash\npython -m pytest core\u002Ftests\u002F\n```\n\nTo run tests for a specific plugin (e.g., HTTP):\n```bash\npython -m pytest plugins\u002Fcommunication_protocols\u002Fhttp\u002Ftests\u002F -v\n```\n\nTo run tests with coverage:\n```bash\npython -m pytest --cov=utcp --cov-report=xml\n```\n\n## Build\n\nThe build process now involves building each package (`core` and `plugins`) separately if needed, though they are published to PyPI independently.\n\n1.  Create and activate a virtual environment.\n2.  Install build dependencies: `pip install build`.\n3.  Navigate to the package directory (e.g., `cd core`).\n4.  Run the build: `python -m build`.\n5.  The distributable files (`.whl` and `.tar.gz`) will be in the `dist\u002F` directory.\n\n## OpenAPI Ingestion - Zero Infrastructure Tool Integration\n\n🚀 **Transform any existing REST API into UTCP tools without server modifications!**\n\nUTCP's OpenAPI ingestion feature automatically converts OpenAPI 2.0\u002F3.0 specifications into UTCP tools, enabling AI agents to interact with existing APIs directly - no wrapper servers, no API changes, no additional infrastructure required.\n\n### Quick Start with OpenAPI\n\n```python\nfrom utcp_http.openapi_converter import OpenApiConverter\nimport aiohttp\n\n# Convert any OpenAPI spec to UTCP tools\nasync def convert_api():\n    async with aiohttp.ClientSession() as session:\n        async with session.get(\"https:\u002F\u002Fapi.github.com\u002Fopenapi.json\") as response:\n            openapi_spec = await response.json()\n    \n    converter = OpenApiConverter(openapi_spec)\n    manual = converter.convert()\n    \n    print(f\"Generated {len(manual.tools)} tools from GitHub API!\")\n    return manual\n\n# Or use UTCP Client configuration for automatic detection\nfrom utcp.utcp_client import UtcpClient\n\nclient = await UtcpClient.create(config={\n    \"manual_call_templates\": [{\n        \"name\": \"github\",\n        \"call_template_type\": \"http\", \n        \"url\": \"https:\u002F\u002Fapi.github.com\u002Fopenapi.json\",\n        \"auth_tools\": {  # Authentication for generated tools requiring auth\n            \"auth_type\": \"api_key\",\n            \"api_key\": \"Bearer ${GITHUB_TOKEN}\",\n            \"var_name\": \"Authorization\",\n            \"location\": \"header\"\n        }\n    }]\n})\n```\n\n### Key Benefits\n\n- ✅ **Zero Infrastructure**: No servers to deploy or maintain\n- ✅ **Direct API Calls**: Native performance, no proxy overhead  \n- ✅ **Automatic Conversion**: OpenAPI schemas → UTCP tools\n- ✅ **Selective Authentication**: Only protected endpoints get auth, public endpoints remain accessible\n- ✅ **Authentication Preserved**: API keys, OAuth2, Basic auth supported\n- ✅ **Multi-format Support**: JSON, YAML, OpenAPI 2.0\u002F3.0\n- ✅ **Batch Processing**: Convert multiple APIs simultaneously\n\n### Multiple Ingestion Methods\n\n1. **Direct Converter**: `OpenApiConverter` class for full control\n2. **Remote URLs**: Fetch and convert specs from any URL\n3. **Client Configuration**: Include specs directly in UTCP config\n4. **Batch Processing**: Process multiple specs programmatically\n5. **File-based**: Convert local JSON\u002FYAML specifications\n\n📖 **[Complete OpenAPI Ingestion Guide](docs\u002Fopenapi-ingestion.md)** - Detailed examples and advanced usage\n\n---\n\n## [Contributors](https:\u002F\u002Fwww.utcp.io\u002Fabout)\n","# 通用工具调用协议 (UTCP)\n\n[![关注组织](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Ffollowers\u002Funiversal-tool-calling-protocol?label=Follow%20Org&logo=github)](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol)\n[![PyPI 下载量](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Funiversal-tool-calling-protocol_python-utcp_readme_00190256c29b.png)](https:\u002F\u002Fpepy.tech\u002Fprojects\u002Futcp)\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Funiversal-tool-calling-protocol\u002Fpython-utcp)](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fblob\u002Fmain\u002FLICENSE)\n[![CDTM S23](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCDTM-S23-0b84f3)](https:\u002F\u002Fcdtm.com\u002F)\n\n## 简介\n\n通用工具调用协议 (UTCP) 是一种安全、可扩展的标准，用于在多种通信协议中定义和交互工具。UTCP 1.0.0 引入了基于插件架构的模块化核心，使其更具扩展性、可测试性，并且更易于打包。\n\n与其他协议相比，UTCP 强调以下几点：\n\n*   **可扩展性**：UTCP 旨在处理大量工具和提供商，同时不降低性能。\n*   **可扩展性**：可插拔的架构使开发者能够轻松添加新的通信协议、工具存储机制和搜索策略，而无需修改核心库。\n*   **互操作性**：随着越来越多的协议插件（包括 HTTP、SSE、CLI 等）的出现，UTCP 可以与几乎任何现有服务或基础设施集成。\n*   **易用性**：该协议基于简单且定义明确的 Pydantic 模型，使得开发者可以轻松实现和使用。\n\n\n![MCP 与 UTCP 对比](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Funiversal-tool-calling-protocol_python-utcp_readme_d966f4184ea9.png)\n\n## 仓库结构\n\n此仓库包含完整的 UTCP Python 实现：\n\n- **[`core\u002F`](core\u002F)** - 核心 `utcp` 包，包含基础组件（[README](core\u002FREADME.md)）\n- **[`plugins\u002Fcommunication_protocols\u002F`](plugins\u002Fcommunication_protocols\u002F)** - 协议特定插件：\n  - [`http\u002F`](plugins\u002Fcommunication_protocols\u002Fhttp\u002F) - HTTP\u002FREST、SSE、流式传输、OpenAPI（[README](plugins\u002Fcommunication_protocols\u002Fhttp\u002FREADME.md)）\n  - [`cli\u002F`](plugins\u002Fcommunication_protocols\u002Fcli\u002F) - 命令行工具（[README](plugins\u002Fcommunication_protocols\u002Fcli\u002FREADME.md)）\n  - [`mcp\u002F`](plugins\u002Fcommunication_protocols\u002Fmcp\u002F) - 模型上下文协议（[README](plugins\u002Fcommunication_protocols\u002Fmcp\u002FREADME.md)）\n  - [`text\u002F`](plugins\u002Fcommunication_protocols\u002Ftext\u002F) - 基于文件的工具（[README](plugins\u002Fcommunication_protocols\u002Ftext\u002FREADME.md)）\n  - [`socket\u002F`](plugins\u002Fcommunication_protocols\u002Fsocket\u002F) - TCP\u002FUDP（🚧 开发中）\n  - [`gql\u002F`](plugins\u002Fcommunication_protocols\u002Fgql\u002F) - GraphQL（🚧 开发中）\n\n## 架构概览\n\nUTCP 采用模块化架构，由核心库和协议插件组成：\n\n### 核心包 (`utcp`)\n\n[`core\u002F`](core\u002F) 目录包含基础组件：\n- **数据模型**：用于 `Tool`、`CallTemplate`、`UtcpManual` 和 `Auth` 的 Pydantic 模型\n- **客户端接口**：用于工具交互的主要 `UtcpClient`\n- **插件系统**：用于协议、仓库和搜索的可扩展接口\n- **默认实现**：内置的工具存储和搜索策略\n\n## 快速入门\n\n### 安装\n\n安装核心库和所需的任何协议插件：\n\n```bash\n# 安装核心 + HTTP 插件（最常用）\npip install utcp utcp-http\n\n# 根据需要安装其他插件\npip install utcp-cli utcp-mcp utcp-text\n```\n\n### 基本用法\n\n```python\nfrom utcp.utcp_client import UtcpClient\n\n# 使用 HTTP API 创建客户端\nclient = await UtcpClient.create(config={\n    \"manual_call_templates\": [{\n        \"name\": \"my_api\",\n        \"call_template_type\": \"http\",\n        \"url\": \"https:\u002F\u002Fapi.example.com\u002Futcp\"\n    }]\n})\n\n# 调用工具\nresult = await client.call_tool(\"my_api.get_data\", {\"id\": \"123\"})\n```\n\n## 协议插件\n\nUTCP 通过专用插件支持多种通信协议：\n\n| 插件 | 描述 | 状态 | 文档 |\n|--------|-------------|--------|---------------|\n| [`utcp-http`](plugins\u002Fcommunication_protocols\u002Fhttp\u002F) | HTTP\u002FREST API、SSE、流式传输 | ✅ 稳定 | [HTTP 插件 README](plugins\u002Fcommunication_protocols\u002Fhttp\u002FREADME.md) |\n| [`utcp-cli`](plugins\u002Fcommunication_protocols\u002Fcli\u002F) | 命令行工具 | ✅ 稳定 | [CLI 插件 README](plugins\u002Fcommunication_protocols\u002Fcli\u002FREADME.md) |\n| [`utcp-mcp`](plugins\u002Fcommunication_protocols\u002Fmcp\u002F) | 模型上下文协议 | ✅ 稳定 | [MCP 插件 README](plugins\u002Fcommunication_protocols\u002Fmcp\u002FREADME.md) |\n| [`utcp-text`](plugins\u002Fcommunication_protocols\u002Ftext\u002F) | 本地基于文件的工具 | ✅ 稳定 | [Text 插件 README](plugins\u002Fcommunication_protocols\u002Ftext\u002FREADME.md) |\n| [`utcp-websocket`](plugins\u002Fcommunication_protocols\u002Fwebsocket\u002F) | WebSocket 实时双向通信 | ✅ 稳定 | [WebSocket 插件 README](plugins\u002Fcommunication_protocols\u002Fwebsocket\u002FREADME.md) |\n| [`utcp-socket`](plugins\u002Fcommunication_protocols\u002Fsocket\u002F) | TCP\u002FUDP 协议 | 🚧 开发中 | [Socket 插件 README](plugins\u002Fcommunication_protocols\u002Fsocket\u002FREADME.md) |\n| [`utcp-gql`](plugins\u002Fcommunication_protocols\u002Fgql\u002F) | GraphQL API | 🚧 开发中 | [GraphQL 插件 README](plugins\u002Fcommunication_protocols\u002Fgql\u002FREADME.md) |\n\n在开发过程中，您可以从克隆的仓库中以可编辑模式安装这些包：\n\n```bash\n# 克隆仓库\ngit clone https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp.git\ncd python-utcp\n\n# 以可编辑模式安装核心包及其开发依赖项\npip install -e \"core[dev]\"\n\n# 以可编辑模式安装特定的协议插件\npip install -e plugins\u002Fcommunication_protocols\u002Fhttp\n```\n\n## 从 0.x 迁移到 1.0.0 的迁移指南\n\n版本 1.0.0 引入了多项破坏性变更。请按照以下步骤迁移您的项目。\n\n1.  **更新依赖**：安装新的 `utcp` 核心包以及您使用的特定协议插件（例如 `utcp-http`、`utcp-cli`）。\n2.  **配置**：\n    *   **配置对象**：`UtcpClient` 现在通过一个 `UtcpClientConfig` 对象、字典或包含配置的 JSON 文件路径来初始化。\n    *   **手动调用模板**：移除了 `providers_file_path` 选项。现在不再使用文件路径，而是直接在 `UtcpClientConfig` 中提供 `manual_call_templates` 列表。\n    *   **术语变化**：`provider` 一词已被替换为 `call_template`，而 `provider_type` 现在称为 `call_template_type`。\n    *   **可流式 HTTP**：`call_template_type` 中的 `http_stream` 已更名为 `streamable_http`。\n3.  **更新导入语句**：更改您的导入语句以反映新的模块化结构。例如，`from utcp.client.transport_interfaces.http_transport import HttpProvider` 将变为 `from utcp_http.http_call_template import HttpCallTemplate`。\n4.  **工具搜索**：如果您之前使用的是默认搜索策略，新的策略是 `TagAndDescriptionWordMatchStrategy`。这是新的默认设置，除非您实现了自定义策略，否则无需进行任何更改。\n5.  **工具命名**：工具名称现在采用命名空间格式，即 `manual_name.tool_name`。客户端会自动处理这一点。\n6.  **变量替换命名空间**：在不同 `call_templates` 中被替换的变量，首先会使用手册名称进行命名空间划分，并将 `_` 重复一次。因此，在名为 `manual_1` 的手册中的工具调用模板里有一个键为 `API_KEY` 的变量，它会被转换为 `manual__1_API_KEY`。\n\n## 使用示例\n\n### 1. 使用 UTCP 客户端\n\n**`config.json`**（可选）\n\n您可以在一个 JSON 文件中定义全面的客户端配置。这些字段都是可选的。\n\n```json\n{\n  \"variables\": {\n    \"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"\n  },\n  \"load_variables_from\": [\n    {\n      \"variable_loader_type\": \"dotenv\",\n      \"env_file_path\": \".env\"\n    }\n  ],\n  \"tool_repository\": {\n    \"tool_repository_type\": \"in_memory\"\n  },\n  \"tool_search_strategy\": {\n    \"tool_search_strategy_type\": \"tag_and_description_word_match\"\n  },\n  \"manual_call_templates\": [\n    {\n        \"name\": \"openlibrary\",\n        \"call_template_type\": \"http\",\n        \"http_method\": \"GET\",\n        \"url\": \"${URL}\",\n        \"content_type\": \"application\u002Fjson\"\n    }\n  ]\n}\n```\n\n**`client.py`**\n\n```python\nimport asyncio\nfrom utcp.utcp_client import UtcpClient\nfrom utcp.data.utcp_client_config import UtcpClientConfig\n\nasync def main():\n    # UtcpClient 可以通过配置文件路径、字典或 UtcpClientConfig 对象来创建。\n\n    # 选项 1：从配置文件路径初始化\n    # client_from_file = await UtcpClient.create(config=\".\u002Fconfig.json\")\n\n    # 选项 2：从字典初始化\n    client_from_dict = await UtcpClient.create(config={\n        \"variables\": {\n            \"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"\n        },\n        \"load_variables_from\": [\n            {\n                \"variable_loader_type\": \"dotenv\",\n                \"env_file_path\": \".env\"\n            }\n        ],\n        \"tool_repository\": {\n            \"tool_repository_type\": \"in_memory\"\n        },\n        \"tool_search_strategy\": {\n            \"tool_search_strategy_type\": \"tag_and_description_word_match\"\n        },\n        \"manual_call_templates\": [\n            {\n                \"name\": \"openlibrary\",\n                \"call_template_type\": \"http\",\n                \"http_method\": \"GET\",\n                \"url\": \"${URL}\",\n                \"content_type\": \"application\u002Fjson\"\n            }\n        ],\n        \"post_processing\": [\n            {\n                \"tool_post_processor_type\": \"filter_dict\",\n                \"only_include_keys\": [\"name\", \"key\"],\n                \"only_include_tools\": [\"openlibrary.read_search_authors_json_search_authors_json_get\"]\n            }\n        ]\n    })\n\n    # 选项 3：使用功能齐全的 UtcpClientConfig 对象初始化\n    from utcp_http.http_call_template import HttpCallTemplate\n    from utcp.data.variable_loader import VariableLoaderSerializer\n    from utcp.interfaces.tool_post_processor import ToolPostProcessorConfigSerializer\n\n    config_obj = UtcpClientConfig(\n        variables={\"openlibrary_URL\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"},\n        load_variables_from=[\n            VariableLoaderSerializer().validate_dict({\n                \"variable_loader_type\": \"dotenv\", \"env_file_path\": \".env\"\n            })\n        ],\n        manual_call_templates=[\n            HttpCallTemplate(\n                name=\"openlibrary\",\n                call_template_type=\"http\",\n                http_method=\"GET\",\n                url=\"${URL}\",\n                content_type=\"application\u002Fjson\"\n            )\n        ],\n        post_processing=[\n            ToolPostProcessorConfigSerializer().validate_dict({\n                \"tool_post_processor_type\": \"filter_dict\",\n                \"only_include_keys\": [\"name\", \"key\"],\n                \"only_include_tools\": [\"openlibrary.read_search_authors_json_search_authors_json_get\"]\n            })\n        ]\n    )\n    client = await UtcpClient.create(config=config_obj)\n\n    # 调用工具。工具名称采用命名空间格式：`manual_name.tool_name`\n    result = await client.call_tool(\n        tool_name=\"openlibrary.read_search_authors_json_search_authors_json_get\",\n        tool_args={\"q\": \"J. K. Rowling\"}\n    )\n\n    print(result)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 2. 提供 UTCP 手册\n\n`UTCPManual` 描述了您提供的工具。关键变化是将 `tool_provider` 替换为 `tool_call_template`。\n\n**`server.py`**\n\n使用 UTCP 装饰器的版本：\n\n```python\nfrom fastapi import FastAPI\nfrom utcp_http.http_call_template import HttpCallTemplate\nfrom utcp.data.utcp_manual import UtcpManual\nfrom utcp.python_specific_tooling.tool_decorator import utcp_tool\n\napp = FastAPI()\n\n# 发现端点返回工具手册\n@app.get(\"\u002Futcp\")\ndef utcp_discovery():\n    return UtcpManual.create_from_decorators(manual_version=\"1.0.0\")\n\n# 实际的工具端点\n@utcp_tool(tool_call_template=HttpCallTemplate(\n    name=\"get_weather\",\n    url=f\"https:\u002F\u002Fexample.com\u002Fapi\u002Fweather\",\n    http_method=\"GET\"\n), tags=[\"weather\"])\n@app.get(\"\u002Fapi\u002Fweather\")\ndef get_weather(location: str):\n    return {\"temperature\": 22.5, \"conditions\": \"Sunny\"}\n```\n\n\n不使用 UTCP 依赖的服务器版本：\n\n```python\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n# 发现端点返回工具手册\n@app.get(\"\u002Futcp\")\ndef utcp_discovery():\n    return {\n        \"manual_version\": \"1.0.0\",\n        \"utcp_version\": \"1.0.2\",\n        \"tools\": [\n            {\n                \"name\": \"get_weather\",\n                \"description\": \"获取某个地点的当前天气\",\n                \"tags\": [\"weather\"],\n                \"inputs\": {\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"location\": {\"type\": \"string\"}\n                    }\n                },\n                \"outputs\": {\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"temperature\": {\"type\": \"number\"},\n                        \"conditions\": {\"type\": \"string\"}\n                    }\n                },\n                \"tool_call_template\": {\n                    \"call_template_type\": \"http\",\n                    \"url\": \"https:\u002F\u002Fexample.com\u002Fapi\u002Fweather\",\n                    \"http_method\": \"GET\"\n                }\n            }\n        ]\n    }\n\n# 实际的工具端点\n@app.get(\"\u002Fapi\u002Fweather\")\ndef get_weather(location: str):\n    return {\"temperature\": 22.5, \"conditions\": \"Sunny\"}\n```\n\n### 3. 完整示例\n\n您可以在 [examples repository](https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Futcp-examples) 中找到完整的示例。\n\n## 协议规范\n\n### `UtcpManual` 和 `Tool` 模型\n\n`Tool` 中的 `tool_provider` 对象已被 `tool_call_template` 替代。\n\n```json\n{\n  \"manual_version\": \"string\",\n  \"utcp_version\": \"string\",\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"description\": \"string\",\n      \"inputs\": { ... },\n      \"outputs\": { ... },\n      \"tags\": [\"string\"],\n      \"tool_call_template\": {\n        \"call_template_type\": \"http\",\n        \"url\": \"https:\u002F\u002F...\",\n        \"http_method\": \"GET\"\n      }\n    }\n  ]\n}\n```\n\n## 调用模板配置示例\n\n针对每种协议的配置示例。请记住将 `provider_type` 替换为 `call_template_type`。\n\n### HTTP 调用模板\n\n```json\n{\n  \"name\": \"my_rest_api\",\n  \"call_template_type\": \"http\", \u002F\u002F 必需\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fusers\u002F{user_id}\", \u002F\u002F 必需\n  \"http_method\": \"POST\", \u002F\u002F 必需，默认值为 \"GET\"\n  \"content_type\": \"application\u002Fjson\", \u002F\u002F 可选，默认值为 \"application\u002Fjson\"\n  \"allowed_communication_protocols\": [\"http\"], \u002F\u002F 可选，默认为 [call_template_type]。限制工具可以使用的通信协议。\n  \"auth\": { \u002F\u002F 可选，用于 HTTP 请求的身份验证（例如使用 ApiKeyAuth 提供 Bearer 令牌）\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer $API_KEY\", \u002F\u002F 必需\n    \"var_name\": \"Authorization\", \u002F\u002F 可选，默认值为 \"X-Api-Key\"\n    \"location\": \"header\" \u002F\u002F 可选，默认值为 \"header\"\n  },\n  \"auth_tools\": { \u002F\u002F 可选，用于转换后的工具的身份验证，如果此调用模板指向一个应自动转换为 utcp 手册的 openapi 规范（仅适用于按 OpenAPI 规范需要身份验证的端点）\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer $TOOL_API_KEY\", \u002F\u002F 必需\n    \"var_name\": \"Authorization\", \u002F\u002F 可选，默认值为 \"X-Api-Key\"\n    \"location\": \"header\" \u002F\u002F 可选，默认值为 \"header\"\n  },\n  \"headers\": { \u002F\u002F 可选\n    \"X-Custom-Header\": \"value\"\n  },\n  \"body_field\": \"body\", \u002F\u002F 可选，默认值为 \"body\"\n  \"header_fields\": [\"user_id\"] \u002F\u002F 可选\n}\n```\n\n### SSE（服务器发送事件）调用模板\n\n```json\n{\n  \"name\": \"my_sse_stream\",\n  \"call_template_type\": \"sse\", \u002F\u002F 必需\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fevents\", \u002F\u002F 必需\n  \"event_type\": \"message\", \u002F\u002F 可选\n  \"reconnect\": true, \u002F\u002F 可选，默认值为 true\n  \"retry_timeout\": 30000, \u002F\u002F 可选，默认值为 30000 毫秒\n  \"auth\": { \u002F\u002F 可选，示例使用 BasicAuth\n    \"auth_type\": \"basic\",\n    \"username\": \"${USERNAME}\", \u002F\u002F 必需\n    \"password\": \"${PASSWORD}\" \u002F\u002F 必需\n  },\n  \"headers\": { \u002F\u002F 可选\n    \"X-Client-ID\": \"12345\"\n  },\n  \"body_field\": null, \u002F\u002F 可选\n  \"header_fields\": [] \u002F\u002F 可选\n}\n```\n\n### 流式 HTTP 调用模板\n\n请注意名称已从 `http_stream` 更改为 `streamable_http`。\n\n```json\n{\n  \"name\": \"streaming_data_source\",\n  \"call_template_type\": \"streamable_http\", \u002F\u002F 必需\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Fstream\", \u002F\u002F 必需\n  \"http_method\": \"POST\", \u002F\u002F 可选，默认值为 \"GET\"\n  \"content_type\": \"application\u002Foctet-stream\", \u002F\u002F 可选，默认值为 \"application\u002Foctet-stream\"\n  \"chunk_size\": 4096, \u002F\u002F 可选，默认值为 4096\n  \"timeout\": 60000, \u002F\u002F 可选，默认值为 60000 毫秒\n  \"auth\": null, \u002F\u002F 可选\n  \"headers\": {}, \u002F\u002F 可选\n  \"body_field\": \"data\", \u002F\u002F 可选\n  \"header_fields\": [] \u002F\u002F 可选\n}\n```\n\n### CLI 调用模板\n\n```json\n{\n  \"name\": \"multi_step_cli_tool\",\n  \"call_template_type\": \"cli\", \u002F\u002F 必需\n  \"commands\": [ \u002F\u002F 必需——按顺序执行命令\n    {\n      \"command\": \"git clone UTCP_ARG_repo_url_UTCP_END temp_repo\",\n      \"append_to_final_output\": false\n    },\n    {\n      \"command\": \"cd temp_repo && find . -name '*.py' | wc -l\"\n      \u002F\u002F 默认返回最后一道命令的输出\n    }\n  ],\n  \"env_vars\": { \u002F\u002F 可选\n    \"GIT_AUTHOR_NAME\": \"UTCP Bot\",\n    \"API_KEY\": \"${MY_API_KEY}\"\n  },\n  \"working_dir\": \"\u002Ftmp\", \u002F\u002F 可选\n  \"auth\": null \u002F\u002F 可选（CLI 始终为 null）\n}\n```\n\n**CLI 协议特性：**\n- **多命令执行**：命令在单个子进程中按顺序运行\n- **跨平台**：Windows 上使用 PowerShell，Unix\u002FLinux\u002FmacOS 上使用 Bash\n- **状态保留**：目录更改（`cd`）在各命令之间保持有效\n- **参数占位符**：`UTCP_ARG_argname_UTCP_END` 格式\n- **输出引用**：可通过 `$CMD_0_OUTPUT`、$`CMD_1_OUTPUT` 访问先前的输出\n- **灵活的输出控制**：可选择将哪些命令的输出包含在最终结果中\n\n### 文本调用模板\n\n```json\n{\n  \"name\": \"my_text_manual\",\n  \"call_template_type\": \"text\", \u002F\u002F 必需\n  \"file_path\": \".\u002Fmanuals\u002Fmy_manual.json\", \u002F\u002F 必需\n  \"auth\": null, \u002F\u002F 可选（文本始终为 null）\n  \"auth_tools\": { \u002F\u002F 可选，用于从 OpenAPI 规范生成的工具的身份验证\n    \"auth_type\": \"api_key\",\n    \"api_key\": \"Bearer ${API_TOKEN}\",\n    \"var_name\": \"Authorization\",\n    \"location\": \"header\"\n  }\n}\n```\n\n### MCP（模型上下文协议）调用模板\n\n```json\n{\n  \"name\": \"my_mcp_server\",\n  \"call_template_type\": \"mcp\", \u002F\u002F 必需\n  \"config\": { \u002F\u002F 必需\n    \"mcpServers\": {\n      \"server_name\": {\n        \"transport\": \"stdio\",\n        \"command\": [\"python\", \"-m\", \"my_mcp_server\"]\n      }\n    }\n  },\n  \"auth\": { \u002F\u002F 可选，示例使用 OAuth2\n    \"auth_type\": \"oauth2\",\n    \"token_url\": \"https:\u002F\u002Fauth.example.com\u002Ftoken\", \u002F\u002F 必需\n    \"client_id\": \"${CLIENT_ID}\", \u002F\u002F 必需\n    \"client_secret\": \"${CLIENT_SECRET}\", \u002F\u002F 必需\n    \"scope\": \"read:tools\" \u002F\u002F 可选\n  }\n}\n```\n\n## 安全性：协议限制\n\nUTCP 通过 `allowed_communication_protocols` 字段，对每个手册可使用的通信协议提供细粒度控制。这可以防止潜在的危险协议升级（例如，基于 HTTP 的手册意外调用 CLI 工具）。\n\n### 默认行为（默认安全）\n\n当 `allowed_communication_protocols` 未设置或为空时，手册只能注册和调用与手册本身使用 **相同协议类型** 的工具：\n\n```python\nfrom utcp_http.http_call_template import HttpCallTemplate\n\n# 此手册仅能注册\u002F调用 HTTP 工具（默认限制）\nhttp_manual = HttpCallTemplate(\n    name=\"my_api\",\n    call_template_type=\"http\",\n    url=\"https:\u002F\u002Fapi.example.com\u002Futcp\"\n    # allowed_communication_protocols 未设置 → 默认为 [\"http\"]\n)\n```\n\n### 允许多种协议\n\n若要允许手册使用来自多种协议的工具，请显式设置 `allowed_communication_protocols`：\n\n```python\nfrom utcp_http.http_call_template import HttpCallTemplate\n\n# 此手册可以注册\u002F调用 HTTP 和 CLI 工具\nmulti_protocol_manual = HttpCallTemplate(\n    name=\"flexible_manual\",\n    call_template_type=\"http\",\n    url=\"https:\u002F\u002Fapi.example.com\u002Futcp\",\n    allowed_communication_protocols=[\"http\", \"cli\"]  # 显式允许两种协议\n)\n```\n\n### JSON 配置\n\n```json\n{\n  \"name\": \"my_api\",\n  \"call_template_type\": \"http\",\n  \"url\": \"https:\u002F\u002Fapi.example.com\u002Futcp\",\n  \"allowed_communication_protocols\": [\"http\", \"cli\", \"mcp\"]\n}\n```\n\n### 行为总结\n\n| `allowed_communication_protocols` | 手册类型 | 允许的工具协议 |\n|----------------------------------|-------------|------------------------|\n| 未设置 \u002F `null` | `\"http\"` | 仅 `\"http\"` |\n| `[]`（空） | `\"http\"` | 仅 `\"http\"` |\n| `[\"http\", \"cli\"]` | `\"http\"` | `\"http\"` 和 `\"cli\"` |\n| `[\"http\", \"cli\", \"mcp\"]` | `\"cli\"` | `\"http\"`、`\"cli\"` 和 `\"mcp\"` |\n\n### 注册时的过滤\n\n在 `register_manual()` 过程中，不符合允许协议的工具会被自动过滤掉，并发出警告：\n\n```\nWARNING - 工具 'dangerous_tool' 使用通信协议 'cli'，该协议不在手册 'my_api' 的允许协议 ['http'] 中。该工具将不会被注册。\n```\n\n### 调用时的验证\n\n即使工具以某种方式存在于仓库中，如果其协议未被允许，调用也会失败：\n\n```python\n# 抛出 ValueError：工具 'my_api.some_cli_tool' 使用通信协议 'cli'，而该协议不被手册 'my_api' 允许。允许的协议：['http']\nawait client.call_tool(\"my_api.some_cli_tool\", {\"arg\": \"value\"})\n```\n\n## 测试\n\n测试结构已更新，以反映新的核心与插件分离。\n\n### 运行测试\n\n要运行核心库和所有插件的所有测试：\n```bash\n# 确保已安装所有开发依赖项\npython -m pytest\n```\n\n要运行特定包的测试（例如，核心库）：\n```bash\npython -m pytest core\u002Ftests\u002F\n```\n\n要运行特定插件的测试（例如，HTTP）：\n```bash\npython -m pytest plugins\u002Fcommunication_protocols\u002Fhttp\u002Ftests\u002F -v\n```\n\n要运行带有覆盖率的测试：\n```bash\npython -m pytest --cov=utcp --cov-report=xml\n```\n\n## 构建\n\n构建过程现在涉及单独构建每个包（`core` 和 `plugins`），尽管它们是独立发布到 PyPI 的。\n\n1. 创建并激活虚拟环境。\n2. 安装构建依赖项：`pip install build`。\n3. 导航到包目录（例如，`cd core`）。\n4. 运行构建：`python -m build`。\n5. 可分发文件（`.whl` 和 `.tar.gz`）将位于 `dist\u002F` 目录中。\n\n## OpenAPI 摄取——零基础设施工具集成\n\n🚀 **无需修改服务器即可将任何现有 REST API 转换为 UTCP 工具！**\n\nUTCP 的 OpenAPI 摄取功能会自动将 OpenAPI 2.0\u002F3.0 规范转换为 UTCP 工具，使 AI 代理能够直接与现有 API 交互——无需包装服务器、无需更改 API、无需额外基础设施。\n\n### 使用 OpenAPI 快速入门\n\n```python\nfrom utcp_http.openapi_converter import OpenApiConverter\nimport aiohttp\n\n# 将任意 OpenAPI 规范转换为 UTCP 工具\nasync def convert_api():\n    async with aiohttp.ClientSession() as session:\n        async with session.get(\"https:\u002F\u002Fapi.github.com\u002Fopenapi.json\") as response:\n            openapi_spec = await response.json()\n    \n    converter = OpenApiConverter(openapi_spec)\n    manual = converter.convert()\n    \n    print(f\"从 GitHub API 生成了 {len(manual.tools)} 个工具！\")\n    return manual\n\n# 或使用 UTCP 客户端配置进行自动检测\nfrom utcp.utcp_client import UtcpClient\n\nclient = await UtcpClient.create(config={\n    \"manual_call_templates\": [{\n        \"name\": \"github\",\n        \"call_template_type\": \"http\", \n        \"url\": \"https:\u002F\u002Fapi.github.com\u002Fopenapi.json\",\n        \"auth_tools\": {  # 为需要认证的生成工具添加认证\n            \"auth_type\": \"api_key\",\n            \"api_key\": \"Bearer ${GITHUB_TOKEN}\",\n            \"var_name\": \"Authorization\",\n            \"location\": \"header\"\n        }\n    }]\n})\n```\n\n### 主要优势\n\n- ✅ **零基础设施**：无需部署或维护服务器\n- ✅ **直接 API 调用**：原生性能，无代理开销\n- ✅ **自动转换**：OpenAPI 模式 → UTCP 工具\n- ✅ **选择性认证**：仅受保护的端点需要认证，公开端点仍可访问\n- ✅ **保留认证信息**：支持 API 密钥、OAuth2、Basic 认证\n- ✅ **多格式支持**：JSON、YAML、OpenAPI 2.0\u002F3.0\n- ✅ **批量处理**：可同时转换多个 API\n\n### 多种摄取方法\n\n1. **直接转换器**：`OpenApiConverter` 类，提供完全控制\n2. **远程 URL**：从任意 URL 获取并转换规范\n3. **客户端配置**：直接在 UTCP 配置中包含规范\n4. **批量处理**：以编程方式处理多个规范\n5. **基于文件**：转换本地 JSON\u002FYAML 规范\n\n📖 **[完整的 OpenAPI 摄取指南](docs\u002Fopenapi-ingestion.md)** —— 详细示例和高级用法\n\n---\n\n## [贡献者](https:\u002F\u002Fwww.utcp.io\u002Fabout)","# python-utcp 快速上手指南\n\nUniversal Tool Calling Protocol (UTCP) 是一个安全、可扩展的标准，用于定义和交互各种通信协议下的工具。它采用模块化核心与插件化架构，强调高扩展性、互操作性及易用性。\n\n## 环境准备\n\n*   **系统要求**：支持 Python 3.8+ 的操作系统（Linux, macOS, Windows）。\n*   **前置依赖**：\n    *   Python 3.8 或更高版本。\n    *   `pip` 包管理工具。\n    *   （可选）`git`，用于克隆源码进行开发。\n\n## 安装步骤\n\nUTCP 采用核心库与协议插件分离的设计。请根据需求安装核心库及对应的协议插件。\n\n### 1. 通过 PyPI 安装（推荐）\n\n安装核心库及最常用的 HTTP 插件：\n\n```bash\npip install utcp utcp-http\n```\n\n如需其他协议支持，可按需安装：\n\n```bash\n# 命令行工具插件\npip install utcp-cli\n\n# Model Context Protocol 插件\npip install utcp-mcp\n\n# 本地文件工具插件\npip install utcp-text\n\n# WebSocket 插件\npip install utcp-websocket\n```\n\n> **国内加速建议**：如遇网络问题，可使用清华或阿里云镜像源：\n> ```bash\n> pip install utcp utcp-http -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> ```\n\n### 2. 开发模式安装（可选）\n\n如需修改源码或贡献代码，可克隆仓库并以可编辑模式安装：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp.git\ncd python-utcp\n\n# 安装核心库（含开发依赖）\npip install -e \"core[dev]\"\n\n# 安装特定插件（例如 HTTP）\npip install -e plugins\u002Fcommunication_protocols\u002Fhttp\n```\n\n## 基本使用\n\n以下示例展示如何通过 Python 代码初始化客户端并调用一个远程 HTTP 工具。\n\n### 1. 最小化代码示例\n\n```python\nimport asyncio\nfrom utcp.utcp_client import UtcpClient\n\nasync def main():\n    # 创建客户端，配置手动调用模板\n    client = await UtcpClient.create(config={\n        \"manual_call_templates\": [{\n            \"name\": \"my_api\",\n            \"call_template_type\": \"http\",\n            \"url\": \"https:\u002F\u002Fapi.example.com\u002Futcp\"\n        }]\n    })\n\n    # 调用工具\n    # 注意：工具名称格式为 \"manual_name.tool_name\"\n    result = await client.call_tool(\"my_api.get_data\", {\"id\": \"123\"})\n    \n    print(result)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 2. 使用配置文件初始化\n\n对于复杂场景，可以使用 JSON 文件或字典配置变量、存储策略和后处理逻辑。\n\n**config.json**\n```json\n{\n  \"variables\": {\n    \"base_url\": \"https:\u002F\u002Fopenlibrary.org\u002Fstatic\u002Fopenapi.json\"\n  },\n  \"manual_call_templates\": [\n    {\n      \"name\": \"openlibrary\",\n      \"call_template_type\": \"http\",\n      \"http_method\": \"GET\",\n      \"url\": \"${base_url}\",\n      \"content_type\": \"application\u002Fjson\"\n    }\n  ]\n}\n```\n\n**client.py**\n```python\nimport asyncio\nfrom utcp.utcp_client import UtcpClient\n\nasync def main():\n    # 从配置文件路径初始化\n    client = await UtcpClient.create(config=\".\u002Fconfig.json\")\n\n    # 调用工具\n    result = await client.call_tool(\n        tool_name=\"openlibrary.search\", \n        tool_args={\"q\": \"J. K. Rowling\"}\n    )\n    print(result)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 关键特性提示\n*   **命名空间**：工具调用时名称需遵循 `manual_name.tool_name` 格式（如 `my_api.get_data`），客户端会自动处理。\n*   **变量替换**：在配置中使用 `${variable_name}` 语法引用变量，支持从 `.env` 文件加载。\n*   **插件扩展**：更换 `call_template_type` 即可切换到底层不同的通信协议（如 `cli`, `mcp`, `text` 等），无需修改核心逻辑。","某电商公司的后端团队正致力于构建一个智能运维助手，需要让 AI 代理同时调用内部遗留的 CLI 脚本、新的 HTTP 微服务以及第三方 GraphQL 接口来自动处理订单异常。\n\n### 没有 python-utcp 时\n- **中间件冗余**：为了统一不同协议的调用方式，团队不得不开发和维护一套沉重的自定义网关作为中间层，导致架构复杂且延迟增加。\n- **扩展困难**：每当接入新类型的工具（如从 HTTP 切换到 WebSocket），都需要修改核心代码逻辑，无法实现真正的插件化热插拔。\n- **协议孤岛**：CLI 命令、REST API 和 GraphQL 查询各自为政，AI 代理难以理解统一的工具描述格式，导致意图识别准确率低下。\n- **维护成本高**：缺乏标准化的数据模型，每次更新接口文档都需要同步修改多处适配代码，测试工作量巨大。\n\n### 使用 python-utcp 后\n- **直连任意 API**：python-utcp 允许 AI 代理通过标准协议直接调用各类接口，彻底移除了多余的中间件，显著降低了系统延迟。\n- **插件化极速扩展**：借助其模块化架构，团队只需安装 `utcp-cli` 或 `utcp-gql` 等插件即可无缝支持新协议，无需触碰核心逻辑。\n- **统一交互标准**：所有工具被抽象为一致的 Pydantic 模型，AI 代理能以统一视角理解和调度跨协议工具，大幅提升了执行成功率。\n- **开发效率飞跃**：基于清晰的接口定义和内置搜索策略，开发人员能快速封装现有基础设施，将新工具接入时间从数天缩短至小时级。\n\npython-utcp 通过建立通用的工具调用标准，打破了协议壁垒，让 AI 代理能像人类一样灵活、直接地操控任何异构系统。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Funiversal-tool-calling-protocol_python-utcp_fd6249c2.png","universal-tool-calling-protocol","Universal Tool Calling Protocol","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Funiversal-tool-calling-protocol_bcc4d40a.png","",null,"utcp.io","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol",[83],{"name":84,"color":85,"percentage":86},"Python","#3572A5",100,640,43,"2026-03-28T17:46:48","MPL-2.0",1,"Linux, macOS, Windows","未说明",{"notes":95,"python":96,"dependencies":97},"该工具为纯 Python 协议库，无 GPU 或大内存需求。核心包与通信协议插件（如 HTTP, CLI, MCP 等）需分开安装。支持通过 JSON 配置文件、字典或配置对象初始化客户端。变量替换支持从 .env 文件加载。工具名称采用命名空间格式（manual_name.tool_name）。部分插件（如 Socket, GraphQL）仍在开发中。","3.8+",[98,99,100,101,102,103,104],"pydantic","utcp","utcp-http","utcp-cli","utcp-mcp","utcp-text","python-dotenv",[13,15,14,26],[107,108,109,110,111,112,113,114,99],"ai","ai-agent","ai-agent-tools","developer-tools","llm","mcp","model-context-protocol","python","2026-03-27T02:49:30.150509","2026-04-06T06:55:14.972043",[118,123,128,133,138,143,148,153],{"id":119,"question_zh":120,"answer_zh":121,"source_url":122},17209,"文档中的导入路径不正确，导致 ImportError，正确的导入方式是什么？","在 utcp 0.1.8 版本中，文档中的示例导入路径有误。不要使用 `from utcp.client import UtcpClient`，而应使用实际的模块路径：`from utcp.client.utcp_client import UtcpClient`。这是因为 `UtcpClient` 类定义在 `utcp\u002Fclient\u002Futcp_client.py` 文件中，而非直接在 `utcp.client` 包下。请检查并更新所有文档示例以匹配实际的包结构。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F37",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},17210,"如何将现有的 MCP 服务器转换为 UTCP 手册（Manuals）？","可以通过调用 `McpCommunicationProtocol.register_manual` 方法来实现自动化或半自动化的转换。该方法接受一个或多个 MCP 服务器配置作为输入（封装在 `McpCallTemplate` 中），并返回一个包含生成手册的 `RegisterManualResult` 对象。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F68",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},17211,"是否应该将不同的传输协议（如 gRPC、GraphQL）拆分为独立的包？","目前社区倾向于保持在一个包中以便于添加新的传输类型，但主要担忧是依赖项过多。如果拆分，用户可以根据需要仅安装特定传输（如仅 HTTP 和 Text）的依赖，避免安装不需要的 gRPC 或 GraphQL 库。不过，维护者指出拆分可能导致仓库管理混乱，且并非所有编程语言都容易实现这种按需加载，因此目前仍在权衡灵活性与维护成本。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F25",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},17212,"如何参与 UTCP 项目贡献或成为维护者？","贡献者可以先加入项目的 Discord 服务器（https:\u002F\u002Fdiscord.gg\u002FY6Ycyz8nJR）进行协调。对于外部仓库的贡献（如 Langchain 集成或 Golang 实现），维护者建议将仓库转移到 UTCP 组织下，之后贡献者可被任命为该仓库的维护者并获得贡献者角色。同时，请在关于页面提供您的姓名和链接以便收录。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F6",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},17213,"Langchain 的集成实现目前状态如何？","已有草案实现（如 langchain-utcp-adapters），维护者确认该集成可以转移到 UTCP 组织下。需要注意的是，随着 UTCP 1.0.0 的发布，现有的 Langchain 集成代码需要更新以适配新版本的标准和接口。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F34",{"id":144,"question_zh":145,"answer_zh":146,"source_url":147},17214,"是否有计划支持基于嵌入（Embedding）的工具搜索功能？","是的，这是一个已确认的增强功能（Enhancement）。项目计划让工具可以通过嵌入模型进行搜索，以便更智能地匹配用户需求。该问题已被标记为“适合新手”，欢迎贡献者参与开发。如有进展疑问，建议加入 Discord 获取更快的回复。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F17",{"id":149,"question_zh":150,"answer_zh":151,"source_url":152},17215,"如何更新 Socket 通信协议以适配 UTCP 1.0 版本？","需要将 plugins\u002Fcommunication_protocols\u002Fsocket 中旧版本（0.2.3）的 TCP 和 UDP 实现更新为 1.0 版本的命名规范和约定。大部分现有实现逻辑仍然有效，主要工作集中在修改命名约定和更新相应的测试用例以符合新标准。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F46",{"id":154,"question_zh":155,"answer_zh":156,"source_url":157},17216,"是否有其他语言的 UTCP 实现（如 Golang）？","社区成员正在开发 Golang 版本的 UTCP 实现。维护者鼓励此类多语言移植工作，并建议将相关仓库转移到 UTCP 组织下以便吸引更多贡献者共同完善。目前已有社区成员协助开发。","https:\u002F\u002Fgithub.com\u002Funiversal-tool-calling-protocol\u002Fpython-utcp\u002Fissues\u002F14",[]]