Skip to content
Back to search

web-shooter

MarketplaceWorks with Claude CodeGitHub

web-shooter: generate tested MCP servers from API docs and OpenAPI specs.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ggbifulco--web-shooter/badge.svg)](/listings/ggbifulco--web-shooter)

HTML

<a href="/listings/ggbifulco--web-shooter"><img src="/api/listings/ggbifulco--web-shooter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

# with uv (recommended)
uvx --from git+https://github.com/ggbifulco/web-shooter web-shooter shoot \
    https://petstore3.swagger.io/api/v3/openapi.json --install-claude project

# or install it
pip install git+https://github.com/ggbifulco/web-shooter
web-shooter shoot ./openapi.yaml --dry-run      # see the planned tools
web-shooter shoot ./openapi.yaml                # generate + test -> out/<name>-mcp
web-shooter test out/<name>-mcp --live          # re-run tests against the real API

Specs (OpenAPI 3.x, Swagger 2.0; JSON or YAML; file or URL) need no API key. HTML documentation pages are read with Claude and need `ANTHROPIC_API_KEY` (see [.env.example](.env.example)).

As a Claude Code plugin

/plugin install web-shooter --marketplace ggbifulco/web-shooter
/web-shooter https://petstore3.swagger.io/api/v3/openapi.json

The plugin adds a `/web-shooter` command and a skill that tells Claude when to use it. After the tests pass, the generated server is registered in the project's `.mcp.json`.

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.

.claude-plugin/marketplace.json · Manifest · 23 lines
  1. {
  2. "name": "web-shooter",
  3. "description": "web-shooter: generate tested MCP servers from API docs and OpenAPI specs.",
  4. "owner": {
  5. "name": "Giuseppe Bifulco",
  6. "url": "https://github.com/ggbifulco"
  7. },
  8. "plugins": [
  9. {
  10. "name": "web-shooter",
  11. "source": "./plugin",
  12. "description": "Turn any API docs URL or OpenAPI spec into a tested MCP server and register it in Claude Code.",
  13. "version": "0.1.0",
  14. "category": "development",
  15. "keywords": [
  16. "mcp",
  17. "openapi",
  18. "api",
  19. "codegen"
  20. ]
  21. }
  22. ]
  23. }
README.md · README · 141 lines
  1. # web-shooter 🕸️
  2. [![CI](https://github.com/ggbifulco/web-shooter/actions/workflows/ci.yml/badge.svg)](https://github.com/ggbifulco/web-shooter/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
  5. **Point it at any API docs or OpenAPI spec and get a tested, working MCP server.**
  6. web-shooter reads an API description, decides which endpoints make good tools, generates a
  7. standalone [MCP](https://modelcontextprotocol.io) server, tests every tool in a sandbox, asks an
  8. LLM to repair whatever fails, and registers the result in Claude Code.
  9. ![demo](docs/demo.gif)
  10. ## Why
  11. Every assistant can call an API through MCP, but most APIs don't ship an MCP server. Writing one
  12. by hand means mapping endpoints to tools, handling auth, pagination and errors, and then hoping
  13. it works. web-shooter does that in seconds and **proves** it works with generated tests, instead
  14. of handing you code that merely compiles.
  15. ## Quick start
  16. ```bash
  17. # with uv (recommended)
  18. uvx --from git+https://github.com/ggbifulco/web-shooter web-shooter shoot \
  19. https://petstore3.swagger.io/api/v3/openapi.json --install-claude project
  20. # or install it
  21. pip install git+https://github.com/ggbifulco/web-shooter
  22. web-shooter shoot ./openapi.yaml --dry-run # see the planned tools
  23. web-shooter shoot ./openapi.yaml # generate + test -> out/<name>-mcp
  24. web-shooter test out/<name>-mcp --live # re-run tests against the real API
  25. ```
  26. Specs (OpenAPI 3.x, Swagger 2.0; JSON or YAML; file or URL) need no API key.
  27. HTML documentation pages are read with Claude and need `ANTHROPIC_API_KEY`
  28. (see [.env.example](.env.example)).
  29. ### As a Claude Code plugin
  30. ```
  31. /plugin install web-shooter --marketplace ggbifulco/web-shooter
  32. /web-shooter https://petstore3.swagger.io/api/v3/openapi.json
  33. ```
  34. The plugin adds a `/web-shooter` command and a skill that tells Claude when to use it. After the
  35. tests pass, the generated server is registered in the project's `.mcp.json`.
  36. ## How it works
  37. ```mermaid
  38. flowchart LR
  39. A[OpenAPI / Swagger spec] --> I[Ingest]
  40. B[HTML API docs] -->|crawl + LLM extraction| I
  41. I --> IR[(API IR)]
  42. IR --> T[Tool design]
  43. T -->|optional LLM polish| G[Codegen]
  44. G --> S[Sandbox: local or Docker]
  45. S --> R{Generated tests pass?}
  46. R -->|no| F[LLM self-repair: search/replace patches]
  47. F --> S
  48. R -->|yes| P[Package + register in Claude Code]
  49. ```
  50. | Stage | What happens | Code |
  51. |---|---|---|
  52. | Ingest | OpenAPI/Swagger parsed with `$ref` resolution (cycles cut), Swagger 2 converted; HTML docs crawled (same section, depth-limited), cleaned to markdown, split per endpoint, extracted by Claude with structured outputs. Every extracted endpoint keeps its source URL and a verbatim excerpt; a grounding check lowers confidence when the excerpt or path isn't really in the page. | [`ingest/`](src/web_shooter/ingest) |
  53. | IR | One normalized model (`APISpec`, `Endpoint`, `Parameter`, `AuthScheme`…) that every later stage consumes. | [`ir.py`](src/web_shooter/ir.py) |
  54. | Tool design | Stable snake_case names, descriptions with the HTTP signature, JSON input schemas (flat body fields or a wrapped `body`), `all_pages` for page/offset pagination, DELETE skipped unless `--include-destructive`, optional CRUD consolidation into one tool with an `action` enum. | [`tools.py`](src/web_shooter/tools.py) |
  55. | Codegen | A standalone package: `pyproject.toml`, `Dockerfile`, README, `tools.json` and a small runtime on the official MCP SDK (auth via env vars, retries on 429/5xx, host allowlist, mock mode). | [`codegen/`](src/web_shooter/codegen) |
  56. | Sandbox | `local` subprocess, or `docker` with `--network none` (mock), `--read-only`, memory/CPU/pids limits, all capabilities dropped. | [`sandbox.py`](src/web_shooter/sandbox.py) |
  57. | Tests | Per tool: a valid call (response validated against the declared schema), a call missing a required argument and one with a wrong type (both must be rejected). Mock mode needs no key; `--live` hits the real API and marks 4xx answers to made-up inputs as *inconclusive*, not passed. | [`testing.py`](src/web_shooter/testing.py) |
  58. | Self-repair | Failures (arguments, error, response) plus `tools.json` and the runtime go to Claude, which answers with search/replace edits. Bounded iterations, every edit validated, each round logged to `repair_log.json`. | [`repair.py`](src/web_shooter/repair.py) |
  59. ## Benchmark
  60. `uv run python benchmarks/run.py` runs the whole pipeline on 20 public APIs
  61. ([list](benchmarks/apis.yaml)): 16 specs, 4 docs-only sites. Mock-mode tests, local sandbox, no LLM
  62. key in this run.
  63. <!-- benchmark:start -->
  64. | API | Input | Endpoints | Tools | Tests passed | Repair iters | LLM cost | Time | Status |
  65. |---|---|---:|---:|---:|---:|---:|---:|---|
  66. | Swagger Petstore v3 | spec | 19 | 16 | 38/38 | 0 | $0.00 | 2.5s | ok |
  67. | Swagger Petstore v2 | spec | 20 | 16 | 39/39 | 0 | $0.00 | 2.2s | ok |
  68. | xkcd | spec | 2 | 2 | 4/4 | 0 | $0.00 | 1.7s | ok |
  69. | APIs.guru | spec | 7 | 7 | 15/15 | 0 | $0.00 | 1.8s | ok |
  70. | NYT Top Stories | spec | 1 | 1 | 3/3 | 0 | $0.00 | 1.9s | ok |
  71. | Spotify | spec | 88 | 80 | 214/214 | 0 | $0.00 | 4.2s | ok |
  72. | NASA APOD | spec | 1 | 1 | 2/2 | 0 | $0.00 | 1.8s | ok |
  73. | httpbin | spec | 73 | 67 | 138/138 | 0 | $0.00 | 2.4s | ok |
  74. | Listen Notes | spec | 23 | 22 | 64/66 | 0 | $0.00 | 2.7s | failing |
  75. | Wikimedia | spec | 35 | 35 | 101/101 | 0 | $0.00 | 2.4s | ok |
  76. | Giphy | spec | 10 | 10 | 25/25 | 0 | $0.00 | 2.1s | ok |
  77. | ExchangeRate-API | spec | 1 | 1 | 3/3 | 0 | $0.00 | 1.7s | ok |
  78. | Lyft | spec | 16 | 16 | 43/46 | 0 | $0.00 | 2.0s | failing |
  79. | CircleCI | spec | 22 | 19 | 50/50 | 0 | $0.00 | 2.0s | ok |
  80. | UK Vehicle Enquiry | spec | 1 | 1 | 3/3 | 0 | $0.00 | 1.7s | ok |
  81. | Gitea | spec | 325 | 267 | 747/747 | 0 | $0.00 | 11.0s | ok |
  82. | JSONPlaceholder | docs | - | - | - | - | - | - | needs LLM key |
  83. | Dog CEO | docs | - | - | - | - | - | - | needs LLM key |
  84. | Random User | docs | - | - | - | - | - | - | needs LLM key |
  85. | Chuck Norris | docs | - | - | - | - | - | - | needs LLM key |
  86. **14/16 APIs fully green, 1489/1494 generated tests passing** (4 not run).
  87. <!-- benchmark:end -->
  88. Notes, so the numbers are read correctly:
  89. - The 5 remaining failures come from the specs themselves: Lyft declares `ride_profile` as both
  90. `type: object` and a string enum, and two Listen Notes responses use `oneOf` options that any
  91. object matches, so no response can satisfy them. web-shooter reports this instead of hiding it.
  92. - Mock mode checks that every tool accepts valid input, rejects invalid input and that its
  93. request is built correctly; it does not prove the real API behaves as documented. Use `--live`
  94. with credentials for that.
  95. - Docs-only rows need `ANTHROPIC_API_KEY`; repair iterations and LLM cost are 0 here because all
  96. spec-based servers passed without repair.
  97. - Running the benchmark found and fixed four real bugs in the mock-data generator and the
  98. Swagger converter (see the git history).
  99. ## Development
  100. ```bash
  101. uv sync
  102. uv run pytest # 77 tests; Docker tests run when a daemon is available
  103. uv run ruff check . && uv run ruff format --check . && uv run mypy
  104. ```
  105. The suite includes a fake Petstore HTTP server, so live-mode tests (real HTTP, auth, pagination
  106. across pages, 404 handling) run offline. LLM steps are tested with a scripted LLM.
  107. ## Roadmap
  108. Tracked on the [project board](https://github.com/users/ggbifulco/projects/5). Ideas next:
  109. OAuth2 flows, streamable HTTP transport for generated servers, an egress proxy for a real
  110. network allowlist in live Docker runs, and an LLM-backed benchmark run on the docs-only APIs.
  111. ## License
  112. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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