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

mcp_api_test-0.1.4/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: mcp-api-test
+Version: 0.1.4
+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<2.0.0,>=1.0.0
+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) ![PyPI License](https://img.shields.io/pypi/l/mcp-api-test) ![PyPI Python Version](https://img.shields.io/pypi/pyversions/mcp-api-test)
+
+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 this [page](https://ryaneatfood.gitlab.io/mcp-api-testing/), and another way to navigate the docs:
+
+- **[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.4/README.md

@@ -0,0 +1,81 @@
+# mcp-api-test
+
+![pipeline](https://gitlab.com/ryaneatfood/mcp-api-testing/badges/master/pipeline.svg) ![PyPI License](https://img.shields.io/pypi/l/mcp-api-test) ![PyPI Python Version](https://img.shields.io/pypi/pyversions/mcp-api-test)
+
+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 this [page](https://ryaneatfood.gitlab.io/mcp-api-testing/), and another way to navigate the docs:
+
+- **[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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-api-test"
-version = "0.1.2"
+version = "0.1.4"
 description = "MCP server for testing REST API with built-in assertions"
 readme = "README.md"
 license = "MIT"
@@ -10,7 +10,7 @@ authors = [
 
 requires-python = ">=3.10"
 dependencies = [
-  "mcp",
+  "mcp>=1.0.0,<2.0.0",
   "httpx",
   "python-dotenv"
 ]
@@ -39,7 +39,8 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
-py-modules = ["server", "__main__", "logger", "models", "utils"]
+py-modules = ["server", "__main__", "logger", "models", "utils", "flags"]
 
 [project.optional-dependencies]
-dev = ["pytest", "pytest-asyncio", "respx"]
+dev = ["pytest", "pytest-asyncio", "respx"]
+docs = ["mkdocs-material"]

mcp_api_test-0.1.4/src/flags.py

@@ -0,0 +1,61 @@
+"""A collection of curl flag which is being used during HTTP request/inspection"""
+
+# flags that consume the next token as their value,
+# maps every recognize consuming flag to its semantic roles
+CURL_VALUE_FLAGS: dict[str, str] = {
+    "-X": "method",
+    "--request": "method",
+    "-H": "header",
+    "--header": "header",
+    "-d": "data",
+    "--data": "data",
+    "--data-raw": "data",  # browser DevTools "Copy as cURL" uses this
+    "--data-binary": "data",  # common in API clients
+    "--data-urlencode": "data",  # URL-encoded payloads
+    "-u": "user",
+    "--user": "user",
+    "--url": "url_flag",  # explicit --url form
+    "-A": "user_agent",
+    "--user-agent": "user_agent",
+    "--max-time": "ignored",
+    "--connect-timeout": "ignored",
+    "-o": "ignored",
+    "--output": "ignored",
+    "--proxy": "ignored",
+    "-x": "ignored",
+    "-e": "ignored",
+    "--referer": "ignored",
+}
+
+# standalone flags with no following value
+CURL_BOOLEAN_FLAGS: dict[str, str] = {
+    "-L",
+    "--location",  # follow redirects, very common in browser exports
+    "-k",
+    "--insecure",  # skip TLS verification
+    "-s",
+    "--silent",
+    "-v",
+    "--verbose",
+    "-i",
+    "--include",
+    "-I",
+    "--head",
+    "--compressed",  # added by Chrome DevTools
+    "--http1.1",
+    "--http2",
+    "-G",
+    "--get",
+    "--no-keepalive",
+    "--fail",
+    "-f",
+}
+
+# flags that we recognize but want to surface with a warning for,
+# emit a logger.warning with a human-readable explanation
+CURL_WARN_FLAGS: dict[str, str] = {
+    "-k": "--insecure is not supported: TLS verification will still be enforced",
+    "--insecure": "--insecure is not supported: TLS verification will still be enforced",
+    "-u": "-u/--user (basic auth) is not supported: add an Authorization header explicitly",
+    "--user": "-u/--user (basic auth) is not supported: add an Authorization header explicitly",
+}

{mcp_api_test-0.1.2 → mcp_api_test-0.1.4}/src/logger.py

@@ -39,6 +39,14 @@ class Logger:
             message = message % args
         self.logger.info(message, **kwargs)
 
+    def warning(self, message: str, *args, **kwargs) -> None:
+        """
+        Log a warning message with particular arguments
+        """
+        if args:
+            message = message % args
+        self.logger.warning(message, **kwargs)
+
     def error(self, message: str, *args, **kwargs) -> None:
         """
         Log an error message with particular arguments

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

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: mcp-api-test
+Version: 0.1.4
+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<2.0.0,>=1.0.0
+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) ![PyPI License](https://img.shields.io/pypi/l/mcp-api-test) ![PyPI Python Version](https://img.shields.io/pypi/pyversions/mcp-api-test)
+
+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 this [page](https://ryaneatfood.gitlab.io/mcp-api-testing/), and another way to navigate the docs:
+
+- **[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.4}/src/mcp_api_test.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ MANIFEST.in
 README.md
 pyproject.toml
 src/__main__.py
+src/flags.py
 src/logger.py
 src/models.py
 src/server.py
@@ -14,5 +15,7 @@ src/mcp_api_test.egg-info/entry_points.txt
 src/mcp_api_test.egg-info/requires.txt
 src/mcp_api_test.egg-info/top_level.txt
 tests/test_mcp_api_tools.py
+tests/test_packaging.py
 tests/test_parse_curl_command.py
-tests/test_parse_status_code.py
+tests/test_parse_status_code.py
+tests/test_utils.py

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

@@ -1,4 +1,4 @@
-mcp
+mcp<2.0.0,>=1.0.0
 httpx
 python-dotenv
 
@@ -6,3 +6,6 @@ python-dotenv
 pytest
 pytest-asyncio
 respx
+
+[docs]
+mkdocs-material

{mcp_api_test-0.1.2 → mcp_api_test-0.1.4}/src/mcp_api_test.egg-info/top_level.txt

@@ -1,4 +1,5 @@
 __main__
+flags
 logger
 models
 server

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

@@ -80,7 +80,7 @@ def parse_curl_command(command: str) -> Dict[str, Any]:
 
             # emit warning for supported but warnin changing flags
             if token in CURL_WARN_FLAGS:
-                logger.warning(message=f"[curl parser] {CURL_WARN_FLAGS[token]}`")
+                logger.warning(message=f"[curl parser] {CURL_WARN_FLAGS[token]}")
 
             if role == "method":
                 method = value
@@ -96,11 +96,13 @@ def parse_curl_command(command: str) -> Dict[str, Any]:
                     payload = json.loads(raw_data)
                 except json.JSONDecodeError:
                     logger.error(
-                        f"[curl parser] payload for '{token} is not valid JSON"
+                        f"[curl parser] payload for '{token}' is not valid JSON"
                     )
                     payload = raw_data
             elif role == "url_flag":
                 url = value
+            elif role == "user_agent":
+                headers["User-Agent"] = value
 
             # everything else is consumed silently
             index += 2
@@ -109,7 +111,7 @@ def parse_curl_command(command: str) -> Dict[str, Any]:
         # boolean standalone flags
         if token in CURL_BOOLEAN_FLAGS:
             if token in CURL_WARN_FLAGS:
-                logger.info(f"[curl parser] {CURL_WARN_FLAGS[token]}")
+                logger.warning(message=f"[curl parser] {CURL_WARN_FLAGS[token]}")
             index += 1
             continue
 
@@ -193,10 +195,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 +252,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 +301,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.4}/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)
 
@@ -105,7 +108,7 @@ def build_fullpath_url(base_url: str, endpoint: str) -> str:
     _endpoint = endpoint.strip()
 
     if not _endpoint:
-        endpoint = "/"
+        _endpoint = "/"
 
     if not _endpoint.startswith("/"):
         # automaticaly prepend the '/' before raise an assertion

mcp_api_test-0.1.4/tests/test_packaging.py

@@ -0,0 +1,46 @@
+"""Static checks that the source layout matches the wheel packaging config"""
+
+import tomllib
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC_DIR = PROJECT_ROOT / "src"
+
+
+def _packaged_modules() -> list[str]:
+    with open(PROJECT_ROOT / "pyproject.toml", "rb") as f:
+        config = tomllib.load(f)
+    return config["tool"]["setuptools"]["py-modules"]
+
+
+def _project_version() -> str:
+    with open(PROJECT_ROOT / "pyproject.toml", "rb") as f:
+        config = tomllib.load(f)
+    return config["project"]["version"]
+
+
+def test_all_src_modules_are_packaged():
+    src_modules = {
+        p.stem
+        for p in SRC_DIR.glob("*.py")
+        if p.name != "__init__.py" and not p.name.startswith("__")
+    }
+    missing = src_modules - set(_packaged_modules())
+    assert not missing, (
+        f"Modules in src/ that are missing from pyproject.toml "
+        f"[tool.setuptools] py-modules: {sorted(missing)}"
+    )
+
+
+def test_packaged_modules_exist_in_src():
+    for module in _packaged_modules():
+        assert (
+            SRC_DIR / f"{module}.py"
+        ).exists(), f"'{module}' is listed in py-modules but has no src/{module}.py"
+
+
+def test_version_matches_pyproject():
+    # regression: src/__init__.py __version__ drifted from pyproject.toml
+    import src
+
+    assert src.__version__ == _project_version()