openapi-agent-ready 0.2.0__tar.gz → 0.3.0__tar.gz

{openapi_agent_ready-0.2.0 → openapi_agent_ready-0.3.0}/CHANGELOG.md

@@ -5,6 +5,49 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-31
+
+### Added
+- **Progress indicator for long audits.** The ambiguity check dominates runtime
+  on large specs and previously produced no output while running — a 587-endpoint
+  spec looked like the tool had hung. A progress bar now reports on stderr, shown
+  only for specs above 150 endpoints and only when stderr is a terminal, so piped
+  output and `--format json` stay clean.
+
+### Changed
+- **Ambiguity check is ~4.7x faster** (Stripe: 77s to 16s; Asana: 6.4s to 1.6s)
+  using `SequenceMatcher`'s `real_quick_ratio` and `quick_ratio` as prefilters.
+  Both are documented upper bounds on `ratio()`, so a pair rejected by a cheap
+  bound could not have exceeded the threshold anyway. Results are verified
+  identical to the unoptimised implementation.
+
+  Truncating comparison text was also tried and rejected: another ~5x, but it
+  changed which pairs were reported. A faster check that disagrees with itself
+  is not an optimisation.
+
+  A subtler trap surfaced here too: `SequenceMatcher.ratio()` is not symmetric,
+  because the autojunk heuristic applies to the second sequence only. The first
+  version of this optimisation reversed the argument order to reuse a cached
+  sequence — it was faster, passed every existing test, and silently reported
+  different pairs. Results are now pinned against a reference implementation.
+
+## [0.2.1] - 2026-07-31
+
+Found by running the published 0.2.0 against Asana's public spec.
+
+### Fixed
+- **Generated scaffolds could contain duplicate arguments and fail to parse.**
+  OpenAPI identifies a parameter by name *and* location, and an operation-level
+  declaration overrides a path-level one. The extractor concatenated both lists
+  without deduplicating, so a spec declaring the same parameter at each level —
+  Asana's declares `project_gid` that way — produced a function with two
+  identically-named arguments, a Python `SyntaxError`. Parameters declared at
+  both levels are now deduplicated with operation-level winning; the same name
+  in a different location is still treated as distinct.
+- **`--version` reported a stale hardcoded number.** The CLI printed `0.1.0`
+  from a published 0.2.0 install. The version is now read from installed package
+  metadata, so `pyproject.toml` is the single source of truth and cannot drift.
+
 ## [0.2.0] - 2026-07-30
 
 The generated MCP scaffold is now verified against the real protocol rather than
@@ -16,18 +59,27 @@ against the current SDK.
 against mcp 2.x.
 
 ### Added
-- **MCP conformance test suite** (`tests/test_mcp_conformance.py`). Launches the
-  generated scaffold as a subprocess, completes a real MCP handshake over stdio
-  using the official client, and validates the advertised tool definitions: name
-  format, uniqueness, description presence, input-schema validity as JSON Schema,
+- **MCP conformance test suite.** Launches the generated scaffold as a
+  subprocess, completes a real MCP handshake over stdio using the official
+  client, and validates the advertised tool definitions: name format,
+  uniqueness, description presence, input-schema validity as JSON Schema,
   required-argument correctness, and side-effect disclosure. Previously the only
   check on generated output was that the file compiled.
+- **Tool Surface & Schema Strictness** category (category 8), derived from
+  OpenAI's function-calling guidance: flags catalogues far above the ~20-tool
+  ceiling, request bodies incompatible with strict mode
+  (`additionalProperties: false`, all properties required), and parameters that
+  imply a fixed value set but accept free-form strings where an enum belongs.
 - **`ToolAnnotations` on generated tools** (`readOnlyHint`, `destructiveHint`,
   `idempotentHint`, `openWorldHint`), derived from the HTTP method. Prose in a
   description helps a model reason about side effects; annotations let a client
   *enforce* — auto-approving reads while requiring confirmation for writes.
 - **`[server]` extra**, a clearer alias for `[mcp]`: these are dependencies the
   *generated* server needs at runtime, not dependencies of the auditor.
+- Findings now carry a `scope` ("endpoint" or "spec"). Spec-level findings are
+  weighted at 50% of their category so a single whole-API finding isn't averaged
+  away against hundreds of endpoint findings. Stripe's tool-surface score was
+  99/100 before this fix and 49.6/100 after.
 
 ### Fixed
 - **Generated scaffolds failed to import on mcp 2.0.** FastMCP was replaced by
@@ -57,6 +109,10 @@ against mcp 2.x.
   wrapper and leaves the real error truncated.
 
 ### Changed
+- **Distribution renamed to `openapi-agent-ready`.** PyPI rejected `agent-ready`
+  as too similar to the existing `agentready` package — its similarity check
+  strips separators before comparing. Import name (`agent_ready`), CLI command
+  (`agent-ready`), and repository name are unchanged.
 - **Generated scaffolds are self-documenting.** The file header states its
   dependencies, how to run it, a paste-ready Claude Desktop config block, and
   three things to fix before shipping — notably that the scaffold sends no
@@ -67,26 +123,10 @@ against mcp 2.x.
 - Tool listings are fetched once per generated file and cached rather than
   spawning a server subprocess per test, cutting spawns from ~14 to 4.
 
-## [0.1.1] - 2026-07-29
-
-### Added
-- **Tool Surface & Schema Strictness** category (category 8), derived from
-  OpenAI's function-calling guidance: flags catalogues far above the ~20-tool
-  ceiling, request bodies incompatible with strict mode
-  (`additionalProperties: false`, all properties required), and parameters that
-  imply a fixed value set but accept free-form strings where an enum belongs.
-- Findings now carry a `scope` ("endpoint" or "spec"). Spec-level findings are
-  weighted at 50% of their category so a single whole-API finding isn't averaged
-  away against hundreds of endpoint findings. Stripe's tool-surface score was
-  99/100 before this fix and 49.6/100 after.
-
-### Changed
-- Distribution name is `openapi-agent-ready` (PyPI rejected `agent-ready` as too
-  similar to the existing `agentready` package). Import name, CLI command, and
-  repo name are unchanged.
-
 ## [0.1.0] - 2026-07-28
 
+Initial release.
+
 ### Added
 - Seven-category AI-readiness rubric for OpenAPI specs
 - CLI with text, markdown, and JSON output formats

{openapi_agent_ready-0.2.0 → openapi_agent_ready-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openapi-agent-ready
-Version: 0.2.0
+Version: 0.3.0
 Summary: Audit any OpenAPI spec for AI-agent and MCP readiness, and generate an MCP server scaffold.
 Project-URL: Homepage, https://github.com/sfaisal/agent-ready
 Project-URL: Issues, https://github.com/sfaisal/agent-ready/issues
@@ -75,18 +75,17 @@ agent-ready https://example.com/openapi.yaml
 
 ```
 Generic Booking Platform API (v1.0)
-AI-readiness score: 58.4/100
-Endpoints: 4  Fails: 7  Warnings: 14
+AI-readiness score: 54.4/100
+Endpoints: 4  Fails: 6  Warnings: 12
 
 Category scores:
-  Description Clarity           37.5/100
-  Side Effects                  70.0/100
-  Error Responses               62.5/100
-  Auth Clarity                  50.0/100
-  Ambiguity                    100.0/100
-  Parameter Explanation         10.0/100
-  Usage Guidelines              50.0/100
-  Tool Surface                 100.0/100
+  Description Clarity            37.5/100
+  Side Effects                   70.0/100
+  Error Responses                62.5/100
+  Auth Clarity                   50.0/100
+  Ambiguity                     100.0/100
+  Parameter Explanation          16.7/100
+  Usage Guidelines               50.0/100
 ```
 
 ## Why this exists
@@ -112,9 +111,11 @@ directly onto the rubric:
 | **Frictionless authentication** | 4 (auth/scope clarity) |
 | **Structured error handling** | 3 (actionable errors) |
 
-Categories 2 (side effects) and 5 (ambiguity) were added during implementation
-— they turned out to matter as much as the original three, which is the usual
-reward for actually building the thing you wrote about.
+Categories 2 (side effects) and 5 (ambiguity) have no counterpart in the
+article — they were added during implementation, once it became clear that
+unsignalled write operations and confusable endpoint descriptions cause agent
+failures as often as the original three. Category 8 came later still, from
+OpenAI's function-calling guidance.
 
 The gap is measurable, and enormous. A 2026 study of 856 tools across 103 MCP
 servers found that **97.1% of tool descriptions contained at least one quality
@@ -128,7 +129,7 @@ agent failures in production.
 
 ```bash
 pip install openapi-agent-ready             # core
-pip install "openapi-agent-ready[server]"      # + MCP scaffold generation
+pip install "openapi-agent-ready[server]"    # + deps to RUN a generated scaffold
 ```
 
 From source:
@@ -156,6 +157,10 @@ agent-ready openapi.yaml --format json
 
 # Generate an MCP server for the endpoints that pass
 agent-ready openapi.yaml --generate-mcp server.py
+
+# Generating only writes a file — running it needs the server deps:
+pip install "openapi-agent-ready[server]"
+python server.py
 ```
 
 ### Use it as a CI gate
@@ -191,10 +196,8 @@ numbers:
 
 ```
 Stripe API (v2026-06-24.dahlia)
-AI-readiness score: 61.3/100
-Endpoints: 587  Fails: 393  Warnings: 2133
+AI-readiness score: 62.9/100
 
-Category scores:
   Description Clarity           68.3/100
   Side Effects                  64.7/100
   Error Responses              100.0/100
@@ -202,7 +205,6 @@ Category scores:
   Ambiguity                     50.0/100
   Parameter Explanation         43.0/100
   Usage Guidelines              51.2/100
-  Tool Surface                  49.6/100
 ```
 
 Two things worth drawing out.
@@ -211,11 +213,11 @@ Two things worth drawing out.
 in this tool, not in Stripe.** Stripe documents errors via OpenAPI's `default`
 response rather than enumerating explicit 4xx/5xx codes. Perfectly valid, and
 arguably cleaner. The check only looked for `4`/`5` prefixes, so it failed all
-587 endpoints. Fixed, regression-tested, and the reason this README says to run it against a
-real spec before trusting it.
+587 endpoints. Fixed, regression-tested, and the reason the README says to run
+this against a real spec before trusting it.
 
 **Stripe is widely and correctly regarded as agent-ready, yet its raw OpenAPI
-spec scores 61.3.** That isn't a contradiction — it's the whole point. Stripe's
+spec scores 62.9.** That isn't a contradiction — it's the whole point. Stripe's
 agent-readiness comes from the *Agent Toolkit* layered on top: curated tool
 definitions, an MCP server, managed OAuth. The raw spec is the input to that
 layer, not the layer itself. Which is exactly why this tool ships with

{openapi_agent_ready-0.2.0 → openapi_agent_ready-0.3.0}/README.md

@@ -20,18 +20,17 @@ agent-ready https://example.com/openapi.yaml
 
 ```
 Generic Booking Platform API (v1.0)
-AI-readiness score: 58.4/100
-Endpoints: 4  Fails: 7  Warnings: 14
+AI-readiness score: 54.4/100
+Endpoints: 4  Fails: 6  Warnings: 12
 
 Category scores:
-  Description Clarity           37.5/100
-  Side Effects                  70.0/100
-  Error Responses               62.5/100
-  Auth Clarity                  50.0/100
-  Ambiguity                    100.0/100
-  Parameter Explanation         10.0/100
-  Usage Guidelines              50.0/100
-  Tool Surface                 100.0/100
+  Description Clarity            37.5/100
+  Side Effects                   70.0/100
+  Error Responses                62.5/100
+  Auth Clarity                   50.0/100
+  Ambiguity                     100.0/100
+  Parameter Explanation          16.7/100
+  Usage Guidelines               50.0/100
 ```
 
 ## Why this exists
@@ -57,9 +56,11 @@ directly onto the rubric:
 | **Frictionless authentication** | 4 (auth/scope clarity) |
 | **Structured error handling** | 3 (actionable errors) |
 
-Categories 2 (side effects) and 5 (ambiguity) were added during implementation
-— they turned out to matter as much as the original three, which is the usual
-reward for actually building the thing you wrote about.
+Categories 2 (side effects) and 5 (ambiguity) have no counterpart in the
+article — they were added during implementation, once it became clear that
+unsignalled write operations and confusable endpoint descriptions cause agent
+failures as often as the original three. Category 8 came later still, from
+OpenAI's function-calling guidance.
 
 The gap is measurable, and enormous. A 2026 study of 856 tools across 103 MCP
 servers found that **97.1% of tool descriptions contained at least one quality
@@ -73,7 +74,7 @@ agent failures in production.
 
 ```bash
 pip install openapi-agent-ready             # core
-pip install "openapi-agent-ready[server]"      # + MCP scaffold generation
+pip install "openapi-agent-ready[server]"    # + deps to RUN a generated scaffold
 ```
 
 From source:
@@ -101,6 +102,10 @@ agent-ready openapi.yaml --format json
 
 # Generate an MCP server for the endpoints that pass
 agent-ready openapi.yaml --generate-mcp server.py
+
+# Generating only writes a file — running it needs the server deps:
+pip install "openapi-agent-ready[server]"
+python server.py
 ```
 
 ### Use it as a CI gate
@@ -136,10 +141,8 @@ numbers:
 
 ```
 Stripe API (v2026-06-24.dahlia)
-AI-readiness score: 61.3/100
-Endpoints: 587  Fails: 393  Warnings: 2133
+AI-readiness score: 62.9/100
 
-Category scores:
   Description Clarity           68.3/100
   Side Effects                  64.7/100
   Error Responses              100.0/100
@@ -147,7 +150,6 @@ Category scores:
   Ambiguity                     50.0/100
   Parameter Explanation         43.0/100
   Usage Guidelines              51.2/100
-  Tool Surface                  49.6/100
 ```
 
 Two things worth drawing out.
@@ -156,11 +158,11 @@ Two things worth drawing out.
 in this tool, not in Stripe.** Stripe documents errors via OpenAPI's `default`
 response rather than enumerating explicit 4xx/5xx codes. Perfectly valid, and
 arguably cleaner. The check only looked for `4`/`5` prefixes, so it failed all
-587 endpoints. Fixed, regression-tested, and the reason this README says to run it against a
-real spec before trusting it.
+587 endpoints. Fixed, regression-tested, and the reason the README says to run
+this against a real spec before trusting it.
 
 **Stripe is widely and correctly regarded as agent-ready, yet its raw OpenAPI
-spec scores 61.3.** That isn't a contradiction — it's the whole point. Stripe's
+spec scores 62.9.** That isn't a contradiction — it's the whole point. Stripe's
 agent-readiness comes from the *Agent Toolkit* layered on top: curated tool
 definitions, an MCP server, managed OAuth. The raw spec is the input to that
 layer, not the layer itself. Which is exactly why this tool ships with