mcp-api-test 0.1.2__tar.gz → 0.1.3__tar.gz

mcp_api_test-0.1.3/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: mcp-api-test
+Version: 0.1.3
+Summary: MCP server for testing REST API with built-in assertions
+Author: Ryan Febriansyah
+License-Expression: MIT
+Keywords: testing,mcp,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Dynamic: license-file
+
+# mcp-api-test
+
+![pipeline](https://gitlab.com/ryaneatfood/mcp-api-testing/badges/master/pipeline.svg)
+
+An AI-native API testing engine that enables LLM agents to execute, validate, and reason about REST APIs using natural language or cURL inputs.
+
+Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a **first-class capability for AI agents** rather than a developer-facing tool. LLM-powered clients invoke the `run_test_api` tool directly, making API validation a building block for autonomous coding agents, not a separate human-driven workflow.
+
+It complements (rather than replaces) tools like pytest, Postman, and Playwright.
+
+## Use cases
+
+- **QA & test engineering**: prompt an agent with natural language instead of crafting Postman requests
+- **Post-deployment regression**: have an agent smoke-test critical paths after a deploy
+- **Quick validation**: test an endpoint inline during a coding session
+- **CI/CD automation**: agents validate deployments autonomously in pipelines
+
+> **Token efficiency.** Agents get deterministic, structured results in a single tool call instead of parsing raw `curl` output. Fewer tokens, fewer hallucinations.
+
+## Install
+
+```bash
+pip install mcp-api-test
+```
+
+Or from source:
+
+```bash
+git clone git@gitlab.com:ryaneatfood/mcp-api-testing.git
+cd mcp-api-testing
+pip install -e .
+```
+
+Requires Python >= 3.10.
+
+## Quick start
+
+Configure your MCP client to use the server. For **OpenCode**, add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "mcp-api-test": {
+      "type": "local",
+      "command": ["mcp-api-test"],
+      "enabled": true
+    }
+  }
+}
+```
+
+For **Claude Desktop**, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-api-test": {
+      "command": "mcp-api-test"
+    }
+  }
+}
+```
+
+Then prompt your agent:
+
+> "Test this API: `curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{"name":"test"}'`, ensure status code is 201 and response contains 'id'"
+
+The agent invokes `run_test_api`, validates against the expected contract, and returns structured pass/fail results.
+
+## Documentation
+
+Full documentation is hosted on [GitLab Pages](https://ryaneatfood.gitlab.io/mcp-api-testing/) (or build locally with `mkdocs serve`).
+
+- **[Getting Started](docs/getting-started/installation.md)**: installation and client setup
+- **[Usage](docs/usage/request-modes.md)**: cURL mode, structured mode, assertions, response format
+- **[Guides](docs/guides/troubleshooting.md)**: troubleshooting, development, configuration
+- **[Reference](docs/reference/tool-parameters.md)**: full parameter reference
+
+## License
+
+MIT

mcp_api_test-0.1.3/README.md

@@ -0,0 +1,81 @@
+# mcp-api-test
+
+![pipeline](https://gitlab.com/ryaneatfood/mcp-api-testing/badges/master/pipeline.svg)
+
+An AI-native API testing engine that enables LLM agents to execute, validate, and reason about REST APIs using natural language or cURL inputs.
+
+Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a **first-class capability for AI agents** rather than a developer-facing tool. LLM-powered clients invoke the `run_test_api` tool directly, making API validation a building block for autonomous coding agents, not a separate human-driven workflow.
+
+It complements (rather than replaces) tools like pytest, Postman, and Playwright.
+
+## Use cases
+
+- **QA & test engineering**: prompt an agent with natural language instead of crafting Postman requests
+- **Post-deployment regression**: have an agent smoke-test critical paths after a deploy
+- **Quick validation**: test an endpoint inline during a coding session
+- **CI/CD automation**: agents validate deployments autonomously in pipelines
+
+> **Token efficiency.** Agents get deterministic, structured results in a single tool call instead of parsing raw `curl` output. Fewer tokens, fewer hallucinations.
+
+## Install
+
+```bash
+pip install mcp-api-test
+```
+
+Or from source:
+
+```bash
+git clone git@gitlab.com:ryaneatfood/mcp-api-testing.git
+cd mcp-api-testing
+pip install -e .
+```
+
+Requires Python >= 3.10.
+
+## Quick start
+
+Configure your MCP client to use the server. For **OpenCode**, add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "mcp-api-test": {
+      "type": "local",
+      "command": ["mcp-api-test"],
+      "enabled": true
+    }
+  }
+}
+```
+
+For **Claude Desktop**, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-api-test": {
+      "command": "mcp-api-test"
+    }
+  }
+}
+```
+
+Then prompt your agent:
+
+> "Test this API: `curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{"name":"test"}'`, ensure status code is 201 and response contains 'id'"
+
+The agent invokes `run_test_api`, validates against the expected contract, and returns structured pass/fail results.
+
+## Documentation
+
+Full documentation is hosted on [GitLab Pages](https://ryaneatfood.gitlab.io/mcp-api-testing/) (or build locally with `mkdocs serve`).
+
+- **[Getting Started](docs/getting-started/installation.md)**: installation and client setup
+- **[Usage](docs/usage/request-modes.md)**: cURL mode, structured mode, assertions, response format
+- **[Guides](docs/guides/troubleshooting.md)**: troubleshooting, development, configuration
+- **[Reference](docs/reference/tool-parameters.md)**: full parameter reference
+
+## License
+
+MIT

{mcp_api_test-0.1.2 → mcp_api_test-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-api-test"
-version = "0.1.2"
+version = "0.1.3"
 description = "MCP server for testing REST API with built-in assertions"
 readme = "README.md"
 license = "MIT"
@@ -42,4 +42,5 @@ package-dir = {"" = "src"}
 py-modules = ["server", "__main__", "logger", "models", "utils"]
 
 [project.optional-dependencies]
-dev = ["pytest", "pytest-asyncio", "respx"]
+dev = ["pytest", "pytest-asyncio", "respx"]
+docs = ["mkdocs-material"]

mcp_api_test-0.1.3/src/mcp_api_test.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: mcp-api-test
+Version: 0.1.3
+Summary: MCP server for testing REST API with built-in assertions
+Author: Ryan Febriansyah
+License-Expression: MIT
+Keywords: testing,mcp,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Dynamic: license-file
+
+# mcp-api-test
+
+![pipeline](https://gitlab.com/ryaneatfood/mcp-api-testing/badges/master/pipeline.svg)
+
+An AI-native API testing engine that enables LLM agents to execute, validate, and reason about REST APIs using natural language or cURL inputs.
+
+Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a **first-class capability for AI agents** rather than a developer-facing tool. LLM-powered clients invoke the `run_test_api` tool directly, making API validation a building block for autonomous coding agents, not a separate human-driven workflow.
+
+It complements (rather than replaces) tools like pytest, Postman, and Playwright.
+
+## Use cases
+
+- **QA & test engineering**: prompt an agent with natural language instead of crafting Postman requests
+- **Post-deployment regression**: have an agent smoke-test critical paths after a deploy
+- **Quick validation**: test an endpoint inline during a coding session
+- **CI/CD automation**: agents validate deployments autonomously in pipelines
+
+> **Token efficiency.** Agents get deterministic, structured results in a single tool call instead of parsing raw `curl` output. Fewer tokens, fewer hallucinations.
+
+## Install
+
+```bash
+pip install mcp-api-test
+```
+
+Or from source:
+
+```bash
+git clone git@gitlab.com:ryaneatfood/mcp-api-testing.git
+cd mcp-api-testing
+pip install -e .
+```
+
+Requires Python >= 3.10.
+
+## Quick start
+
+Configure your MCP client to use the server. For **OpenCode**, add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "mcp-api-test": {
+      "type": "local",
+      "command": ["mcp-api-test"],
+      "enabled": true
+    }
+  }
+}
+```
+
+For **Claude Desktop**, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-api-test": {
+      "command": "mcp-api-test"
+    }
+  }
+}
+```
+
+Then prompt your agent:
+
+> "Test this API: `curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{"name":"test"}'`, ensure status code is 201 and response contains 'id'"
+
+The agent invokes `run_test_api`, validates against the expected contract, and returns structured pass/fail results.
+
+## Documentation
+
+Full documentation is hosted on [GitLab Pages](https://ryaneatfood.gitlab.io/mcp-api-testing/) (or build locally with `mkdocs serve`).
+
+- **[Getting Started](docs/getting-started/installation.md)**: installation and client setup
+- **[Usage](docs/usage/request-modes.md)**: cURL mode, structured mode, assertions, response format
+- **[Guides](docs/guides/troubleshooting.md)**: troubleshooting, development, configuration
+- **[Reference](docs/reference/tool-parameters.md)**: full parameter reference
+
+## License
+
+MIT

{mcp_api_test-0.1.2 → mcp_api_test-0.1.3}/src/mcp_api_test.egg-info/requires.txt

@@ -6,3 +6,6 @@ python-dotenv
 pytest
 pytest-asyncio
 respx
+
+[docs]
+mkdocs-material

{mcp_api_test-0.1.2 → mcp_api_test-0.1.3}/src/server.py

@@ -193,10 +193,15 @@ async def run_test_api(
     start_time = time.perf_counter()
     try:
         async with httpx.AsyncClient(timeout=30) as client:
-            # prevent requests payload with None-type object or empty body
             kwargs = {"method": method, "url": full_path_url, "headers": headers}
             if payload is not None:
-                kwargs["json"] = payload
+                # cURL parser may produce a raw string for non-JSON -d payloads
+                # (example: form-encoded data). Use content= to send as-is rather
+                # than json= which would double-encode the string.
+                if isinstance(payload, str):
+                    kwargs["content"] = payload
+                else:
+                    kwargs["json"] = payload
             response = await client.request(**kwargs)
             end_time = time.perf_counter()
             response_time_ms = (end_time - start_time) * 1000
@@ -245,9 +250,20 @@ async def run_test_api(
     if required_response_fields:
         for field in required_response_fields:
             if isinstance(resp_body, dict):
-                # resolve conflict resolution about dot-nested structure
                 is_exist = get_nested_fields(body=resp_body, field_path=field)
+            elif isinstance(resp_body, list):
+                # For JSON arrays, check whether at least one item
+                # (if dict) contains the expected field.
+                is_exist = any(
+                    (
+                        get_nested_fields(body=item, field_path=field)
+                        if isinstance(item, dict)
+                        else field in str(item)
+                    )
+                    for item in resp_body
+                )
             else:
+                # Scalar or plain-text response like substring match.
                 is_exist = field in str(resp_body)
             assertions.append(
                 {
@@ -283,9 +299,9 @@ async def run_test_api(
             )
         )
 
-    overall_result = (
-        all(a["passed"] for a in assertions) if assertions else response.is_success
-    )
+    # When no assertions are provided there is nothing to check,
+    # set default to False so the user can see the raw response and decide.
+    overall_result = all(a["passed"] for a in assertions) if assertions else False
 
     result = APITestResult(
         api_name=api_name,

{mcp_api_test-0.1.2 → mcp_api_test-0.1.3}/src/utils.py

@@ -31,16 +31,19 @@ def render_console_template_result(result: APITestResult) -> str:
     lines.append("Assertions")
     lines.append(divider)
 
-    for assertion in result.assertions:
-        symbol = "✓" if assertion.passed else "x"
-        lines.append(f"{symbol} {assertion.assertion}")
-
-    lines.append("")
-    lines.append("Summary")
-    lines.append(divider)
-    lines.append(f"Total Assertions : {len(result.assertions)}")
-    lines.append(f"Passed           : {passed_assertions}")
-    lines.append(f"Failed           : {failed_assertions}")
+    if result.assertions:
+        for assertion in result.assertions:
+            symbol = "✓" if assertion.passed else "x"
+            lines.append(f"{symbol} {assertion.assertion}")
+
+        lines.append("")
+        lines.append("Summary")
+        lines.append(divider)
+        lines.append(f"Total Assertions : {len(result.assertions)}")
+        lines.append(f"Passed           : {passed_assertions}")
+        lines.append(f"Failed           : {failed_assertions}")
+    else:
+        lines.append("  (no assertions provided)")
 
     return "\n".join(lines)