FieldFlow

FieldFlow is an innovative tool that converts OpenAPI-described REST endpoints into tailored, easy-to-use interfaces. This project not only generates Pydantic models but also creates FastAPI routes capable of forwarding requests to upstream APIs while returning only the specific fields requested by users. Additionally, it features an optional Model Context Protocol (MCP) layer, which extends its capabilities to clients such as Claude Desktop.

Key Features

• OpenAPI Discovery: Automatically discovers endpoints and schemas from OpenAPI 3.0 JSON or YAML specifications.
• Dynamic Model Generation: Builds request and response Pydantic models on-the-fly, ensuring that aliases and optional fields are preserved.
• Flexible Response Filtering: Generates FastAPI routes that allow users to send requests with parameters and an optional fields list to selectively slice responses.
• Efficient Proxying: Proxies requests using httpx, automatically formatting URL paths and query parameters for easy interfacing.
• Broad Compatibility: Works seamlessly with any OpenAPI-compliant specification, accommodating nested schemas and references.

Project Structure

fieldflow/
  config.py          # Contains environment-based settings
  http_app.py        # FastAPI application factory
  openapi_loader.py  # Loads JSON/YAML specifications with a fallback to PyYAML
  proxy.py           # Asynchronous HTTP proxy that filters responses based on requested fields
  spec_parser.py     # Parses schemas and dynamically generates Pydantic models
  tooling.py         # Constructs FastAPI routers for tool endpoints
fieldflow_mcp/
  server.py          # MCP server wrapper built on FastMCP
  cli.py             # Command line interface entry point for the MCP server
examples/
  jsonplaceholder_openapi.yaml  # Minimal example specification
  pokeapi_openapi.yaml          # More extensive specification for stress testing

Example Usage

FieldFlow makes it easy to retrieve data according to specific needs. Here are a couple of examples:

Default Tool Call Using JSONPlaceholder

Fetch specific fields for a user:

curl -X POST http://127.0.0.1:8000/tools/get_user_info \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1, "fields": ["name", "email"]}'

List user posts, returning only the id and title:

curl -X POST http://127.0.0.1:8000/tools/list_posts \
  -H "Content-Type: application/json" \
  -d '{"userId": 1, "fields": ["id", "title"]}'

Switching to PokeAPI

Change the OpenAPI spec to PokeAPI:

dexport FIELD_FLOW_OPENAPI_SPEC_PATH=examples/pokeapi_openapi.yaml
fieldflow serve-http --reload

List abilities:

curl -X POST http://127.0.0.1:8000/tools/ability_list \
  -H "Content-Type: application/json" \
  -d '{"limit": 5, "fields": ["results"]}'

Interactive Documentation

FastAPI automatically provides interactive documentation at http://127.0.0.1:8000/docs, allowing users to explore and invoke the generated tool endpoints easily.

Command Line Interface

For streamlined interactions, the bundled CLI can be utilized:

# Start the HTTP proxy
fieldflow serve-http --host 127.0.0.1 --port 8000

# Start the MCP server over standard input/output
fieldflow-mcp

Testing

To ensure code quality and functionality, the asynchronous test suite can be executed using pytest:

pip install -e .[dev]
pytest

Connecting to Claude Desktop via MCP

To integrate with Claude Desktop:

1. Install FieldFlow with MCP support (pip install -e '.[mcp]').
2. Claude Desktop will automatically launch configured MCP servers on startup.
3. Configure Claude Desktop to point to the FieldFlow server by modifying the settings, and paste a configuration from claude_config_example/claude_desktop_config.json.
4. For further instructions, refer to the Model Context Protocol guide: https://modelcontextprotocol.io/docs/develop/connect-local-servers.
5. Once configured, Claude will list and can invoke the generated tools during chats.