api-mcp-compiler 0.2.0__tar.gz → 0.3.0__tar.gz

{api_mcp_compiler-0.2.0/src/api_mcp_compiler.egg-info → api_mcp_compiler-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-mcp-compiler
-Version: 0.2.0
+Version: 0.3.0
 Summary: Semantic and safe compilation of enterprise APIs into MCP tool surfaces
 Author-email: Subhadip Mitra <contact@subhadipmitra.com>
 License-Expression: Apache-2.0
@@ -87,8 +87,9 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 
 ## Contents
 
-- [Status](#status)
-- [Install and verify](#install-and-verify)
+- [What it does](#what-it-does)
+- [What is not demonstrated](#what-is-not-demonstrated)
+- [Install](#install)
 - [Try it](#try-it)
 - [How it works](#how-it-works)
 - [Design properties](#design-properties)
@@ -98,22 +99,32 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 - [Author](#author)
 - [Licence](#licence)
 
-## Status
+## What it does
 
-Working software, and recorded comparisons that did not find a difference.
+Ingests **OpenAPI 3.x, Swagger 2.0 and WSDL 1.1**, normalizes them into one provider-independent
+intermediate representation, plans a tool surface, derives a policy manifest, and emits a
+runnable MCP server for the approved part: over HTTP for OpenAPI, over SOAP envelopes for WSDL.
+The compiler itself binds to no MCP SDK, never calls a model, and never reaches the network.
 
-The compiler ingests OpenAPI 3.x, Swagger 2.0 and WSDL 1.1, produces an intermediate
-representation, plans a tool surface, derives a policy manifest, and generates a
-transport-independent surface that runs against a deterministic mock. An evaluation harness
-scores a surface against a task corpus using deterministic oracles over real service state,
-driven either by a replay of a recorded solution or by a model that sees only the goal and the
-tools. It emits a runnable MCP server for the approved part of a surface, over HTTP for
-OpenAPI and over SOAP envelopes for WSDL, while the compiler itself binds to no MCP SDK, never
-calls a model, and never reaches the network.
+This has been exercised on specifications and services written by other people, which is where
+the interesting defects live:
 
-The central question, whether a semantically planned surface beats one-tool-per-operation on
-task success, unsafe-action rate and cost, **has been measured four times and is still
-unanswered**.
+| Exercised against | Result |
+|---|---|
+| Spotify Web API, 40 operations (RestBench) | Parsed with no blocking ambiguities; least-privilege scopes derived from a real OAuth2 surface |
+| Swagger 2.0 Petstore, 20 operations | Parsed, 13 tools executable, runnable server emitted |
+| 40 WSDL documents (SAWSDL collection) | Parsed, with what cannot be translated recorded rather than approximated |
+| Two live public SOAP services | Real calls made and answered through generated servers |
+
+The governance is the part worth having. Every field carries provenance, judgement is proposed
+rather than applied, write and destructive tools are not emitted in executable form until a
+human approves them by class, and what the compiler cannot demonstrate it records as
+unresolved instead of assuming.
+
+## What is not demonstrated
+
+The design thesis, that a semantically planned surface beats one tool per operation on task
+success, unsafe-action rate and cost, **has been measured four times and is still unanswered**.
 
 Every comparison was pre-registered: the hypothesis, corpus, arms, model, success definition
 and significance threshold were fixed in a digested document before the run, and each run
@@ -121,17 +132,18 @@ records that digest. All returned inconclusive, and the nominal direction revers
 them. Nothing here should be read as evidence that the semantic surface performs better. It is
 an argued position that has so far survived no test capable of confirming it.
 
-What the runs did establish is mostly about the instrument. Several defects were found only by
-pointing the system at a specification and a task set written by other people: a parser that
-marked every optional argument required, generated schemas no client would load, a store in
-which a read mutated state and a bulk delete removed everything, and oracles that scored the
-route an annotator took rather than the outcome a goal asked for. Each is fixed, and the rules
-that would have prevented the last class now fail the build.
-
-The most distinctive claim, that operations should be composed into workflow tools, remains
-untested. The rule that proposes composites fires nowhere on the first benchmark API, and
-designing a better one after reading that benchmark's solution paths would fit the treatment
-to the test set. It needs a benchmark whose tasks have not been read here.
+The most distinctive claim, that operations should be composed into workflow tools, is
+untested rather than unsupported. The rule that proposes composites fires nowhere on the first
+benchmark API, and designing a better one after reading that benchmark's solution paths would
+fit the treatment to the test set. It needs a benchmark whose tasks have not been read here.
+
+What the runs did establish is mostly about the instrument, and it was worth the tokens.
+Several defects were found only by pointing the system at a specification and a task set
+written by other people: a parser that marked every optional argument required, generated
+schemas no client would load, a store in which a read mutated state and a bulk delete removed
+everything, and oracles that scored the route an annotator took rather than the outcome a goal
+asked for. Each is fixed, and the rules that would have prevented the last class now fail the
+build.
 
 ## Install
 

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

@@ -43,8 +43,9 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 
 ## Contents
 
-- [Status](#status)
-- [Install and verify](#install-and-verify)
+- [What it does](#what-it-does)
+- [What is not demonstrated](#what-is-not-demonstrated)
+- [Install](#install)
 - [Try it](#try-it)
 - [How it works](#how-it-works)
 - [Design properties](#design-properties)
@@ -54,22 +55,32 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 - [Author](#author)
 - [Licence](#licence)
 
-## Status
+## What it does
 
-Working software, and recorded comparisons that did not find a difference.
+Ingests **OpenAPI 3.x, Swagger 2.0 and WSDL 1.1**, normalizes them into one provider-independent
+intermediate representation, plans a tool surface, derives a policy manifest, and emits a
+runnable MCP server for the approved part: over HTTP for OpenAPI, over SOAP envelopes for WSDL.
+The compiler itself binds to no MCP SDK, never calls a model, and never reaches the network.
 
-The compiler ingests OpenAPI 3.x, Swagger 2.0 and WSDL 1.1, produces an intermediate
-representation, plans a tool surface, derives a policy manifest, and generates a
-transport-independent surface that runs against a deterministic mock. An evaluation harness
-scores a surface against a task corpus using deterministic oracles over real service state,
-driven either by a replay of a recorded solution or by a model that sees only the goal and the
-tools. It emits a runnable MCP server for the approved part of a surface, over HTTP for
-OpenAPI and over SOAP envelopes for WSDL, while the compiler itself binds to no MCP SDK, never
-calls a model, and never reaches the network.
+This has been exercised on specifications and services written by other people, which is where
+the interesting defects live:
 
-The central question, whether a semantically planned surface beats one-tool-per-operation on
-task success, unsafe-action rate and cost, **has been measured four times and is still
-unanswered**.
+| Exercised against | Result |
+|---|---|
+| Spotify Web API, 40 operations (RestBench) | Parsed with no blocking ambiguities; least-privilege scopes derived from a real OAuth2 surface |
+| Swagger 2.0 Petstore, 20 operations | Parsed, 13 tools executable, runnable server emitted |
+| 40 WSDL documents (SAWSDL collection) | Parsed, with what cannot be translated recorded rather than approximated |
+| Two live public SOAP services | Real calls made and answered through generated servers |
+
+The governance is the part worth having. Every field carries provenance, judgement is proposed
+rather than applied, write and destructive tools are not emitted in executable form until a
+human approves them by class, and what the compiler cannot demonstrate it records as
+unresolved instead of assuming.
+
+## What is not demonstrated
+
+The design thesis, that a semantically planned surface beats one tool per operation on task
+success, unsafe-action rate and cost, **has been measured four times and is still unanswered**.
 
 Every comparison was pre-registered: the hypothesis, corpus, arms, model, success definition
 and significance threshold were fixed in a digested document before the run, and each run
@@ -77,17 +88,18 @@ records that digest. All returned inconclusive, and the nominal direction revers
 them. Nothing here should be read as evidence that the semantic surface performs better. It is
 an argued position that has so far survived no test capable of confirming it.
 
-What the runs did establish is mostly about the instrument. Several defects were found only by
-pointing the system at a specification and a task set written by other people: a parser that
-marked every optional argument required, generated schemas no client would load, a store in
-which a read mutated state and a bulk delete removed everything, and oracles that scored the
-route an annotator took rather than the outcome a goal asked for. Each is fixed, and the rules
-that would have prevented the last class now fail the build.
-
-The most distinctive claim, that operations should be composed into workflow tools, remains
-untested. The rule that proposes composites fires nowhere on the first benchmark API, and
-designing a better one after reading that benchmark's solution paths would fit the treatment
-to the test set. It needs a benchmark whose tasks have not been read here.
+The most distinctive claim, that operations should be composed into workflow tools, is
+untested rather than unsupported. The rule that proposes composites fires nowhere on the first
+benchmark API, and designing a better one after reading that benchmark's solution paths would
+fit the treatment to the test set. It needs a benchmark whose tasks have not been read here.
+
+What the runs did establish is mostly about the instrument, and it was worth the tokens.
+Several defects were found only by pointing the system at a specification and a task set
+written by other people: a parser that marked every optional argument required, generated
+schemas no client would load, a store in which a read mutated state and a bulk delete removed
+everything, and oracles that scored the route an annotator took rather than the outcome a goal
+asked for. Each is fixed, and the rules that would have prevented the last class now fail the
+build.
 
 ## Install
 

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "api-mcp-compiler"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
-version = "0.2.0"
+version = "0.3.0"
 description = "Semantic and safe compilation of enterprise APIs into MCP tool surfaces"
 readme = "README.md"
 authors = [{name = "Subhadip Mitra", email = "contact@subhadipmitra.com"}]

api_mcp_compiler-0.3.0/src/api_mcp_compiler/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0}/src/api_mcp_compiler/codegen/mcp_server.py

@@ -33,6 +33,7 @@ from api_mcp_compiler.models import (
     EmissionStatus,
     ParameterLocation,
     PolicyManifest,
+    RetryPolicy,
     RiskClass,
     ToolDescriptor,
     ToolSurface,
@@ -108,6 +109,10 @@ def _tool_function(
     }
     policy = manifest.policy_for(tool.tool_id) if manifest else None
     confirm = policy is not None and policy.confirmation is not None
+    # Derived governance the server has to act on, not merely carry: a retry policy nothing
+    # reads is the same defect as a confirmation nobody expires.
+    retry = policy.retry.value if policy else RetryPolicy.NEVER.value
+    needs_key = policy.idempotency_key_required if policy else False
     confirmation_ttl = (
         policy.confirmation.token_ttl_seconds
         if policy is not None and policy.confirmation is not None
@@ -130,6 +135,8 @@ async def {tool.name}(arguments: dict[str, Any]) -> dict[str, Any]:
         bindings={_binding_map(tool)!r},
         requires_confirmation={confirm!r},
         confirmation_ttl_seconds={confirmation_ttl!r},
+        retry={retry!r},
+        idempotency_key_required={needs_key!r},
         destructive={destructive!r},
         max_output_bytes={max_bytes!r},
         redact_fields={redact!r},
@@ -152,9 +159,11 @@ registered them would undo the decision at the last step.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import os
 import time
+import uuid
 from typing import Any
 
 import httpx
@@ -185,6 +194,73 @@ def _digest(tool_name: str, arguments: dict[str, Any]) -> str:
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
 
 
+#: Attempts in total, not retries in addition. Three is a compromise: enough to ride out a
+#: single restart or rate-limit window, few enough that a wedged upstream is reported rather
+#: than hammered.
+_MAX_ATTEMPTS = 3
+
+#: Status codes worth sending again. Deliberately excludes 500: a server error may mean the
+#: effect happened and the response was lost, and repeating that is exactly what the retry
+#: policy exists to prevent. 429 and the gateway codes are unambiguous about not having acted.
+_RETRYABLE_STATUS = frozenset({{429, 502, 503, 504}})
+
+
+def _backoff(attempt: int, response: Any) -> float:
+    """How long to wait, preferring what the service asked for over what we guessed."""
+    if response is not None:
+        requested = getattr(response, "headers", {{}}) or {{}}
+        raw = requested.get("Retry-After") or requested.get("retry-after")
+        if raw:
+            try:
+                return max(0.0, float(raw))
+            except (TypeError, ValueError):
+                pass
+    return float(2**attempt) / 2
+
+
+async def _send(
+    client: Any,
+    method: str,
+    path: str,
+    *,
+    params: Any,
+    headers: dict[str, str],
+    json_body: Any,
+    retry: str,
+    idempotency_key: str | None,
+) -> Any:
+    """Make one request, repeating it only as far as the derived policy allows.
+
+    `never` means one attempt. It is the policy for an operation whose idempotency could not
+    be determined, where a repeat could duplicate an effect nobody asked for twice.
+
+    An idempotency key is generated per invocation and held across that invocation's retries,
+    which is the whole point: a fresh key per attempt would make every retry a new operation,
+    and a key derived from the arguments would make two deliberate identical calls collide.
+    """
+    attempts = 1 if retry == "never" else _MAX_ATTEMPTS
+    for attempt in range(attempts):
+        sending = dict(headers)
+        if idempotency_key is not None:
+            sending["Idempotency-Key"] = idempotency_key
+        last_error: Exception | None = None
+        try:
+            response = await client.request(
+                method, path, params=params, headers=sending or None, json=json_body
+            )
+        except Exception as error:  # transport failure: nothing was answered, so it is safe
+            last_error = error
+            if attempt + 1 >= attempts:
+                raise
+            await asyncio.sleep(_backoff(attempt, None))
+            continue
+        if response.status_code in _RETRYABLE_STATUS and attempt + 1 < attempts:
+            await asyncio.sleep(_backoff(attempt, response))
+            continue
+        return response
+    raise last_error if last_error is not None else RuntimeError("no attempt was made")
+
+
 def _credentials(tool_name: str) -> tuple[dict[str, str], dict[str, str]]:
     """Read the credentials this tool needs and place each where the service declared it.
 
@@ -263,6 +339,8 @@ async def _invoke(
     bindings: dict[str, tuple[str, str, str | None]],
     requires_confirmation: bool,
     confirmation_ttl_seconds: int,
+    retry: str,
+    idempotency_key_required: bool,
     destructive: bool,
     max_output_bytes: int | None,
     redact_fields: list[str],
@@ -316,6 +394,7 @@ async def _invoke(
     carried = dict(arguments)
     responses: list[Any] = []
     status_code = 0
+    idempotency_key = str(uuid.uuid4()) if idempotency_key_required else None
 
     async with httpx.AsyncClient(base_url=BASE_URL, timeout=30) as client:
         for position, (method, route, operation_id) in enumerate(steps):
@@ -352,8 +431,15 @@ async def _invoke(
             headers.update(authorization)
             query.update(authorized_query)
 
-            response = await client.request(
-                method, path, params=query or None, headers=headers or None, json=body
+            response = await _send(
+                client,
+                method,
+                path,
+                params=query or None,
+                headers=headers,
+                json_body=body,
+                retry=retry,
+                idempotency_key=idempotency_key,
             )
             status_code = response.status_code
             try:

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0}/src/api_mcp_compiler/codegen/soap_server.py

@@ -23,6 +23,7 @@ from api_mcp_compiler.models import (
     OperationIR,
     ParameterLocation,
     PolicyManifest,
+    RetryPolicy,
     RiskClass,
     ToolDescriptor,
     ToolSurface,
@@ -65,6 +66,7 @@ def _tool_function(ir: ApiSemanticIR, tool: ToolDescriptor, manifest: PolicyMani
         raise SoapEmissionError(f"{tool.name!r} carries no SOAP binding record")
     policy = manifest.policy_for(tool.tool_id) if manifest else None
     confirm = policy is not None and policy.confirmation is not None
+    retry = policy.retry.value if policy else RetryPolicy.NEVER.value
     confirmation_ttl = (
         policy.confirmation.token_ttl_seconds
         if policy is not None and policy.confirmation is not None
@@ -96,6 +98,7 @@ async def {tool.name}(arguments: dict[str, Any]) -> dict[str, Any]:
         schema=_SCHEMAS[{tool.name!r}],
         requires_confirmation={confirm!r},
         confirmation_ttl_seconds={confirmation_ttl!r},
+        retry={retry!r},
         destructive={(tool.risk is RiskClass.DESTRUCTIVE)!r},
         max_output_bytes={(policy.output.max_bytes if policy else None)!r},
         redact_fields={sorted(policy.output.redact_fields) if policy else []!r},
@@ -117,6 +120,7 @@ produces a request the service rejects while looking like it worked.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import os
 import time
@@ -153,6 +157,51 @@ def _digest(tool_name: str, arguments: dict[str, Any]) -> str:
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
 
 
+#: Attempts in total, not retries in addition.
+_MAX_ATTEMPTS = 3
+
+#: Transport-level codes worth sending again. A SOAP fault arrives as 500 and is an answer,
+#: not a failure to answer, so 500 is never retried here.
+_RETRYABLE_STATUS = frozenset({{429, 502, 503, 504}})
+
+
+def _backoff(attempt: int, response: Any) -> float:
+    """How long to wait, preferring what the service asked for over what we guessed."""
+    if response is not None:
+        requested = getattr(response, "headers", {{}}) or {{}}
+        raw = requested.get("Retry-After") or requested.get("retry-after")
+        if raw:
+            try:
+                return max(0.0, float(raw))
+            except (TypeError, ValueError):
+                pass
+    return float(2**attempt) / 2
+
+
+async def _post(client: Any, envelope: str, headers: dict[str, str], query: Any, retry: str) -> Any:
+    """Post the envelope, repeating it only as far as the derived policy allows.
+
+    No idempotency key is sent. WSDL declares nothing equivalent, so a key here would be a
+    header invented by this compiler that no service was built to honour, and a retry of a
+    non-idempotent SOAP operation is exactly what `never` is for.
+    """
+    for attempt in range(1 if retry == "never" else _MAX_ATTEMPTS):
+        try:
+            response = await client.post(
+                ENDPOINT, content=envelope.encode("utf-8"), headers=headers, params=query or None
+            )
+        except Exception:  # nothing was answered, so nothing was performed twice
+            if attempt + 1 >= (1 if retry == "never" else _MAX_ATTEMPTS):
+                raise
+            await asyncio.sleep(_backoff(attempt, None))
+            continue
+        if response.status_code in _RETRYABLE_STATUS and attempt + 1 < _MAX_ATTEMPTS:
+            await asyncio.sleep(_backoff(attempt, response))
+            continue
+        return response
+    raise RuntimeError("no attempt was made")
+
+
 def _credentials(tool_name: str) -> tuple[dict[str, str], dict[str, str]]:
     """Read the credentials this tool needs and place each where the service declared it.
 
@@ -252,6 +301,7 @@ async def _invoke(
     schema: dict[str, Any],
     requires_confirmation: bool,
     confirmation_ttl_seconds: int,
+    retry: str,
     destructive: bool,
     max_output_bytes: int | None,
     redact_fields: list[str],
@@ -330,12 +380,7 @@ async def _invoke(
     headers.update(authorization)
 
     async with httpx.AsyncClient(timeout=30) as client:
-        response = await client.post(
-            ENDPOINT,
-            content=envelope.encode("utf-8"),
-            headers=headers,
-            params=query or None,
-        )
+        response = await _post(client, envelope, headers, query, retry)
 
     try:
         root = ElementTree.fromstring(response.text)

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0/src/api_mcp_compiler.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-mcp-compiler
-Version: 0.2.0
+Version: 0.3.0
 Summary: Semantic and safe compilation of enterprise APIs into MCP tool surfaces
 Author-email: Subhadip Mitra <contact@subhadipmitra.com>
 License-Expression: Apache-2.0
@@ -87,8 +87,9 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 
 ## Contents
 
-- [Status](#status)
-- [Install and verify](#install-and-verify)
+- [What it does](#what-it-does)
+- [What is not demonstrated](#what-is-not-demonstrated)
+- [Install](#install)
 - [Try it](#try-it)
 - [How it works](#how-it-works)
 - [Design properties](#design-properties)
@@ -98,22 +99,32 @@ specification -> ingestion -> API Semantic IR -> planner -> tool plan
 - [Author](#author)
 - [Licence](#licence)
 
-## Status
+## What it does
 
-Working software, and recorded comparisons that did not find a difference.
+Ingests **OpenAPI 3.x, Swagger 2.0 and WSDL 1.1**, normalizes them into one provider-independent
+intermediate representation, plans a tool surface, derives a policy manifest, and emits a
+runnable MCP server for the approved part: over HTTP for OpenAPI, over SOAP envelopes for WSDL.
+The compiler itself binds to no MCP SDK, never calls a model, and never reaches the network.
 
-The compiler ingests OpenAPI 3.x, Swagger 2.0 and WSDL 1.1, produces an intermediate
-representation, plans a tool surface, derives a policy manifest, and generates a
-transport-independent surface that runs against a deterministic mock. An evaluation harness
-scores a surface against a task corpus using deterministic oracles over real service state,
-driven either by a replay of a recorded solution or by a model that sees only the goal and the
-tools. It emits a runnable MCP server for the approved part of a surface, over HTTP for
-OpenAPI and over SOAP envelopes for WSDL, while the compiler itself binds to no MCP SDK, never
-calls a model, and never reaches the network.
+This has been exercised on specifications and services written by other people, which is where
+the interesting defects live:
 
-The central question, whether a semantically planned surface beats one-tool-per-operation on
-task success, unsafe-action rate and cost, **has been measured four times and is still
-unanswered**.
+| Exercised against | Result |
+|---|---|
+| Spotify Web API, 40 operations (RestBench) | Parsed with no blocking ambiguities; least-privilege scopes derived from a real OAuth2 surface |
+| Swagger 2.0 Petstore, 20 operations | Parsed, 13 tools executable, runnable server emitted |
+| 40 WSDL documents (SAWSDL collection) | Parsed, with what cannot be translated recorded rather than approximated |
+| Two live public SOAP services | Real calls made and answered through generated servers |
+
+The governance is the part worth having. Every field carries provenance, judgement is proposed
+rather than applied, write and destructive tools are not emitted in executable form until a
+human approves them by class, and what the compiler cannot demonstrate it records as
+unresolved instead of assuming.
+
+## What is not demonstrated
+
+The design thesis, that a semantically planned surface beats one tool per operation on task
+success, unsafe-action rate and cost, **has been measured four times and is still unanswered**.
 
 Every comparison was pre-registered: the hypothesis, corpus, arms, model, success definition
 and significance threshold were fixed in a digested document before the run, and each run
@@ -121,17 +132,18 @@ records that digest. All returned inconclusive, and the nominal direction revers
 them. Nothing here should be read as evidence that the semantic surface performs better. It is
 an argued position that has so far survived no test capable of confirming it.
 
-What the runs did establish is mostly about the instrument. Several defects were found only by
-pointing the system at a specification and a task set written by other people: a parser that
-marked every optional argument required, generated schemas no client would load, a store in
-which a read mutated state and a bulk delete removed everything, and oracles that scored the
-route an annotator took rather than the outcome a goal asked for. Each is fixed, and the rules
-that would have prevented the last class now fail the build.
-
-The most distinctive claim, that operations should be composed into workflow tools, remains
-untested. The rule that proposes composites fires nowhere on the first benchmark API, and
-designing a better one after reading that benchmark's solution paths would fit the treatment
-to the test set. It needs a benchmark whose tasks have not been read here.
+The most distinctive claim, that operations should be composed into workflow tools, is
+untested rather than unsupported. The rule that proposes composites fires nowhere on the first
+benchmark API, and designing a better one after reading that benchmark's solution paths would
+fit the treatment to the test set. It needs a benchmark whose tasks have not been read here.
+
+What the runs did establish is mostly about the instrument, and it was worth the tokens.
+Several defects were found only by pointing the system at a specification and a task set
+written by other people: a parser that marked every optional argument required, generated
+schemas no client would load, a store in which a read mutated state and a bulk delete removed
+everything, and oracles that scored the route an annotator took rather than the outcome a goal
+asked for. Each is fixed, and the rules that would have prevented the last class now fail the
+build.
 
 ## Install
 

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0}/src/api_mcp_compiler.egg-info/SOURCES.txt

@@ -68,6 +68,7 @@ tests/test_determinism.py
 tests/test_evaluation.py
 tests/test_generated_confirmation.py
 tests/test_generated_credentials.py
+tests/test_generated_retry.py
 tests/test_mcp_server.py
 tests/test_mock_runtime.py
 tests/test_openapi.py

api_mcp_compiler-0.3.0/tests/test_generated_retry.py

@@ -0,0 +1,263 @@
+"""Tests that a generated server retries exactly as far as the derived policy allows.
+
+The manifest has always computed a retry policy and an idempotency requirement per tool, and
+the generated server read neither: a `never` policy retried nothing because nothing retried
+at all, which looks like compliance and is absence. This is the third value in a row that was
+derived, written into the artifact, and acted on by nobody, after the confirmation time to
+live and the credential placement.
+
+As with those, the tests here run the emitted module and watch what it does to the wire.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import types
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from api_mcp_compiler.codegen.mcp_server import emit_server
+from api_mcp_compiler.codegen.tools import generate_surface
+from api_mcp_compiler.ingest.openapi import parse_openapi
+from api_mcp_compiler.models import RiskClass
+from api_mcp_compiler.planning.approval import approve
+from api_mcp_compiler.planning.semantic import plan_semantic
+from api_mcp_compiler.policy.synthesis import synthesize_policy
+
+#: `put` is idempotent by RFC 9110 and `post` is not, which is what makes the two tools below
+#: land on different retry policies without anything in the test saying so.
+SERVICE = """openapi: 3.0.3
+info: {title: Retry Service, version: 1.0.0}
+servers: [{url: https://retry.example.invalid}]
+# A write with no declared authentication cannot be shown to be governed, so the emission
+# gate refuses it and there is nothing to test. That refusal is the subject of its own tests.
+security: [{guard: []}]
+paths:
+  /widgets/{id}:
+    put:
+      operationId: replaceWidget
+      summary: Replace a widget
+      parameters: [{in: path, name: id, required: true, schema: {type: string}}]
+      responses: {'200': {description: ok, content: {application/json: {schema: {type: object}}}}}
+  /widgets:
+    post:
+      operationId: createWidget
+      summary: Create a widget
+      responses: {'201': {description: made, content: {application/json: {schema: {type: object}}}}}
+components:
+  securitySchemes:
+    guard: {type: apiKey, in: header, name: X-Retry-Key}
+"""
+
+
+class _Reply:
+    def __init__(self, status: int, headers: dict[str, str] | None = None) -> None:
+        self.status_code = status
+        self.headers = headers or {}
+
+    def json(self) -> dict[str, str]:
+        return {"id": "w-1"}
+
+    @property
+    def text(self) -> str:
+        return "{}"
+
+
+class _Client:
+    """Answers with a scripted sequence, recording every attempt."""
+
+    def __init__(self, script: list[Any], seen: list[dict[str, Any]]) -> None:
+        self.script = script
+        self.seen = seen
+
+    async def __aenter__(self) -> _Client:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        return None
+
+    async def request(
+        self, method: str, path: str, params: Any = None, headers: Any = None, json: Any = None
+    ) -> Any:
+        self.seen.append({"method": method, "path": path, "headers": dict(headers or {})})
+        answer = self.script.pop(0) if self.script else _Reply(200)
+        if isinstance(answer, Exception):
+            raise answer
+        return answer
+
+
+def _load(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, script: list[Any]
+) -> tuple[dict[str, Any], list[dict[str, Any]], list[float]]:
+    """Emit the server, stub the SDK and the clock, and return what it did."""
+    spec = tmp_path / "service.yaml"
+    spec.write_text(SERVICE, encoding="utf-8")
+    ir = parse_openapi(spec)
+    plan = plan_semantic(ir)
+    overlay = approve(plan, overlay=None, risk=RiskClass.WRITE, group=None, names=[]).overlay
+    approved = plan_semantic(ir, overlay)
+    manifest = synthesize_policy(ir, approved)
+    source = emit_server(ir, generate_surface(ir, approved, manifest), manifest).source
+
+    seen: list[dict[str, Any]] = []
+    fastmcp = types.ModuleType("mcp.server.fastmcp")
+    fastmcp.FastMCP = lambda *_, **__: types.SimpleNamespace(  # type: ignore[attr-defined]
+        tool=lambda **_kw: (lambda function: function),
+        resource=lambda *_a, **_kw: (lambda function: function),
+    )
+    server = types.ModuleType("mcp.server")
+    server.fastmcp = fastmcp  # type: ignore[attr-defined]
+    package = types.ModuleType("mcp")
+    package.server = server  # type: ignore[attr-defined]
+    httpx = types.ModuleType("httpx")
+    httpx.AsyncClient = lambda **_: _Client(script, seen)  # type: ignore[attr-defined]
+    for name, module in {
+        "mcp": package, "mcp.server": server, "mcp.server.fastmcp": fastmcp, "httpx": httpx
+    }.items():
+        monkeypatch.setitem(sys.modules, name, module)
+
+    namespace: dict[str, Any] = {"__name__": "generated_server"}
+    exec(compile(source, "<generated server>", "exec"), namespace)
+
+    # Waiting is the one part that must not actually happen in a test, but how long it would
+    # have waited is worth asserting, so it is recorded rather than discarded.
+    waits: list[float] = []
+
+    async def _instant(delay: float) -> None:
+        waits.append(delay)
+
+    namespace["asyncio"] = types.SimpleNamespace(sleep=_instant)
+    return namespace, seen, waits
+
+
+def _replace(namespace: dict[str, Any]) -> Any:
+    """The idempotent tool, whose derived policy is `safe`."""
+    return asyncio.run(namespace["replace_widget"]({"id": "w-1"}))
+
+
+def _create(namespace: dict[str, Any]) -> Any:
+    """The non-idempotent tool, whose derived policy needs an idempotency key."""
+    return asyncio.run(namespace["create_widget"]({}))
+
+
+def test_a_retryable_status_is_sent_again(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    namespace, seen, waits = _load(tmp_path, monkeypatch, [_Reply(503), _Reply(200)])
+
+    _replace(namespace)
+
+    assert len(seen) == 2
+    assert waits == [0.5]
+
+
+def test_a_client_error_is_not_sent_again(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Repeating a request the service rejected changes nothing except the load."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(404), _Reply(200)])
+
+    _replace(namespace)
+
+    assert len(seen) == 1
+
+
+def test_a_server_error_is_not_sent_again(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """500 may mean the effect happened and the answer was lost, which a retry duplicates."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(500), _Reply(200)])
+
+    _replace(namespace)
+
+    assert len(seen) == 1
+
+
+def test_attempts_are_bounded(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """A wedged upstream is reported, not hammered."""
+    namespace, seen, waits = _load(
+        tmp_path, monkeypatch, [_Reply(503), _Reply(503), _Reply(503), _Reply(200)]
+    )
+
+    _replace(namespace)
+
+    assert len(seen) == 3
+    assert waits == [0.5, 1.0]
+
+
+def test_the_service_decides_how_long_to_wait(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A rate limit that names its window is more useful than any backoff curve."""
+    namespace, _, waits = _load(
+        tmp_path, monkeypatch, [_Reply(429, {"Retry-After": "7"}), _Reply(200)]
+    )
+
+    _replace(namespace)
+
+    assert waits == [7.0]
+
+
+def test_a_transport_failure_is_retried(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Nothing was answered, so nothing was performed twice."""
+    namespace, seen, _ = _load(
+        tmp_path, monkeypatch, [ConnectionError("reset"), _Reply(200)]
+    )
+
+    _replace(namespace)
+
+    assert len(seen) == 2
+
+
+def test_a_non_idempotent_tool_carries_a_key_that_survives_the_retry(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A fresh key per attempt would make every retry a new operation."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(503), _Reply(201)])
+
+    _create(namespace)
+
+    keys = [attempt["headers"].get("Idempotency-Key") for attempt in seen]
+    assert len(seen) == 2
+    assert keys[0] and keys[0] == keys[1]
+
+
+def test_two_invocations_do_not_share_a_key(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A key derived from the arguments would make two deliberate identical calls collide."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(201), _Reply(201)])
+
+    _create(namespace)
+    _create(namespace)
+
+    first, second = (attempt["headers"]["Idempotency-Key"] for attempt in seen)
+    assert first != second
+
+
+def test_an_idempotent_tool_sends_no_key(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The header is for the case that needs it, not decoration on every request."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(200)])
+
+    _replace(namespace)
+
+    assert "Idempotency-Key" not in seen[0]["headers"]
+
+
+def test_invalid_arguments_reach_no_request_at_all(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Validating after calling has already had the effect it was checking for."""
+    namespace, seen, _ = _load(tmp_path, monkeypatch, [_Reply(200)])
+
+    outcome = asyncio.run(namespace["replace_widget"]({"id": 17}))
+
+    assert outcome["error"] == "invalid_arguments"
+    assert seen == []

{api_mcp_compiler-0.2.0 → api_mcp_compiler-0.3.0}/tests/test_mcp_server.py

@@ -94,11 +94,16 @@ def test_no_credential_is_written_into_the_generated_file() -> None:
 
 
 def test_arguments_are_validated_before_the_call_is_made() -> None:
-    """A surface that validates after calling has already had the effect it was checking."""
+    """A surface that validates after calling has already had the effect it was checking.
+
+    Asserted on the ordering inside `_invoke`, which is where the decision lives. The request
+    itself is made from a helper defined further up the file, so comparing raw positions
+    would compare the wrong two things. `test_generated_retry.py` checks the same property
+    by running the module and finding no request was made at all.
+    """
     _, _, emitted = _emit()
-    validate_at = emitted.source.index("iter_errors(arguments)")
-    call_at = emitted.source.index("await client.request(")
-    assert validate_at < call_at
+    body = emitted.source[emitted.source.index("async def _invoke("):]
+    assert body.index("iter_errors(arguments)") < body.index("await _send(")
 
 
 def test_a_surface_with_nothing_executable_refuses_to_emit() -> None:

api_mcp_compiler-0.2.0/src/api_mcp_compiler/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"