Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 `<tool>_<arg>` or
`prompt_<prompt>_<arg>`, 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 |
|---|---|
Expand All @@ -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. |
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Changelog

## 0.2.0

### Added
- `--body-variables`: tool and prompt argument values move from request
bodies into environment variables (`{{<tool>_<arg>}}`,
`{{prompt_<prompt>_<arg>}}`). 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)
78 changes: 70 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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`:
Expand Down Expand Up @@ -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 `<server>.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` (`<server>.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 |
Expand Down Expand Up @@ -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
`{{<tool>_<argument>}}`, and every prompt argument becomes
`{{prompt_<prompt>_<argument>}}`. 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
Expand Down Expand Up @@ -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`
Expand Down
Loading
Loading