关键词

OpenAPI工具生成LLM外部功能API代理字段筛选Claude Desktop集成

项目简介

FieldFlow是一个创新的工具，它能够将任何符合OpenAPI规范的REST API自动转换为LLM（大型语言模型）可调用的工具。通过动态生成Pydantic模型和FastAPI路由，FieldFlow不仅代理请求到上游API，还能根据LLM客户端的需求，智能地筛选响应数据中的特定字段。其可选的MCP层确保了与Model Context Protocol客户端（如Claude Desktop）的无缝集成，为LLM应用提供安全、可扩展的外部功能调用能力。

主要功能点

  • OpenAPI集成： 自动从OpenAPI 3.0 JSON或YAML文件中发现API端点和数据模式。
  • 动态工具生成： 将每个API操作转换为一个可被LLM调用的工具，支持路径参数、查询参数和请求体。
  • 响应字段筛选： 允许LLM客户端指定只返回API响应中的特定字段，减少数据量，提高效率。
  • 灵活的认证： 支持通过环境变量配置多种认证方式（如Bearer Token、API Key、Basic Auth），也兼容OpenAPI规范中定义的认证方案。
  • 协议支持： 通过标准的Model Context Protocol (MCP) 与LLM客户端通信，支持Stdio、SSE、WebSocket等多种传输协议。
  • FastAPI网关： 同时提供一个基于FastAPI的HTTP网关，方便开发和测试。

安装步骤

  1. 创建并激活虚拟环境（推荐）： 
    python -m venv .venv
source .venv/bin/activate
  2. 安装FieldFlow及MCP扩展： 
    pip install --upgrade pip
pip install -e '.[mcp]' # 如果使用zsh，请在单引号外加双引号："'.[mcp]'"

服务器配置 (MCP客户端使用)

FieldFlow MCP服务器需要通过MCP客户端（如Claude Desktop）启动。客户端需要一个JSON配置来指定如何启动FieldFlow服务器。以下是一个配置示例和参数注释：

{
  "servers": [
    {
      "name": "fieldflow-mcp-server",
      "command": ["python", "-m", "fieldflow_mcp.cli"],
      "args": [
        "--transport", "stdio",
        "--name", "MyCustomFieldFlow",
        // 以下参数也可通过环境变量FIELD_FLOW_OPENAPI_SPEC_PATH和FIELD_FLOW_TARGET_API_BASE_URL配置
        // "--openapi-spec-path", "/path/to/your/openapi.yaml",
        // "--target-api-base-url", "https://api.example.com"
      ],
      "env": {
        // API认证凭据，根据上游API要求进行配置
        // "FIELD_FLOW_AUTH_TYPE": "apikey", // 认证类型，如bearer, apikey, basic
        // "FIELD_FLOW_AUTH_HEADER": "X-API-Key", // API Key或Basic认证时使用的HTTP头名称
        // "FIELD_FLOW_AUTH_VALUE": "YOUR_API_KEY" // 认证凭据的值（如Bearer Token、API Key、Base64编码的Basic凭据）
      }
    }
  ]
}

配置参数说明：

  • 'name': 服务器在MCP客户端界面显示的名称。
  • 'command': 启动FieldFlow MCP服务器的Python命令。
    • 'python': Python解释器。
    • '-m fieldflow_mcp.cli': 运行'fieldflow_mcp'模块的命令行入口。
  • 'args': 传递给'fieldflow_mcp.cli'的参数列表。
    • '--transport': 指定MCP通信的传输协议，例如'stdio'（适用于Claude Desktop）。可选值包括'stdio', 'sse', 'streamable-http'。
    • '--name': (可选) 覆盖MCP服务器的默认名称。
    • '--openapi-spec-path': (可选，推荐通过环境变量配置) 指定OpenAPI规范文件的路径，例如'examples/jsonplaceholder_openapi.yaml'。
    • '--target-api-base-url': (可选，推荐通过环境变量配置) 指定上游REST API的基础URL。如果OpenAPI规范中已定义'servers'，则可省略。
  • 'env': (可选) 启动服务器时设置的环境变量，用于API认证等，优先级高于'args'中同名配置。
    • 'FIELD_FLOW_AUTH_TYPE': 认证类型，如'bearer', 'apikey', 'basic'。
    • 'FIELD_FLOW_AUTH_HEADER': API Key或Basic认证时使用的HTTP头名称，如'X-API-Key'。
    • 'FIELD_FLOW_AUTH_VALUE': 认证凭据的值（如Bearer Token、API Key、Base64编码的Basic凭据）。

基本使用方法

  1. 准备OpenAPI规范文件： 确保您有一个OpenAPI 3.0 JSON或YAML文件，描述了您希望暴露给LLM的REST API。例如，可以使用项目提供的'examples/jsonplaceholder_openapi.yaml'。
  2. 配置FieldFlow：
    • 通过MCP客户端配置中的'args'参数或环境变量'FIELD_FLOW_OPENAPI_SPEC_PATH'设置您的OpenAPI文件路径。
    • 如果您的OpenAPI规范未指定API的基础URL，或者您想覆盖它，请通过'args'参数或环境变量'FIELD_FLOW_TARGET_API_BASE_URL'进行设置。
    • 根据上游API的认证要求，在MCP客户端配置的'env'部分或系统环境变量中，配置相应的认证信息（'FIELD_FLOW_AUTH_TYPE'、'FIELD_FLOW_AUTH_VALUE'等）。
  3. 连接到MCP客户端：
    • 打开您的MCP客户端（例如Claude Desktop）。
    • 进入客户端的开发者设置或配置页面。
    • 粘贴上述“服务器配置”中生成的JSON配置信息，并保存。
    • 客户端将自动启动FieldFlow MCP服务器并发现其暴露的工具。
  4. 在LLM对话中使用工具： 一旦配置完成，LLM将在对话中自动列出并能够调用FieldFlow生成的工具。您可以通过提供必要的参数（包括可选的'fields'列表来筛选响应数据）来与外部API进行交互。

信息

分类

开发者工具

访问项目