k11-api-functional-qa-mcp 0.1.0__tar.gz

k11_api_functional_qa_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.tmp*
+*.db
+.qa-mcp/api-test-report/

k11_api_functional_qa_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K11 Software Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

k11_api_functional_qa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: k11-api-functional-qa-mcp
+Version: 0.1.0
+Summary: MCP server and Claude Code plugin for functional API testing: user stories to multi-step API test flows, negative and boundary tests from the spec, database checks and fixtures, with evidence for every step.
+Project-URL: Homepage, https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp
+Project-URL: Issues, https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp/issues
+Author: K11 Software Solutions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-testing,claude,database-testing,functional-testing,mcp,negative-testing,openapi,qa,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: k11-api-contract-qa-mcp>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# k11 API Functional QA — MCP server & Claude Code plugin
+
+<!-- mcp-name: io.github.K11-Software-Solutions/api-functional-qa -->
+
+**Functional API tests that prove the API did the right thing, down to the database row.**
+
+Contract checks tell you an API still has the right *shape*. They don't tell you whether placing an order charges the right amount, whether cancelling really soft-deletes the row, or whether a malformed request crashes the server. This MCP server lets Claude (or any MCP client) write and run those tests with you:
+
+- **User story → multi-step test flow.** Chain calls (`POST /orders` → save the `id` → `GET /orders/{id}` → `DELETE`) with readable YAML and value checks.
+- **Database checks in the same flow.** After the API call, check the row really changed: `SELECT status, deleted_at FROM orders WHERE id = :orderId`. Read-only by default, with masked columns.
+- **Negative and boundary tests from the spec,** including nested fields and array items: missing required fields, wrong types, values outside enums and min/max/length limits, no credentials, unknown IDs. Every case must get a 4xx, **never a 5xx**.
+- **Evidence for every step:** the request, response, query, rows and each check, in Markdown (PR comment), JSON and JUnit XML for CI dashboards.
+- **Guardrails:** data-changing calls are refused on production-like environments, database writes only in fixtures and cleanup on allowlisted test databases, secrets only from environment variables and masked everywhere, and requests never leave the environment's host.
+- **No lock-in:** export any flow as plain pytest + httpx code.
+
+Built on the parsers of [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp) (OpenAPI 3.x and Swagger 2.0 for test generation and response-schema checks).
+
+---
+
+## See it find real bugs
+
+The demo shop API (`demo/shop/`) has two planted bugs. Two hand-written flows and one generated negative suite found them, plus one I didn't plant.
+
+**1. The order total is wrong only in the API response.** `order_total.yaml` orders two bags at 42.50:
+
+> ❌ **Order total is quantity times price**
+> - **place an order for two bags**: failed. Response: HTTP 201. ✗ `$.total 85.0`: expected 85.0, got 42.5
+> - **the database stores 85.00**: passed
+> - **order history shows 85.00**: passed
+
+The database check shows exactly where the bug is: the stored total is right, and only the `POST /orders` response is wrong.
+
+**2. Malformed input crashes the server.** `generate_negative_tests("POST /orders")` produced 18 cases from the spec. 16 behaved correctly, and two returned **HTTP 500**:
+
+> - ✗ wrong type for `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+> - ✗ missing required field `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+
+The second crash wasn't planted. It's the same code path, and the generator found it because it tests nested array items, not just top-level fields.
+
+**3. The soft delete works, proven in the database.** `cancel_order.yaml` passes all 7 steps, including checks that the row is kept with `status = cancelled` and a `deleted_at` timestamp.
+
+## A flow
+
+```yaml
+name: Customer cancels an order and it is soft-deleted
+fixtures: [customer]                       # seeded in the test database, removed afterwards
+steps:
+  - name: place an order
+    call: POST /orders
+    body: { customerId: "${fixture.customer.id}", channel: web, items: [{ sku: HAT-2, qty: 1 }] }
+    expect:
+      status: 201
+      json: { "$.status": pending, "$.total": 15.0, "$.items": { length: 1 } }
+    save: { orderId: "$.id" }
+
+  - name: the row is kept and marked deleted
+    db: SELECT status, deleted_at FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+    expect: { rows: 1, row: { status: cancelled, deleted_at: { ne: null } } }
+
+cleanup:
+  - db: DELETE FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+```
+
+- **Checks** (`expect`): `status` (`201`, `"2xx"`, `[400, 422]`), `json` paths (`$.items[0].qty`, `$.items[*].sku`, `$.items.length`), `headers`, `body_contains`, `max_ms`, and the response schema from the spec (on by default). Values compare as literals or with operators: `eq ne gt gte lt lte approx contains matches length type in exists empty`.
+- **Variables:** `save` from JSON paths, headers (`header:Location`) or `status`; use them as `${orderId}`. Generators: `${uuid}`, `${random_email}`, `${random_int}`, `${now}`, `${today}`. Secrets: `${ENV:NAME}`.
+- **Failures:** a step that only fails value checks lets the flow continue, to gather more evidence. A wrong status, a 5xx, a blocked write or a missing saved value stops it. `continue_on_failure: true` runs every step (generated negative suites use it). Cleanup always runs.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_environments` | Environments and whether each allows writes (and why), auth profiles, databases, fixtures, flows. |
+| `draft_flow` | User story → scenarios, the spec operations most likely involved, and a flow skeleton. |
+| `generate_negative_tests` | Negative and boundary cases for one operation, with real base values from fixtures. |
+| `write_flow` | Validates and saves a flow under `tests/api/`. |
+| `run_flows` | Runs flows (all, by path or by tag) with full evidence and reports. |
+| `call_api` | One request with the same guardrails, to explore an API while writing tests. |
+| `query_db` | One read-only query against a test database, with masking. |
+| `export_pytest` | A flow as plain pytest + httpx code. |
+
+## Configure: `.qa-mcp/api-test.yaml`
+
+```yaml
+spec: openapi.yaml
+default_environment: local
+environments:
+  local:   { base_url: http://localhost:8080 }
+  staging: { base_url: https://staging.example.com, allow_writes: true }
+  prod:    { base_url: https://api.example.com }        # read-only: writes refused
+auth:
+  default: { type: bearer, token: "${ENV:API_TOKEN}" }
+  # basic: {username, password} · api_key: {header, value} · oauth2: {token_url, client_id, client_secret, scope}
+databases:
+  main: { url: "${ENV:TEST_DB_URL}", allow_writes: true, mask: [email, card_number] }
+fixtures:
+  customer:
+    db: main
+    insert: { table: customers, values: { id: "${uuid}", email: "${random_email}", name: Test Customer } }
+    delete: { table: customers, where: { id: "${id}" } }
+```
+
+**Databases:** SQLite (built in), PostgreSQL (`pip install "k11-api-functional-qa-mcp[postgres]"`), MySQL/MariaDB (`[mysql]`) and SQL Server (`[mssql]`).
+
+## Guardrails
+
+| Risk | What happens |
+|---|---|
+| Changing data in production | `POST/PUT/PATCH/DELETE` are refused on environments named like production (`prod`, `production`, `live`) unless they set both `allow_writes: true` and `production_writes_acknowledged: true`. Other environments must be local, named like a test environment, or set `allow_writes: true`. |
+| Writing to a database | `db` steps may only read (SELECT/WITH/SHOW/EXPLAIN; no write verbs anywhere, no `FOR UPDATE`), on a read-only connection inside a rolled-back transaction. Writes happen only in fixtures and cleanup, on databases with `allow_writes: true`. |
+| SQL injection | Values go in `:named` parameters; `${...}` inside SQL text is refused, as is more than one statement. Table and column names in fixtures are validated. |
+| Leaking secrets | Credentials come from `${ENV:NAME}`. Authorization headers show as `•••`, and any secret value is masked in requests, responses, errors and reports, as are database columns listed under `mask`. |
+| Sending credentials elsewhere | Requests must stay on the environment's host; a flow can't send your token to another URL. |
+| Runaway queries | At most 1,000 rows are read per query, with timeouts on every connection and request. |
+
+## In CI
+
+```bash
+k11-api-functional-qa-mcp run --env staging
+```
+
+It writes `api-test-report.md` (PR comment), `api-test-report.json` (evidence) and `api-test-junit.xml`, sets GitHub Actions outputs and exits non-zero when a flow fails (`--fail-on any|failed|never`). See [`docs/api-tests.yml`](docs/api-tests.yml).
+
+## Install
+
+Requires Python 3.10+.
+
+```text
+/plugin marketplace add K11-Software-Solutions/k11techlab-api-functional-qa-mcp
+/plugin install api-functional-qa@k11-api-functional-qa
+```
+
+The plugin adds `/api-story-test` and `/api-negative-tests`. To add only the MCP server:
+
+```bash
+claude mcp add api-functional-qa -- uvx k11-api-functional-qa-mcp
+```
+
+Claude Desktop and other clients: run `uvx k11-api-functional-qa-mcp` with `QA_MCP_ROOT` set to your project.
+
+## Try the demo
+
+```bash
+python demo/shop/server.py --port 8080
+SHOP_URL=http://127.0.0.1:8080 SHOP_TOKEN=test-token QA_MCP_ROOT=demo/shop k11-api-functional-qa-mcp run
+```
+
+## Scope
+
+This server is for functional REST testing with database checks. Related K11 tools:
+- **Contract and breaking-change checks** (REST, GraphQL, gRPC, AsyncAPI, SOAP): [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp)
+- **UI tests:** [Playwright QA](https://github.com/K11-Software-Solutions/k11techlab-playwright-qa-mcp) and [Selenium QA](https://github.com/K11-Software-Solutions/k11techlab-selenium-qa-mcp)
+- **LLM red-teaming:** [LLM Assure](https://github.com/K11-Software-Solutions/k11techlab-llm-assurance-toolkit)
+
+Not covered: load testing (use k6 or Gatling) and deep fuzzing (use Schemathesis).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"   # bin/pip on macOS/Linux
+pytest   # values, guardrails, flows against the demo shop, negative tests, export, CLI, MCP (25)
+```
+
+## Roadmap
+
+- GraphQL, gRPC and SOAP calls as flow steps
+- Java export (REST Assured)
+- MongoDB checks
+- Schema-driven test data (realistic values per field format)
+
+---
+
+Built by [K11 Software Solutions](https://k11softwaresolutions.com). Part of the K11 Tech Lab agentic QA series. MIT licensed.

k11_api_functional_qa_mcp-0.1.0/README.md

@@ -0,0 +1,174 @@
+# k11 API Functional QA — MCP server & Claude Code plugin
+
+<!-- mcp-name: io.github.K11-Software-Solutions/api-functional-qa -->
+
+**Functional API tests that prove the API did the right thing, down to the database row.**
+
+Contract checks tell you an API still has the right *shape*. They don't tell you whether placing an order charges the right amount, whether cancelling really soft-deletes the row, or whether a malformed request crashes the server. This MCP server lets Claude (or any MCP client) write and run those tests with you:
+
+- **User story → multi-step test flow.** Chain calls (`POST /orders` → save the `id` → `GET /orders/{id}` → `DELETE`) with readable YAML and value checks.
+- **Database checks in the same flow.** After the API call, check the row really changed: `SELECT status, deleted_at FROM orders WHERE id = :orderId`. Read-only by default, with masked columns.
+- **Negative and boundary tests from the spec,** including nested fields and array items: missing required fields, wrong types, values outside enums and min/max/length limits, no credentials, unknown IDs. Every case must get a 4xx, **never a 5xx**.
+- **Evidence for every step:** the request, response, query, rows and each check, in Markdown (PR comment), JSON and JUnit XML for CI dashboards.
+- **Guardrails:** data-changing calls are refused on production-like environments, database writes only in fixtures and cleanup on allowlisted test databases, secrets only from environment variables and masked everywhere, and requests never leave the environment's host.
+- **No lock-in:** export any flow as plain pytest + httpx code.
+
+Built on the parsers of [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp) (OpenAPI 3.x and Swagger 2.0 for test generation and response-schema checks).
+
+---
+
+## See it find real bugs
+
+The demo shop API (`demo/shop/`) has two planted bugs. Two hand-written flows and one generated negative suite found them, plus one I didn't plant.
+
+**1. The order total is wrong only in the API response.** `order_total.yaml` orders two bags at 42.50:
+
+> ❌ **Order total is quantity times price**
+> - **place an order for two bags**: failed. Response: HTTP 201. ✗ `$.total 85.0`: expected 85.0, got 42.5
+> - **the database stores 85.00**: passed
+> - **order history shows 85.00**: passed
+
+The database check shows exactly where the bug is: the stored total is right, and only the `POST /orders` response is wrong.
+
+**2. Malformed input crashes the server.** `generate_negative_tests("POST /orders")` produced 18 cases from the spec. 16 behaved correctly, and two returned **HTTP 500**:
+
+> - ✗ wrong type for `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+> - ✗ missing required field `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+
+The second crash wasn't planted. It's the same code path, and the generator found it because it tests nested array items, not just top-level fields.
+
+**3. The soft delete works, proven in the database.** `cancel_order.yaml` passes all 7 steps, including checks that the row is kept with `status = cancelled` and a `deleted_at` timestamp.
+
+## A flow
+
+```yaml
+name: Customer cancels an order and it is soft-deleted
+fixtures: [customer]                       # seeded in the test database, removed afterwards
+steps:
+  - name: place an order
+    call: POST /orders
+    body: { customerId: "${fixture.customer.id}", channel: web, items: [{ sku: HAT-2, qty: 1 }] }
+    expect:
+      status: 201
+      json: { "$.status": pending, "$.total": 15.0, "$.items": { length: 1 } }
+    save: { orderId: "$.id" }
+
+  - name: the row is kept and marked deleted
+    db: SELECT status, deleted_at FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+    expect: { rows: 1, row: { status: cancelled, deleted_at: { ne: null } } }
+
+cleanup:
+  - db: DELETE FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+```
+
+- **Checks** (`expect`): `status` (`201`, `"2xx"`, `[400, 422]`), `json` paths (`$.items[0].qty`, `$.items[*].sku`, `$.items.length`), `headers`, `body_contains`, `max_ms`, and the response schema from the spec (on by default). Values compare as literals or with operators: `eq ne gt gte lt lte approx contains matches length type in exists empty`.
+- **Variables:** `save` from JSON paths, headers (`header:Location`) or `status`; use them as `${orderId}`. Generators: `${uuid}`, `${random_email}`, `${random_int}`, `${now}`, `${today}`. Secrets: `${ENV:NAME}`.
+- **Failures:** a step that only fails value checks lets the flow continue, to gather more evidence. A wrong status, a 5xx, a blocked write or a missing saved value stops it. `continue_on_failure: true` runs every step (generated negative suites use it). Cleanup always runs.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_environments` | Environments and whether each allows writes (and why), auth profiles, databases, fixtures, flows. |
+| `draft_flow` | User story → scenarios, the spec operations most likely involved, and a flow skeleton. |
+| `generate_negative_tests` | Negative and boundary cases for one operation, with real base values from fixtures. |
+| `write_flow` | Validates and saves a flow under `tests/api/`. |
+| `run_flows` | Runs flows (all, by path or by tag) with full evidence and reports. |
+| `call_api` | One request with the same guardrails, to explore an API while writing tests. |
+| `query_db` | One read-only query against a test database, with masking. |
+| `export_pytest` | A flow as plain pytest + httpx code. |
+
+## Configure: `.qa-mcp/api-test.yaml`
+
+```yaml
+spec: openapi.yaml
+default_environment: local
+environments:
+  local:   { base_url: http://localhost:8080 }
+  staging: { base_url: https://staging.example.com, allow_writes: true }
+  prod:    { base_url: https://api.example.com }        # read-only: writes refused
+auth:
+  default: { type: bearer, token: "${ENV:API_TOKEN}" }
+  # basic: {username, password} · api_key: {header, value} · oauth2: {token_url, client_id, client_secret, scope}
+databases:
+  main: { url: "${ENV:TEST_DB_URL}", allow_writes: true, mask: [email, card_number] }
+fixtures:
+  customer:
+    db: main
+    insert: { table: customers, values: { id: "${uuid}", email: "${random_email}", name: Test Customer } }
+    delete: { table: customers, where: { id: "${id}" } }
+```
+
+**Databases:** SQLite (built in), PostgreSQL (`pip install "k11-api-functional-qa-mcp[postgres]"`), MySQL/MariaDB (`[mysql]`) and SQL Server (`[mssql]`).
+
+## Guardrails
+
+| Risk | What happens |
+|---|---|
+| Changing data in production | `POST/PUT/PATCH/DELETE` are refused on environments named like production (`prod`, `production`, `live`) unless they set both `allow_writes: true` and `production_writes_acknowledged: true`. Other environments must be local, named like a test environment, or set `allow_writes: true`. |
+| Writing to a database | `db` steps may only read (SELECT/WITH/SHOW/EXPLAIN; no write verbs anywhere, no `FOR UPDATE`), on a read-only connection inside a rolled-back transaction. Writes happen only in fixtures and cleanup, on databases with `allow_writes: true`. |
+| SQL injection | Values go in `:named` parameters; `${...}` inside SQL text is refused, as is more than one statement. Table and column names in fixtures are validated. |
+| Leaking secrets | Credentials come from `${ENV:NAME}`. Authorization headers show as `•••`, and any secret value is masked in requests, responses, errors and reports, as are database columns listed under `mask`. |
+| Sending credentials elsewhere | Requests must stay on the environment's host; a flow can't send your token to another URL. |
+| Runaway queries | At most 1,000 rows are read per query, with timeouts on every connection and request. |
+
+## In CI
+
+```bash
+k11-api-functional-qa-mcp run --env staging
+```
+
+It writes `api-test-report.md` (PR comment), `api-test-report.json` (evidence) and `api-test-junit.xml`, sets GitHub Actions outputs and exits non-zero when a flow fails (`--fail-on any|failed|never`). See [`docs/api-tests.yml`](docs/api-tests.yml).
+
+## Install
+
+Requires Python 3.10+.
+
+```text
+/plugin marketplace add K11-Software-Solutions/k11techlab-api-functional-qa-mcp
+/plugin install api-functional-qa@k11-api-functional-qa
+```
+
+The plugin adds `/api-story-test` and `/api-negative-tests`. To add only the MCP server:
+
+```bash
+claude mcp add api-functional-qa -- uvx k11-api-functional-qa-mcp
+```
+
+Claude Desktop and other clients: run `uvx k11-api-functional-qa-mcp` with `QA_MCP_ROOT` set to your project.
+
+## Try the demo
+
+```bash
+python demo/shop/server.py --port 8080
+SHOP_URL=http://127.0.0.1:8080 SHOP_TOKEN=test-token QA_MCP_ROOT=demo/shop k11-api-functional-qa-mcp run
+```
+
+## Scope
+
+This server is for functional REST testing with database checks. Related K11 tools:
+- **Contract and breaking-change checks** (REST, GraphQL, gRPC, AsyncAPI, SOAP): [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp)
+- **UI tests:** [Playwright QA](https://github.com/K11-Software-Solutions/k11techlab-playwright-qa-mcp) and [Selenium QA](https://github.com/K11-Software-Solutions/k11techlab-selenium-qa-mcp)
+- **LLM red-teaming:** [LLM Assure](https://github.com/K11-Software-Solutions/k11techlab-llm-assurance-toolkit)
+
+Not covered: load testing (use k6 or Gatling) and deep fuzzing (use Schemathesis).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"   # bin/pip on macOS/Linux
+pytest   # values, guardrails, flows against the demo shop, negative tests, export, CLI, MCP (25)
+```
+
+## Roadmap
+
+- GraphQL, gRPC and SOAP calls as flow steps
+- Java export (REST Assured)
+- MongoDB checks
+- Schema-driven test data (realistic values per field format)
+
+---
+
+Built by [K11 Software Solutions](https://k11softwaresolutions.com). Part of the K11 Tech Lab agentic QA series. MIT licensed.

k11_api_functional_qa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "k11-api-functional-qa-mcp"
+version = "0.1.0"
+description = "MCP server and Claude Code plugin for functional API testing: user stories to multi-step API test flows, negative and boundary tests from the spec, database checks and fixtures, with evidence for every step."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "K11 Software Solutions" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "api-testing", "functional-testing", "rest", "openapi", "database-testing", "negative-testing", "qa", "claude"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = ["k11-api-contract-qa-mcp>=0.1.0"]
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.1"]
+mysql = ["pymysql>=1.1"]
+mssql = ["pymssql>=2.3"]
+dev = ["pytest>=8", "pytest-timeout>=2"]
+
+[project.urls]
+Homepage = "https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp"
+Issues = "https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp/issues"
+
+[project.scripts]
+k11-api-functional-qa-mcp = "k11_api_qa.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/k11_api_qa"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 120

k11_api_functional_qa_mcp-0.1.0/src/k11_api_qa/__init__.py

@@ -0,0 +1,3 @@
+"""k11 API Functional QA: multi-step API test flows with database checks, over MCP and in CI."""
+
+__version__ = "0.1.0"

k11_api_functional_qa_mcp-0.1.0/src/k11_api_qa/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

k11_api_functional_qa_mcp-0.1.0/src/k11_api_qa/auth.py

@@ -0,0 +1,54 @@
+"""Auth profiles: bearer, basic, api_key, oauth2 client credentials, or none.
+
+Secrets come from ``${ENV:NAME}``; they are masked in every result. OAuth tokens are cached
+for the run.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+
+import httpx
+
+from .values import Vars
+
+_cache: dict[str, tuple[str, float]] = {}
+
+
+def headers(profile_name: str | None, profiles: dict, v: Vars, timeout: float = 20) -> dict[str, str]:
+    if not profile_name or profile_name == "none":
+        return {}
+    if profile_name not in profiles:
+        if profile_name == "default":
+            return {}
+        raise ValueError(f"Unknown auth profile '{profile_name}'. Known: {sorted(profiles) or ['(none)']}")
+    p = v.sub(profiles[profile_name])
+    kind = p.get("type", "bearer")
+    if kind == "bearer":
+        return {"Authorization": f"Bearer {p['token']}"}
+    if kind == "basic":
+        raw = f"{p['username']}:{p['password']}".encode()
+        token = base64.b64encode(raw).decode()
+        v.secrets.add(token)
+        return {"Authorization": f"Basic {token}"}
+    if kind == "api_key":
+        return {p.get("header", "X-API-Key"): str(p["value"])}
+    if kind in ("oauth2", "oauth2_client_credentials"):
+        key = f"{p['token_url']}|{p['client_id']}|{p.get('scope', '')}"
+        tok, exp = _cache.get(key, ("", 0.0))
+        if not tok or exp < time.time() + 30:
+            data = {"grant_type": "client_credentials", "client_id": p["client_id"], "client_secret": p["client_secret"]}
+            if p.get("scope"):
+                data["scope"] = p["scope"]
+            if p.get("audience"):
+                data["audience"] = p["audience"]
+            r = httpx.post(p["token_url"], data=data, timeout=timeout)
+            if r.status_code >= 400:
+                raise ValueError(f"OAuth token request failed with HTTP {r.status_code}")
+            body = r.json()
+            tok = body["access_token"]
+            _cache[key] = (tok, time.time() + float(body.get("expires_in", 300)))
+        v.secrets.add(tok)
+        return {"Authorization": f"Bearer {tok}"}
+    raise ValueError(f"Unknown auth type '{kind}' (bearer, basic, api_key, oauth2)")

k11_api_functional_qa_mcp-0.1.0/src/k11_api_qa/cli.py

@@ -0,0 +1,86 @@
+"""Command line: start the MCP server (default) or run flows in CI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+
+USAGE = f"""k11-api-functional-qa-mcp {__version__}
+
+Usage:
+  k11-api-functional-qa-mcp                      start the MCP server on stdio
+  k11-api-functional-qa-mcp run [paths] [opts]   run API test flows and write reports
+  k11-api-functional-qa-mcp --version
+
+run options:
+  --env NAME           environment from .qa-mcp/api-test.yaml (default: default_environment)
+  --tag TAG            only flows with this tag (repeatable)
+  --report-dir PATH    default .qa-mcp/api-test-report
+  --fail-on LEVEL      any (default: fail on failed, blocked or error) | failed | never
+
+The project is QA_MCP_ROOT or the current directory.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv:
+        from .server import serve
+
+        serve()
+        return 0
+    if argv[0] in ("--version", "-v"):
+        print(__version__)
+        return 0
+    if argv[0] in ("--help", "-h", "help"):
+        print(USAGE)
+        return 0
+    if argv[0] != "run":
+        print(f"Unknown command: {argv[0]}\n\n{USAGE}", file=sys.stderr)
+        return 2
+    p = argparse.ArgumentParser(prog="k11-api-functional-qa-mcp run")
+    p.add_argument("paths", nargs="*")
+    p.add_argument("--env")
+    p.add_argument("--tag", action="append")
+    p.add_argument("--report-dir", default=".qa-mcp/api-test-report")
+    p.add_argument("--fail-on", default="any", choices=["any", "failed", "never"])
+    a = p.parse_args(argv[1:])
+
+    from k11_contract_qa.spec import SpecError, inside
+
+    from . import config, report
+    from .runner import flow_files, run_files
+
+    root = Path(os.environ.get("QA_MCP_ROOT") or os.getcwd()).resolve()
+    try:
+        cfg = config.load(root)
+        files = flow_files(root, a.paths or None)
+        if not files:
+            print("No flows found in tests/api/", file=sys.stderr)
+            return 1
+        results = run_files(cfg, files, a.env, a.tag)
+        env = results[0].environment if results else (a.env or cfg.default_environment)
+        paths = report.write(results, env, inside(root, a.report_dir))
+    except (SpecError, ValueError, OSError) as e:
+        print(f"run failed: {e}", file=sys.stderr)
+        return 1
+    c = report.counts(results)
+    print(f"{c['passed']}/{c['flows']} flows passed ({c['failed']} failed, {c['blocked']} blocked, {c['error']} errors, "
+          f"{c['server_errors']} server errors). Report: {paths['markdown']}")
+    if os.environ.get("GITHUB_OUTPUT"):
+        with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf8") as fh:
+            fh.write(f"passed={c['passed']}\nfailed={c['failed']}\nblocked={c['blocked']}\nerrors={c['error']}\n"
+                     f"report={paths['markdown']}\njunit={paths['junit']}\n")
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf8") as fh:
+            fh.write(paths["markdown"].read_text("utf8") + "\n")
+    bad = {"any": c["failed"] + c["blocked"] + c["error"], "failed": c["failed"], "never": 0}[a.fail_on]
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())