From 6b4cba451295502fa828d2bc4a69dbdc3bdf046a Mon Sep 17 00:00:00 2001 From: "Marco A. Sanz" Date: Thu, 5 Nov 2026 22:14:25 +0100 Subject: [PATCH] feat: --body-variables and always-written environment (SA-3276) - New --body-variables option: tool and prompt argument values are moved out of the request bodies into environment variables ({{_}}, {{prompt__}}). Strings are referenced inside quotes and stored JSON-escaped; other types are referenced unquoted and stored as JSON literals so the server keeps receiving the right JSON type. Wrong-type negative tests keep their literal value. - The Postman environment file is now always generated (next to the collection by default) and always contains baseUrl; --environment-out only changes its path. - Test scripts resolve variables before reading the JSON-RPC request id. - Docs (README, ARCHITECTURE, CHANGELOG), tests (unit, CLI, newman/Postman CLI end-to-end with environment), version 0.2.0. Co-Authored-By: Claude Opus 5.5 --- ARCHITECTURE.md | 29 ++++++- CHANGELOG.md | 24 ++++++ README.md | 78 ++++++++++++++++-- examples/demo.postman_collection.json | 76 +++++++++--------- pyproject.toml | 2 +- src/mcp2rest2postman/__init__.py | 2 +- src/mcp2rest2postman/cli.py | 38 +++++++-- src/mcp2rest2postman/postman.py | 111 +++++++++++++++++++++++--- src/mcp2rest2postman/scripts.py | 2 +- tests/test_cli.py | 42 +++++++++- tests/test_e2e_postman.py | 20 ++++- tests/test_postman.py | 46 ++++++++++- 12 files changed, 398 insertions(+), 72 deletions(-) create mode 100644 CHANGELOG.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index d2abe0c..4c8772a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -40,7 +40,7 @@ without a running server. | `schema_values.py` | JSON Schema helpers. `sample_value` / `sample_object` create valid samples. They handle local `$ref`, `allOf` (merged), `anyOf` and `oneOf` (first branch that isn't null), `const`, `default`, `examples`, `enum`, `format`, string length, `pattern` (tries known candidates), numeric bounds and `multipleOf`, and array sizes. `wrong_type_value` picks a value of a type the schema doesn't accept. `sanitize_for_ajv` makes schemas compile in Postman's sandbox. `required_and_optional` splits the properties of an object. | | `mcp_schemas.py` | Draft-07 schemas for MCP results (`InitializeResult`, `CallToolResult` and others) and for JSON-RPC errors. They're strict on the fields the spec requires and allow anything else, so servers on newer protocol revisions still pass. | | `scripts.py` | JavaScript templates for the Postman test scripts. | -| `postman.py` | `CollectionBuilder` creates the folders, requests, variables and environment from a snapshot and `GeneratorOptions`. | +| `postman.py` | `CollectionBuilder` creates the folders, requests and variables from a snapshot and `GeneratorOptions`. With `body_variables`, it records each argument value it moves out of a body. `build_collection_and_environment` returns the collection and the matching environment (`baseUrl`, header variables, body variables). | ## Key design decisions @@ -91,6 +91,29 @@ those. `sanitize_for_ajv` removes `$schema` and `$id` and drops `format` values that Ajv doesn't know. It leaves *property names* alone, even a property called `$schema`. +### The environment file and body variables +`generate` always writes an environment next to the collection. It holds +`baseUrl`, one variable per custom header and, with `--body-variables`, one +variable per argument value. `baseUrl` also stays as a collection variable as +a fallback, but Postman gives environment values precedence. + +With `body_variables`, `CollectionBuilder._vars()` replaces each top-level +argument with a `BodyVar` placeholder named `_` or +`prompt__`, and `_var()` records the value. The same name with +the same value is reused. A different value under an existing name gets a +numeric suffix, so one variable never has two meanings. `_raw_body()` +serializes the payload with sentinel strings and then rewrites them: + +* string values become `"{{name}}"`. The environment stores the JSON-escaped + text without the surrounding quotes. +* any other value becomes an unquoted `{{name}}`. The environment stores its + JSON literal, so after substitution the server gets the original JSON type. + +Wrong-type requests pass their key as `literal`, so the deliberately invalid +value stays in the body. Because the raw body is only valid JSON after +substitution, the test helper reads the request `id` from +`pm.variables.replaceIn(pm.request.body.raw)`. + ### Positive vs. negative test semantics | Request kind | Passes when | |---|---| @@ -117,7 +140,7 @@ type. An unconstrained `{}` accepts any value. | Layer | File | What it covers | |---|---|---| | Unit | `tests/test_schema_values.py` | Sample and wrong-type generation, `$ref` and combinators, Ajv sanitizing | -| Unit | `tests/test_postman.py` | Collection structure, variants for required and optional attributes, options, headers and secrets, determinism | +| Unit | `tests/test_postman.py` | Collection structure, variants for required and optional attributes, options, headers and secrets, body variables and environment, determinism | | Integration | `tests/test_client.py` | HTTP (JSON and SSE) and stdio transports against `examples/demo_server.py`, snapshot round trip | | Integration | `tests/test_cli.py` | CLI flags, output files, exit codes | -| End to end | `tests/test_e2e_postman.py` | Runs generated collections with **newman** or the **Postman CLI** against the demo server. All assertions must pass, and drift must be detected. Skipped when neither runner is installed. | +| End to end | `tests/test_e2e_postman.py` | Runs generated collections with **newman** or the **Postman CLI** against the demo server. All assertions must pass, including with `--body-variables` and its environment, and drift must be detected. Skipped when neither runner is installed. | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0b535d5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +## 0.2.0 + +### Added +- `--body-variables`: tool and prompt argument values move from request + bodies into environment variables (`{{_}}`, + `{{prompt__}}`). Non-string values are inserted without quotes, + so their JSON type is kept. (SA-3276) +- `--config` / `--server`: read the server and its auth from an + `mcp-config.json`. + +### Changed +- The Postman environment file is always written, next to the collection by + default, and always contains `baseUrl`. `--environment-out` only sets its + path. (SA-3276) +- Test scripts resolve variables before reading the JSON-RPC request id. +- The client sends its own `User-Agent`. + +## 0.1.0 + +- First release: MCP (Streamable HTTP or stdio) to Postman collection, with + tests for required and optional attributes, response schema validation and + drift checks. (SA-3275) diff --git a/README.md b/README.md index 06f702b..072b0e6 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ MCP server ──(initialize, tools/list, resources/list, prompts/list)──▶ * **Validates responses** with JSON Schema: `InitializeResult`, `CallToolResult`, `structuredContent` against the tool's `outputSchema`, `ReadResourceResult`, `GetPromptResult`, and the JSON-RPC error shape. +* **Always writes a Postman environment** next to the collection, with + `baseUrl` and the header variables. With `--body-variables`, the tool and + prompt argument values move from the request bodies into that environment. * **Detects drift.** `tools/list` and `prompts/list` fail when a tool or prompt disappears or its input schema changes after the collection was generated. * Has no runtime dependencies (Python ≥ 3.9 standard library only). @@ -47,13 +50,12 @@ Try it with the bundled demo server: python examples/demo_server.py --http --port 8765 & mcp2rest2postman inspect --url http://localhost:8765/mcp -mcp2rest2postman generate --url http://localhost:8765/mcp \ - -o demo.postman_collection.json \ - --environment-out demo.postman_environment.json +mcp2rest2postman generate --url http://localhost:8765/mcp -o demo.postman_collection.json +# -> demo.postman_collection.json + demo.postman_environment.json # run it (any of these) -postman collection run demo.postman_collection.json -newman run demo.postman_collection.json +postman collection run demo.postman_collection.json -e demo.postman_environment.json +newman run demo.postman_collection.json -e demo.postman_environment.json ``` Output of `inspect`: @@ -98,7 +100,8 @@ mcp2rest2postman generate (--url URL | --stdio COMMAND | --config FILE | --from- | `-H 'Name: value'` | Extra HTTP header (repeatable). Typical use: `-H 'Authorization: Bearer …'`. Overrides a config header with the same name | | `--env KEY=VALUE` | Environment variable for the stdio server (repeatable). Overrides the config `env` | | `-o FILE` | Collection output file (`-` for stdout). The default is `.postman_collection.json` | -| `--environment-out FILE` | Also write a Postman environment with `baseUrl` and the header variables | +| `--environment-out FILE` | Path of the Postman environment, which is always written. It holds `baseUrl`, the header variables and, with `--body-variables`, the argument values. The default is the collection path with `.postman_environment.json` (`.postman_environment.json` when `-o -`) | +| `--body-variables` | Put tool and prompt argument values in environment variables (`{{tool_arg}}`) instead of writing them into the request bodies. See [Body variables](#body-variables) | | `--snapshot-out FILE` | Also save the discovered server snapshot | | `--base-url URL` | Value of `{{baseUrl}}`. The default is `--url`, or `http://localhost:3000/mcp` for stdio | | `--name NAME` | Collection name | @@ -140,6 +143,65 @@ it in a values file: mcp2rest2postman generate --url … --values examples/values.json ``` +### Body variables + +By default, argument values are written straight into each request body. With +`--body-variables`, every top-level tool argument becomes the variable +`{{_}}`, and every prompt argument becomes +`{{prompt__}}`. The values go into the environment file, so +you can change test data without regenerating the collection or editing +requests. + +```bash +mcp2rest2postman generate --url http://localhost:8765/mcp --body-variables \ + --values examples/values.json -o demo.postman_collection.json +``` + +Request body: + +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "add", + "arguments": { + "a": {{add_a}}, + "b": {{add_b}} + } + } +} +``` + +Environment (`demo.postman_environment.json`): + +| key | value | +|---|---| +| `baseUrl` | `http://localhost:8765/mcp` | +| `add_a` | `40` | +| `add_b` | `2` | +| `greet_name` | `Ada` | +| `search_items_filters` | `{"inStock": true}` | +| `prompt_summarize_text` | `example-text` | + +How values are stored: + +* **Strings** are used inside quotes (`"{{greet_name}}"`). The environment + holds the text with JSON escaping, so `"` becomes `\"`. +* **Numbers, booleans, null, arrays and objects** are used without quotes + (`{{add_a}}`) and stored as JSON literals (`40`, `true`, `["a"]`, + `{"inStock": true}`), so the server still receives the right JSON type. +* The valid variants of a tool (all attributes, required only, one per + optional attribute) and its *missing required* requests share the same + variables. *Wrong type* requests keep their deliberately invalid value as a + literal. +* `--values` sets the initial values in the environment. + +Raw bodies containing unquoted `{{…}}` aren't valid JSON until Postman +substitutes the variables, so **always run the collection with its +environment** (`-e`). + ### MCP config files Reuse the `mcp-config.json` you already give to Claude Desktop, Claude Code @@ -214,10 +276,10 @@ To store the values in the collection and environment files, use ```bash # once: discover and store the contract mcp2rest2postman generate --url $MCP_URL --snapshot-out mcp.snapshot.json -o mcp.postman_collection.json -git add mcp.snapshot.json mcp.postman_collection.json +git add mcp.snapshot.json mcp.postman_collection.json mcp.postman_environment.json # in CI: run the collection against the deployed server -postman collection run mcp.postman_collection.json --env-var "baseUrl=$MCP_URL" +postman collection run mcp.postman_collection.json -e mcp.postman_environment.json --env-var "baseUrl=$MCP_URL" ``` If someone removes a tool or changes its `inputSchema`, the `tools/list` diff --git a/examples/demo.postman_collection.json b/examples/demo.postman_collection.json index 919ba29..3cc5cee 100644 --- a/examples/demo.postman_collection.json +++ b/examples/demo.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "8681b34d-364a-59d4-8b0f-1dd27614321c", "name": "Demo MCP Server (MCP)", - "description": "Generated by mcp2rest2postman 0.1.0 from **Demo MCP Server** (protocol `2025-06-18`).\n\nRun the folders in order: `00 Lifecycle` opens the session used by the rest.\n\nServer instructions:\n\nDemo server for mcp2rest2postman.", + "description": "Generated by mcp2rest2postman 0.2.0 from **Demo MCP Server** (protocol `2025-06-18`).\n\nRun the folders in order: `00 Lifecycle` opens the session used by the rest.\n\nServer instructions:\n\nDemo server for mcp2rest2postman.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ @@ -31,7 +31,7 @@ }, "body": { "mode": "raw", - "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2025-06-18\",\n \"capabilities\": {},\n \"clientInfo\": {\n \"name\": \"mcp2rest2postman\",\n \"version\": \"0.1.0\"\n }\n }\n}", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2025-06-18\",\n \"capabilities\": {},\n \"clientInfo\": {\n \"name\": \"mcp2rest2postman\",\n \"version\": \"0.2.0\"\n }\n }\n}", "options": { "raw": { "language": "json" @@ -66,7 +66,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -221,7 +221,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -316,7 +316,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -427,7 +427,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -526,7 +526,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -617,7 +617,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -708,7 +708,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -799,7 +799,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -896,7 +896,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -991,7 +991,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1086,7 +1086,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1181,7 +1181,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1276,7 +1276,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1367,7 +1367,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1458,7 +1458,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1549,7 +1549,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1646,7 +1646,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1741,7 +1741,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1836,7 +1836,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -1931,7 +1931,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2026,7 +2026,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2121,7 +2121,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2212,7 +2212,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2303,7 +2303,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2394,7 +2394,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2485,7 +2485,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2579,7 +2579,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2675,7 +2675,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2773,7 +2773,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2872,7 +2872,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -2964,7 +2964,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -3059,7 +3059,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -3167,7 +3167,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -3255,7 +3255,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -3343,7 +3343,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", @@ -3439,7 +3439,7 @@ " }", " }", " let requestId;", - " try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; }", + " try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; }", " const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m])));", " const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m);", " const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null;", diff --git a/pyproject.toml b/pyproject.toml index d69e1c2..ff6049d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "mcp2rest2postman" -version = "0.1.0" +version = "0.2.0" description = "Convert an MCP server (Streamable HTTP or stdio) into a Postman collection with contract, required and optional attribute tests." readme = "README.md" license = "Apache-2.0" diff --git a/src/mcp2rest2postman/__init__.py b/src/mcp2rest2postman/__init__.py index d43d817..2e97d52 100644 --- a/src/mcp2rest2postman/__init__.py +++ b/src/mcp2rest2postman/__init__.py @@ -1,5 +1,5 @@ """mcp2rest2postman: turn an MCP server into a tested Postman collection.""" -__version__ = "0.1.0" +__version__ = "0.2.0" __all__ = ["__version__"] diff --git a/src/mcp2rest2postman/cli.py b/src/mcp2rest2postman/cli.py index 1d8b5d2..f8399c8 100644 --- a/src/mcp2rest2postman/cli.py +++ b/src/mcp2rest2postman/cli.py @@ -14,7 +14,7 @@ from .client import DEFAULT_PROTOCOL_VERSION, HttpTransport, MCPError, StdioTransport, Transport from .config import load_server from .discovery import ServerSnapshot, discover -from .postman import GeneratorOptions, build_collection, build_environment +from .postman import GeneratorOptions, build_collection_and_environment from .schema_values import required_and_optional DEFAULT_BASE_URL = "http://localhost:3000/mcp" @@ -104,7 +104,13 @@ def build_parser() -> argparse.ArgumentParser: _add_source_args(gen, allow_snapshot=True) out = gen.add_argument_group("output") out.add_argument("-o", "--output", help="collection file ('-' for stdout). Default: .postman_collection.json") - out.add_argument("--environment-out", metavar="FILE", help="also write a Postman environment with baseUrl and headers") + out.add_argument( + "--environment-out", + metavar="FILE", + help="Postman environment file (always written) with baseUrl, header variables and, with " + "--body-variables, the argument values. Default: next to the collection, " + ".postman_environment.json", + ) out.add_argument("--snapshot-out", metavar="FILE", help="also save the discovered server snapshot (JSON)") out.add_argument("--name", help="collection name (default: ' (MCP)')") out.add_argument( @@ -118,6 +124,12 @@ def build_parser() -> argparse.ArgumentParser: help="store -H values in the collection (by default only empty variables are created; " "beware of committing secrets)", ) + out.add_argument( + "--body-variables", + action="store_true", + help="put tool/prompt argument values in environment variables ({{tool_arg}}) instead of " + "hard-coding them in the request bodies", + ) sel = gen.add_argument_group("content") sel.add_argument("--include-tool", action="append", default=[], metavar="GLOB", help="only these tools (repeatable)") sel.add_argument("--exclude-tool", action="append", default=[], metavar="GLOB", help="skip these tools (repeatable)") @@ -242,22 +254,38 @@ def cmd_generate(args: argparse.Namespace) -> int: include_resources=not args.no_resources, include_prompts=not args.no_prompts, teardown=not args.no_teardown, + body_variables=args.body_variables, + ) + collection, environment = build_collection_and_environment( + snapshot, options, f"{snapshot.server_name} (MCP)" ) - collection = build_collection(snapshot, options) output = args.output or f"{_slug(snapshot.server_name)}.postman_collection.json" + env_output = args.environment_out or environment_path(output, snapshot.server_name) _write_json(output, collection) + _write_json(env_output, environment) if args.snapshot_out: snapshot.save(args.snapshot_out) - if args.environment_out: - _write_json(args.environment_out, build_environment(options, f"{snapshot.server_name} (MCP)")) requests = _count_requests(collection["item"]) if output != "-": log(f"Wrote {output} ({requests} requests)") + if env_output != "-": + log(f"Wrote {env_output} ({len(environment['values'])} variables)") for warning in snapshot.warnings: log(f"warning: {warning}") return 0 +def environment_path(collection_path: str, server_name: str) -> str: + """Default environment file, next to the collection.""" + if collection_path == "-": + return f"{_slug(server_name)}.postman_environment.json" + path = Path(collection_path) + for suffix in (".postman_collection.json", ".json"): + if path.name.endswith(suffix): + return str(path.with_name(path.name[: -len(suffix)] + ".postman_environment.json")) + return str(path.with_name(path.name + ".postman_environment.json")) + + def _count_requests(items: List[Dict[str, Any]]) -> int: return sum(_count_requests(i["item"]) if "item" in i else 1 for i in items) diff --git a/src/mcp2rest2postman/postman.py b/src/mcp2rest2postman/postman.py index ca71492..6dac719 100644 --- a/src/mcp2rest2postman/postman.py +++ b/src/mcp2rest2postman/postman.py @@ -7,7 +7,7 @@ import re import uuid from dataclasses import dataclass, field -from typing import Any, Dict, List, Mapping, Optional +from typing import Any, Dict, List, Mapping, Optional, Tuple from . import __version__, scripts from . import mcp_schemas as ms @@ -46,6 +46,40 @@ class GeneratorOptions: include_resources: bool = True include_prompts: bool = True teardown: bool = True + #: Move tool / prompt argument values out of the request bodies into + #: ``{{tool_arg}}`` environment variables. + body_variables: bool = False + + +class BodyVar: + """Placeholder for an argument value that lives in an environment variable.""" + + __slots__ = ("name",) + + def __init__(self, name: str): + self.name = name + + +_SENTINEL = "__mcp2rest2postman_var__" +_SENTINEL_RE = re.compile(r'"' + _SENTINEL + r'([A-Za-z0-9_]+)(:s)?"') + + +def variable_name(*parts: str) -> str: + """``("create_user", "e-mail")`` -> ``create_user_e_mail``.""" + joined = "_".join(re.sub(r"[^A-Za-z0-9]+", "_", str(p)).strip("_") for p in parts if str(p)) + return joined or "value" + + +def environment_value(value: Any) -> str: + """Text stored in the environment so that substitution yields valid JSON. + + Strings are used inside quotes in the body (``"{{var}}"``), so only their + JSON escaping is stored; any other type is inserted unquoted + (``{{var}}``) and stored as its JSON literal (``42``, ``true``, ``["a"]``). + """ + if isinstance(value, str): + return json.dumps(value, ensure_ascii=False)[1:-1] + return json.dumps(value, ensure_ascii=False) def header_variable(name: str) -> str: @@ -58,6 +92,8 @@ def __init__(self, snapshot: ServerSnapshot, options: Optional[GeneratorOptions] self.snapshot = snapshot self.options = options or GeneratorOptions() self._next_id = 1 + #: Environment variables created for request bodies: name -> value. + self.body_variables: Dict[str, Any] = {} # ------------------------------------------------------------------ utils def _id(self) -> int: @@ -77,6 +113,43 @@ def _headers(self, with_session: bool = True) -> List[Dict[str, Any]]: headers.append({"key": name, "value": "{{" + header_variable(name) + "}}"}) return headers + def _var(self, value: Any, *parts: str) -> BodyVar: + """Register *value* under a variable named after *parts* and return a placeholder. + + The same name always maps to the same value; a different value for an + existing name gets a numeric suffix. + """ + base = variable_name(*parts) + name, n = base, 2 + while name in self.body_variables and self.body_variables[name] != value: + name, n = f"{base}_{n}", n + 1 + self.body_variables[name] = value + return BodyVar(name) + + def _vars(self, arguments: Dict[str, Any], prefix: List[str], literal: Any = ()) -> Dict[str, Any]: + """Replace argument values by variables (keys in *literal* keep their value).""" + if not self.options.body_variables: + return arguments + return {k: (v if k in literal else self._var(v, *prefix, k)) for k, v in arguments.items()} + + def _raw_body(self, payload: Dict[str, Any]) -> str: + values = self.body_variables + + def encode(obj: Any) -> Any: + if isinstance(obj, BodyVar): + suffix = ":s" if isinstance(values[obj.name], str) else "" + return f"{_SENTINEL}{obj.name}{suffix}" + if isinstance(obj, dict): + return {k: encode(v) for k, v in obj.items()} + if isinstance(obj, list): + return [encode(v) for v in obj] + return obj + + raw = json.dumps(encode(payload), indent=2, ensure_ascii=False) + return _SENTINEL_RE.sub( + lambda m: '"{{' + m.group(1) + '}}"' if m.group(2) else "{{" + m.group(1) + "}}", raw + ) + def _url(self) -> Dict[str, Any]: return {"raw": "{{baseUrl}}", "host": ["{{baseUrl}}"]} @@ -104,7 +177,7 @@ def _request( "url": self._url(), "body": { "mode": "raw", - "raw": json.dumps(payload, indent=2, ensure_ascii=False), + "raw": self._raw_body(payload), "options": {"raw": {"language": "json"}}, }, }, @@ -227,11 +300,13 @@ def args(include_optional: bool, only: Optional[List[str]] = None) -> Dict[str, built[key] = value return built - def call(label: str, arguments: Dict[str, Any], tests: List[str], doc: str) -> Dict[str, Any]: + def call( + label: str, arguments: Dict[str, Any], tests: List[str], doc: str, literal: Any = () + ) -> Dict[str, Any]: return self._request( f"{name} - {label}", "tools/call", - {"name": name, "arguments": arguments}, + {"name": name, "arguments": self._vars(arguments, [name], literal)}, tests, doc, ) @@ -295,6 +370,7 @@ def call(label: str, arguments: Dict[str, Any], tests: List[str], doc: str) -> D f"wrong type for '{key}' ({why})", ms.CALL_TOOL_RESULT, ms.JSONRPC_ERROR ), f"`{key}` receives {why}: the server must reject the call.", + literal={key}, ) ) description = self._tool_description(tool, required, optional, props) @@ -399,12 +475,13 @@ def prompts(self) -> Optional[Dict[str, Any]]: required = [a["name"] for a in arguments if a.get("required")] optional = [a["name"] for a in arguments if not a.get("required")] all_args = {a: f"example-{a}" for a in required + optional} + pv = ["prompt", str(pname)] ok = scripts._lines(scripts.HELPERS, scripts.jsonrpc_success(ms.GET_PROMPT_RESULT, "GetPromptResult")) items.append( self._request( f"prompts/get {pname} - all arguments", "prompts/get", - {"name": pname, "arguments": all_args}, + {"name": pname, "arguments": self._vars(all_args, pv)}, ok, str(prompt.get("description") or ""), ) @@ -414,7 +491,7 @@ def prompts(self) -> Optional[Dict[str, Any]]: self._request( f"prompts/get {pname} - required arguments only", "prompts/get", - {"name": pname, "arguments": {a: all_args[a] for a in required}}, + {"name": pname, "arguments": self._vars({a: all_args[a] for a in required}, pv)}, ok, ) ) @@ -424,7 +501,7 @@ def prompts(self) -> Optional[Dict[str, Any]]: self._request( f"prompts/get {pname} - missing required '{arg}' -> error", "prompts/get", - {"name": pname, "arguments": {k: v for k, v in all_args.items() if k != arg}}, + {"name": pname, "arguments": self._vars({k: v for k, v in all_args.items() if k != arg}, pv)}, scripts.rejection_tests( f"missing required argument '{arg}'", ms.GET_PROMPT_RESULT, @@ -522,12 +599,24 @@ def build(self) -> Dict[str, Any]: def build_collection(snapshot: ServerSnapshot, options: Optional[GeneratorOptions] = None) -> Dict[str, Any]: - """Convenience wrapper around :class:`CollectionBuilder`.""" + """Convenience wrapper around :class:`CollectionBuilder` (collection only).""" return CollectionBuilder(snapshot, options).build() -def build_environment(options: GeneratorOptions, name: str) -> Dict[str, Any]: - """A Postman environment holding the target URL and custom header values.""" +def build_collection_and_environment( + snapshot: ServerSnapshot, options: Optional[GeneratorOptions] = None, environment_name: Optional[str] = None +) -> Tuple[Dict[str, Any], Dict[str, Any]]: + """Build the collection and the matching environment (with any body variables).""" + builder = CollectionBuilder(snapshot, options) + collection = builder.build() + name = environment_name or collection["info"]["name"] + return collection, build_environment(builder.options, name, builder.body_variables) + + +def build_environment( + options: GeneratorOptions, name: str, body_variables: Optional[Mapping[str, Any]] = None +) -> Dict[str, Any]: + """A Postman environment with ``baseUrl``, custom headers and body variables.""" values = [{"key": "baseUrl", "value": options.base_url, "type": "default", "enabled": True}] for header, value in options.headers.items(): values.append( @@ -538,6 +627,8 @@ def build_environment(options: GeneratorOptions, name: str) -> Dict[str, Any]: "enabled": True, } ) + for key, value in (body_variables or {}).items(): + values.append({"key": key, "value": environment_value(value), "type": "default", "enabled": True}) return { "id": str(uuid.uuid5(_NAMESPACE, "env:" + name)), "name": name, diff --git a/src/mcp2rest2postman/scripts.py b/src/mcp2rest2postman/scripts.py index 3e3ac34..613fb70 100644 --- a/src/mcp2rest2postman/scripts.py +++ b/src/mcp2rest2postman/scripts.py @@ -32,7 +32,7 @@ } } let requestId; - try { requestId = JSON.parse(pm.request.body.raw).id; } catch (e) { requestId = undefined; } + try { requestId = JSON.parse(pm.variables.replaceIn(pm.request.body.raw)).id; } catch (e) { requestId = undefined; } const flat = [].concat(...messages.map((m) => (Array.isArray(m) ? m : [m]))); const isResponse = (m) => m && typeof m === 'object' && ('result' in m || 'error' in m); const message = flat.find((m) => isResponse(m) && (requestId === undefined || m.id === requestId)) || null; diff --git a/tests/test_cli.py b/tests/test_cli.py index 4c54267..759ae0c 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -38,10 +38,50 @@ def test_generate_from_stdio_and_snapshot(tmp_path): assert a["item"] == b["item"] -def test_generate_to_stdout(json_url, capsys): +def test_generate_to_stdout(json_url, capsys, tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) assert main(["generate", "-q", "--url", json_url, "-o", "-", "--no-negative-tests"]) == 0 col = json.loads(capsys.readouterr().out) assert not any("->" in n and "add" in n for n in by_name(col)) + # the environment is still written, in the working directory + env = json.loads((tmp_path / "demo-mcp-server.postman_environment.json").read_text()) + assert env["values"][0] == {"key": "baseUrl", "value": json_url, "type": "default", "enabled": True} + + +def test_environment_always_written_next_to_collection(tmp_path, json_url): + out = tmp_path / "out" / "my.postman_collection.json" + out.parent.mkdir() + assert main(["generate", "-q", "--url", json_url, "-o", str(out)]) == 0 + env = json.loads((tmp_path / "out" / "my.postman_environment.json").read_text()) + assert {v["key"]: v["value"] for v in env["values"]} == {"baseUrl": json_url} + + +def test_body_variables(tmp_path, json_url): + values = tmp_path / "v.json" + values.write_text(json.dumps({"greet": {"name": 'Ada "the first"'}})) + out = tmp_path / "c.json" + assert main(["generate", "-q", "--url", json_url, "--body-variables", "--values", str(values), "-o", str(out)]) == 0 + col = by_name(json.loads(out.read_text())) + env = {v["key"]: v["value"] for v in json.loads((tmp_path / "c.postman_environment.json").read_text())["values"]} + raw = col["add - valid, all attributes"]["request"]["body"]["raw"] + assert '"a": {{add_a}}' in raw and '"b": {{add_b}}' in raw + assert env["add_a"] == "1" and env["add_b"] == "1" + raw = col["greet - valid, all attributes"]["request"]["body"]["raw"] + assert '"name": "{{greet_name}}"' in raw and '"excited": {{greet_excited}}' in raw + assert env["greet_name"] == 'Ada \\"the first\\"' # stored JSON-escaped + assert env["search_items_filters"] == '{"inStock": true}' + assert env["prompt_summarize_text"] == "example-text" + # wrong-type tests keep their deliberately invalid literal + raw = col["add - wrong type for required 'a' -> error"]["request"]["body"]["raw"] + assert '"a": "not-a-valid-value"' in raw and "{{add_b}}" in raw + # substituting the environment gives back valid JSON with the original types + for item in col.values(): + body = item["request"].get("body") + if body: + text = body["raw"] + for key, value in env.items(): + text = text.replace("{{" + key + "}}", value) + json.loads(text) def test_values_file(tmp_path, json_url): diff --git a/tests/test_e2e_postman.py b/tests/test_e2e_postman.py index 4a92ce0..d02d21c 100644 --- a/tests/test_e2e_postman.py +++ b/tests/test_e2e_postman.py @@ -18,13 +18,16 @@ pytestmark = pytest.mark.skipif(not (NEWMAN or POSTMAN), reason="newman / postman CLI not installed") -def run_collection(path, report): +def run_collection(path, report, environment=None): + env_args = ["-e", str(environment)] if environment else [] if NEWMAN: - cmd = [NEWMAN, "run", str(path), "-r", "json", "--reporter-json-export", str(report)] + cmd = [NEWMAN, "run", str(path), *env_args, "-r", "json", "--reporter-json-export", str(report)] subprocess.run(cmd, capture_output=True, timeout=120) run = json.loads(report.read_text())["run"] return run["stats"]["assertions"]["total"], len(run["failures"]) - proc = subprocess.run([POSTMAN, "collection", "run", str(path)], capture_output=True, text=True, timeout=120) + proc = subprocess.run( + [POSTMAN, "collection", "run", str(path), *env_args], capture_output=True, text=True, timeout=120 + ) return None, proc.returncode @@ -48,3 +51,14 @@ def test_drift_is_detected(tmp_path, json_url): assert main(["generate", "-q", "--from-snapshot", str(snap), "--base-url", json_url, "-o", str(col)]) == 0 _, failures = run_collection(col, tmp_path / "r.json") assert failures > 0 + + +def test_body_variables_collection_passes_with_environment(tmp_path, http_url): + col = tmp_path / "c.postman_collection.json" + env = tmp_path / "c.postman_environment.json" + assert main(["generate", "-q", "--url", http_url, "--body-variables", "-o", str(col)]) == 0 + assert "{{add_a}}" in col.read_text() + total, failures = run_collection(col, tmp_path / "r.json", environment=env) + assert failures == 0 + if total is not None: + assert total > 100 diff --git a/tests/test_postman.py b/tests/test_postman.py index 742f348..595fb41 100644 --- a/tests/test_postman.py +++ b/tests/test_postman.py @@ -3,7 +3,15 @@ import pytest from mcp2rest2postman.discovery import ServerSnapshot -from mcp2rest2postman.postman import POSTMAN_SCHEMA, GeneratorOptions, build_collection, build_environment +from mcp2rest2postman.postman import ( + POSTMAN_SCHEMA, + GeneratorOptions, + build_collection, + build_collection_and_environment, + build_environment, + environment_value, + variable_name, +) from helpers import body, by_name, flatten @@ -153,3 +161,39 @@ def test_custom_headers_become_variables(): assert "s3cret" in json.dumps(build_collection(SNAPSHOT, opts)) env = build_environment(opts, "e") assert {v["key"] for v in env["values"]} == {"baseUrl", "header_authorization"} + + +def test_body_variables_off_by_default(collection): + assert "{{create_user_" not in json.dumps(collection) + + +def test_body_variables_collection_and_environment(): + col, env = build_collection_and_environment(SNAPSHOT, GeneratorOptions(body_variables=True), "env") + items = by_name(col) + raw = items["create_user - valid, all attributes"]["request"]["body"]["raw"] + assert '"email": "{{create_user_email}}"' in raw and '"age": {{create_user_age}}' in raw + values = {v["key"]: v["value"] for v in env["values"]} + assert values["baseUrl"] == "http://localhost:3000/mcp" + assert values["create_user_email"] == "user@example.com" + assert values["create_user_age"] == "18" + assert values["prompt_p_x"] == "example-x" + # the required-only and single-optional variants reuse the same variables + raw = items["create_user - valid, required + optional 'admin'"]["request"]["body"]["raw"] + assert "{{create_user_admin}}" in raw and "{{create_user_email}}" in raw + assert not any(k.endswith("_2") for k in values) + # the test script can still read the JSON-RPC id once variables are resolved + script = "\n".join(items["create_user - valid, all attributes"]["event"][0]["script"]["exec"]) + assert "pm.variables.replaceIn(pm.request.body.raw)" in script + + +def test_variable_helpers(): + assert variable_name("my-tool", "e.mail") == "my_tool_e_mail" + assert environment_value("a\"b") == 'a\\"b' + assert environment_value(3) == "3" + assert environment_value([1, "x"]) == '[1, "x"]' + assert environment_value(None) == "null" + + +def test_environment_without_body_variables_still_has_base_url(): + env = build_environment(GeneratorOptions(base_url="http://x/mcp"), "e") + assert env["values"] == [{"key": "baseUrl", "value": "http://x/mcp", "type": "default", "enabled": True}]