Skip to content
Back to search

fieldflow

FieldFlow turns OpenAPI-described REST endpoints into selectively filtered tools. It generates Pydantic models and FastAPI routes that forward requests to the upstream API and return only the fields…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/guillaumegay13--fieldflow/badge.svg)](/listings/guillaumegay13--fieldflow)

HTML

<a href="/listings/guillaumegay13--fieldflow"><img src="/api/listings/guillaumegay13--fieldflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e '.[mcp]'  # zsh users: quote to avoid globbing
fieldflow serve-http --reload

OpenAPI specs are resolved from `FIELD_FLOW_OPENAPI_SPEC_PATH`. If the spec includes a `servers` entry the first URL is used; otherwise set `FIELD_FLOW_TARGET_API_BASE_URL`.

Environment Variables

| Variable | Description | Default | | --- | --- | --- | | `FIELD_FLOW_OPENAPI_SPEC_PATH` | Path to the OpenAPI JSON/YAML file | `examples/jsonplaceholder_openapi.yaml` | | `FIELD_FLOW_TARGET_API_BASE_URL` | Upstream REST API base URL (overrides spec `servers`) | _derived from spec_ |

Authentication

FieldFlow supports secure API authentication through environment variables. All credentials are handled securely with automatic sanitization in logs and error messages.

Simple Authentication

# Bearer token (OAuth 2.0, JWT)
export FIELDFLOW_AUTH_TYPE=bearer
export FIELDFLOW_AUTH_VALUE=your-token-here

# API Key
export FIELDFLOW_AUTH_TYPE=apikey
export FIELDFLOW_AUTH_HEADER=X-API-Key  # Optional, defaults to X-API-Key
export FIELDFLOW_AUTH_VALUE=your-api-key-here

# Basic authentication
export FIELDFLOW_AUTH_TYPE=basic
export FIELDFLOW_AUTH_VALUE=base64-encoded-credentials

OpenAPI Security Schemes

When your OpenAPI spec defines security schemes, FieldFlow automatically uses them:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

With security schemes, provide credentials using the scheme name:

export FIELDFLOW_AUTH_BEARERAUTH_VALUE=your-bearer-token
export FIELDFLOW_AUTH_APIKEYAUTH_VALUE=your-api-key

**Security features:** - Credentials are never logged or stored - Auth headers are sanitized in all error messages - Memory-safe handling with immediate credential clearing - Environment-only configuration (no hardcoded secrets)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 301 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # FieldFlow
  2. FieldFlow turns OpenAPI-described REST endpoints into selectively filtered tools. It generates Pydantic models and FastAPI routes that forward requests to the upstream API and return only the fields the caller asks for. An optional MCP layer exposes those generated OpenAPI tools to Model Context Protocol clients such as Claude Desktop.
  3. [![Watch the FieldFlow demo](https://img.youtube.com/vi/-pgy0FICWpQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=-pgy0FICWpQ)
  4. ## Features
  5. - Discovers endpoints and schemas from OpenAPI 3.0 JSON or YAML files.
  6. - Builds request/response Pydantic models dynamically, preserving aliases and
  7. optional fields.
  8. - Generates FastAPI routes that accept parameters plus an optional `fields`
  9. list to slice responses.
  10. - Proxies requests with `httpx`, automatically formatting URL paths and query
  11. parameters.
  12. - Works with any OpenAPI-compliant spec, including nested schemas and refs.
  13. ## What FieldFlow Supports Today
  14. FieldFlow currently has two supported application modes:
  15. 1. `fieldflow serve-http` exposes generated HTTP tool endpoints from an OpenAPI spec.
  16. 2. `fieldflow-mcp` exposes the same generated OpenAPI tools through MCP over stdio.
  17. FieldFlow does not yet wrap arbitrary third-party MCP servers. That direction is planned around MCP tools that expose structured `outputSchema`, but it is not part of the current release.
  18. ## Project Layout
  19. ```
  20. fieldflow/
  21. config.py # Environment-based settings
  22. http_app.py # FastAPI app factory
  23. openapi_loader.py # JSON/YAML loader with PyYAML fallback
  24. proxy.py # Async HTTP proxy that filters responses to requested fields
  25. spec_parser.py # Schema parser and dynamic Pydantic model generator
  26. tooling.py # FastAPI router builder for tool endpoints
  27. fieldflow_mcp/
  28. server.py # MCP server wrapper built on FastMCP
  29. cli.py # CLI entry point for the MCP server
  30. examples/
  31. jsonplaceholder_openapi.yaml # Minimal sample spec
  32. pokeapi_openapi.yaml # Larger spec for stress-testing
  33. ```
  34. ## Quickstart
  35. ```bash
  36. python -m venv .venv
  37. source .venv/bin/activate
  38. pip install --upgrade pip
  39. pip install -e '.[mcp]' # zsh users: quote to avoid globbing
  40. fieldflow serve-http --reload
  41. ```
  42. OpenAPI specs are resolved from `FIELD_FLOW_OPENAPI_SPEC_PATH`. If the spec
  43. includes a `servers` entry the first URL is used; otherwise set
  44. `FIELD_FLOW_TARGET_API_BASE_URL`.
  45. ### Environment Variables
  46. | Variable | Description | Default |
  47. | --- | --- | --- |
  48. | `FIELD_FLOW_OPENAPI_SPEC_PATH` | Path to the OpenAPI JSON/YAML file | `examples/jsonplaceholder_openapi.yaml` |
  49. | `FIELD_FLOW_TARGET_API_BASE_URL` | Upstream REST API base URL (overrides spec `servers`) | _derived from spec_ |
  50. ### Authentication
  51. FieldFlow supports secure API authentication through environment variables. All credentials are handled securely with automatic sanitization in logs and error messages.
  52. #### Simple Authentication
  53. ```bash
  54. # Bearer token (OAuth 2.0, JWT)
  55. export FIELDFLOW_AUTH_TYPE=bearer
  56. export FIELDFLOW_AUTH_VALUE=your-token-here
  57. # API Key
  58. export FIELDFLOW_AUTH_TYPE=apikey
  59. export FIELDFLOW_AUTH_HEADER=X-API-Key # Optional, defaults to X-API-Key
  60. export FIELDFLOW_AUTH_VALUE=your-api-key-here
  61. # Basic authentication
  62. export FIELDFLOW_AUTH_TYPE=basic
  63. export FIELDFLOW_AUTH_VALUE=base64-encoded-credentials
  64. ```
  65. #### OpenAPI Security Schemes
  66. When your OpenAPI spec defines security schemes, FieldFlow automatically uses them:
  67. ```yaml
  68. components:
  69. securitySchemes:
  70. BearerAuth:
  71. type: http
  72. scheme: bearer
  73. ApiKeyAuth:
  74. type: apiKey
  75. in: header
  76. name: X-API-Key
  77. ```
  78. With security schemes, provide credentials using the scheme name:
  79. ```bash
  80. export FIELDFLOW_AUTH_BEARERAUTH_VALUE=your-bearer-token
  81. export FIELDFLOW_AUTH_APIKEYAUTH_VALUE=your-api-key
  82. ```
  83. **Security features:**
  84. - Credentials are never logged or stored
  85. - Auth headers are sanitized in all error messages
  86. - Memory-safe handling with immediate credential clearing
  87. - Environment-only configuration (no hardcoded secrets)
  88. ## Example Tool Calls
  89. ### JSONPlaceholder (default)
  90. Fetch only selected fields for a user:
  91. ```bash
  92. curl -X POST http://127.0.0.1:8000/tools/get_user_info \
  93. -H "Content-Type: application/json" \
  94. -d '{"user_id": 1, "fields": ["name", "email"]}'
  95. ```
  96. List posts for a user, reducing each item to `id` and `title`:
  97. ```bash
  98. curl -X POST http://127.0.0.1:8000/tools/list_posts \
  99. -H "Content-Type: application/json" \
  100. -d '{"userId": 1, "fields": ["id", "title"]}'
  101. ```
  102. ### Nested field selectors
  103. Request deeply nested data with a JSONPath-lite syntax tailored for LLMs:
  104. - Use dots (`damage_relations.double_damage_from`) to traverse objects.
  105. - Append `[]` to map over every element in a list (`moves[].move.name`).
  106. - Mix top-level and nested selectors in the same request; missing branches are skipped.
  107. Example with the PokeAPI spec:
  108. ```bash
  109. curl -X POST http://127.0.0.1:8000/tools/pokemon_read \
  110. -H "Content-Type: application/json" \
  111. -d '{"id": 150, "fields": ["name", "types[].type.name", "stats.attack.base_stat"]}'
  112. ```
  113. The proxy trims everything except Mewtwo's name, each type name, and the attack stat. Invalid selectors (for example `moves[0].move`) return a 422 error before the upstream API is called.
  114. ### PokeAPI
  115. Switch to the richer PokeAPI specification:
  116. ```bash
  117. export FIELD_FLOW_OPENAPI_SPEC_PATH=examples/pokeapi_openapi.yaml
  118. fieldflow serve-http --reload
  119. ```
  120. List the first few abilities:
  121. ```bash
  122. curl -X POST http://127.0.0.1:8000/tools/ability_list \
  123. -H "Content-Type: application/json" \
  124. -d '{"limit": 5, "fields": ["results"]}'
  125. ```
  126. Query a single ability by ID:
  127. ```bash
  128. curl -X POST http://127.0.0.1:8000/tools/ability_read \
  129. -H "Content-Type: application/json" \
  130. -d '{"id": 65, "fields": ["name", "effect_entries"]}'
  131. ```
  132. FastAPI automatically publishes documentation at
  133. [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), letting you explore
  134. and invoke the generated tool endpoints interactively.
  135. ## Command Line
  136. Use the bundled CLI for a streamlined experience:
  137. ```bash
  138. # Run the HTTP proxy
  139. fieldflow serve-http --host 127.0.0.1 --port 8000
  140. # Run the MCP server over stdio (ideal for Claude Desktop)
  141. fieldflow-mcp
  142. ```
  143. ### Reduce Noisy CLI Output (`fieldflow-cli`)
  144. `fieldflow-cli` wraps any JSON-emitting CLI (`gh`, `gcloud`, `kubectl`, `aws`,
  145. …) and returns only the fields you project. The wrapped command runs once,
  146. but the model only ever sees the reduced payload — which is how you keep
  147. noisy `list` / `get` / `describe` / `logs` output out of your context window.
  148. **Example — open PRs on a GitHub repo:**
  149. ```bash
  150. # 1. Inspect the shape (writes a compact manifest to .fieldflow/inspect/)
  151. fieldflow-cli inspect -- \
  152. gh pr list --repo mnfst/manifest --state open \
  153. --json number,title,author,createdAt,isDraft,additions,deletions,changedFiles,labels,body \
  154. --limit 100
  155. # 2. Re-run with just the fields you actually need
  156. fieldflow-cli \
  157. --field "[].number" \
  158. --field "[].title" \
  159. --field "[].author.login" \
  160. --field "[].createdAt" \
  161. --field "[].isDraft" \
  162. --field "[].additions" \
  163. --field "[].deletions" \
  164. --field "[].changedFiles" \
  165. --field "[].labels[].name" \
  166. -- \
  167. gh pr list --repo mnfst/manifest --state open \
  168. --json number,title,author,createdAt,isDraft,additions,deletions,changedFiles,labels,body \
  169. --limit 100
  170. ```
  171. On a real run against `mnfst/manifest` (26 open PRs), this dropped the
  172. payload from **23,722 tokens to 2,779** — an **88% reduction**, mostly by
  173. stripping PR `body` markdown.
  174. **Example — Cloud Run error logs:**
  175. ```bash
  176. fieldflow-cli \
  177. --field "[].timestamp" \
  178. --field "[].severity" \
  179. --field "[].httpRequest.requestUrl" \
  180. --field "[].jsonPayload.message" \
  181. --max-items 25 \
  182. -- \
  183. gcloud logging read \
  184. 'resource.type="cloud_run_revision" AND severity>=ERROR' \
  185. --project=my-project --freshness=24h --limit=2000 --format=json
  186. ```
  187. The wrapped command must already support JSON output (`gh --json …`,
  188. `gcloud --format=json`, `kubectl -o json`, `aws --output json`). If the
  189. projection is too narrow, broaden it and rerun. The older
  190. `fieldflow run-cli …` form still works, but `fieldflow-cli …` is the
  191. intended direct wrapper.
  192. ### Claude Code Skill (one-step install)
  193. This repo ships a Claude Code skill that teaches the agent **when** to reach
  194. for `fieldflow-cli` automatically — on noisy `gh`, `gcloud`, `kubectl`, `aws`
  195. commands, but not on trivial local ones. Install it with a symlink so it
  196. stays in sync with the repo:
  197. ```bash
  198. mkdir -p ~/.claude/skills
  199. ln -s "$(pwd)/.agents/skills/fieldflow-cli" ~/.claude/skills/fieldflow-cli
  200. ```
  201. Or copy it if you prefer a snapshot:
  202. ```bash
  203. cp -r .agents/skills/fieldflow-cli ~/.claude/skills/
  204. ```
  205. That's it — next time Claude Code starts, the `fieldflow-cli` skill is
  206. available and will be invoked on qualifying JSON CLI commands.
  207. The skill source lives at
  208. [`.agents/skills/fieldflow-cli/SKILL.md`](.agents/skills/fieldflow-cli/SKILL.md).
  209. An OpenAI-agent variant is also provided under
  210. [`.agents/skills/fieldflow-cli/agents/openai.yaml`](.agents/skills/fieldflow-cli/agents/openai.yaml).
  211. ## Testing
  212. Install the development dependencies and run the same checks used in CI:
  213. ```bash
  214. pip install -e '.[dev,mcp]'
  215. ruff check fieldflow fieldflow_mcp tests
  216. black --check fieldflow fieldflow_mcp tests
  217. mypy fieldflow fieldflow_mcp
  218. pytest
  219. python -m build
  220. python -m pip check
  221. ```
  222. ## MCP Integration
  223. To connect the server to Claude Desktop:
  224. 1. Install with the MCP extra (`pip install -e '.[mcp]'`).
  225. 2. Claude Desktop launches configured MCP servers on startup, so there is no need to run `fieldflow-mcp` manually.
  226. 3. Open Claude Desktop > Settings > Developer > Modify Config, then paste a configuration that points to the FieldFlow server (see `claude_config_example/claude_desktop_config.json`).
  227. 4. For additional details, review the Model Context Protocol guide: https://modelcontextprotocol.io/docs/develop/connect-local-servers.
  228. 5. Claude will automatically list the generated tools and can invoke them during chats once the config is saved.
  229. ## Contributing
  230. Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
  231. instructions on setting up a development environment and submitting changes.
  232. ## License
  233. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.