mcp-api-test 0.2.0__tar.gz → 0.3.0__tar.gz

{mcp_api_test-0.2.0/src/mcp_api_test.egg-info → mcp_api_test-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-api-test
-Version: 0.2.0
+Version: 0.3.0
 Summary: MCP server for testing REST API with built-in assertions
 Author: Ryan Febriansyah
 License-Expression: MIT
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -40,7 +41,7 @@ Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a *
 
 It complements (rather than replaces) tools like pytest, Postman, and Playwright.
 
-> **Breaking changes in v0.2.0.** The server now runs on `mcp` 2.x, and the package layout moved from flat top-level modules to a proper `mcp_api_test` package. If you import internals directly, you may update to `from mcp_api_test.server import ...`. MCP client configuration (OpenCode, Claude Desktop, Claude Code) is unaffected. See the [changelog](docs/changelog.md) for details.
+> **Breaking changes in v0.2.0.** The server now runs on `mcp` 2.x, and the package layout moved from flat top-level modules to a proper `mcp_api_test` package. If you import internals directly, you may update to `from mcp_api_test.server import ...`. MCP client configuration (OpenCode, Claude Desktop, Claude Code) is unaffected. See the [changelog](https://ryaneatfood.gitlab.io/mcp-api-testing/changelog/) for details.
 
 ## Use cases
 
@@ -105,10 +106,10 @@ The agent invokes `run_test_api`, validates against the expected contract, and r
 
 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
+- **[Getting Started](https://ryaneatfood.gitlab.io/mcp-api-testing/getting-started/installation/)**: installation and client setup
+- **[Usage](https://ryaneatfood.gitlab.io/mcp-api-testing/usage/request-modes/)**: cURL mode, structured mode, assertions, response format
+- **[Guides](https://ryaneatfood.gitlab.io/mcp-api-testing/guides/troubleshooting/)**: troubleshooting, development, configuration
+- **[Reference](https://ryaneatfood.gitlab.io/mcp-api-testing/reference/tool-parameters/)**: full parameter reference
 
 ## License
 

{mcp_api_test-0.2.0 → mcp_api_test-0.3.0}/README.md

@@ -8,7 +8,7 @@ Unlike traditional testing frameworks, `mcp-api-test` exposes API testing as a *
 
 It complements (rather than replaces) tools like pytest, Postman, and Playwright.
 
-> **Breaking changes in v0.2.0.** The server now runs on `mcp` 2.x, and the package layout moved from flat top-level modules to a proper `mcp_api_test` package. If you import internals directly, you may update to `from mcp_api_test.server import ...`. MCP client configuration (OpenCode, Claude Desktop, Claude Code) is unaffected. See the [changelog](docs/changelog.md) for details.
+> **Breaking changes in v0.2.0.** The server now runs on `mcp` 2.x, and the package layout moved from flat top-level modules to a proper `mcp_api_test` package. If you import internals directly, you may update to `from mcp_api_test.server import ...`. MCP client configuration (OpenCode, Claude Desktop, Claude Code) is unaffected. See the [changelog](https://ryaneatfood.gitlab.io/mcp-api-testing/changelog/) for details.
 
 ## Use cases
 
@@ -73,10 +73,10 @@ The agent invokes `run_test_api`, validates against the expected contract, and r
 
 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
+- **[Getting Started](https://ryaneatfood.gitlab.io/mcp-api-testing/getting-started/installation/)**: installation and client setup
+- **[Usage](https://ryaneatfood.gitlab.io/mcp-api-testing/usage/request-modes/)**: cURL mode, structured mode, assertions, response format
+- **[Guides](https://ryaneatfood.gitlab.io/mcp-api-testing/guides/troubleshooting/)**: troubleshooting, development, configuration
+- **[Reference](https://ryaneatfood.gitlab.io/mcp-api-testing/reference/tool-parameters/)**: full parameter reference
 
 ## License
 

{mcp_api_test-0.2.0 → mcp_api_test-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-api-test"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server for testing REST API with built-in assertions"
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
 ]
 
 [project.scripts]

{mcp_api_test-0.2.0 → mcp_api_test-0.3.0}/src/mcp_api_test/__init__.py

@@ -1,3 +1,3 @@
 """Lightweight MCP for REST API testing for Claude Desktop and OpenCode"""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

mcp_api_test-0.3.0/src/mcp_api_test/assertions.py

@@ -0,0 +1,192 @@
+"""
+Assertion evaluation for a completed HTTP response.
+
+``evaluate_assertions`` is the single entry point: it takes the response, the
+parsed body and the measured time, and returns one ``AssertionResult`` per
+requested check. It never raises for a failed check, a mismatch is reported as
+``passed=False`` with the expected and actual values, so the caller can render
+every failure at once instead of stopping at the first one.
+"""
+
+import json
+import httpx
+from typing import Any, Dict, List, Optional, Tuple
+from .models import AssertionResult
+from .utils import get_nested_fields, get_nested_value
+
+
+def values_equal(expected: Any, actual: Any) -> bool:
+    """
+    Compare an expected JSON value with the actual one.
+
+    Same as ``==`` except that a boolean never equals a number: in Python
+    ``True == 1`` and ``False == 0``, but in JSON they are different types, so
+    an assertion of ``{"ok": true}`` must not pass against ``{"ok": 1}``.
+    Nested dicts and lists are compared with plain ``==``.
+    """
+    if isinstance(expected, bool) != isinstance(actual, bool):
+        return False
+    return bool(expected == actual)
+
+
+def body_as_text(body: Any) -> str:
+    """
+    Serialize a response body into the text the substring assertions search.
+
+    Dicts and lists become JSON (with real double quotes, and non-ASCII
+    characters kept as-is rather than ``\\uXXXX`` escapes). Anything else, such
+    as a plain-text body, is returned as ``str``.
+    """
+    return (
+        json.dumps(body, ensure_ascii=False)
+        if isinstance(body, (dict, list))
+        else str(body)
+    )
+
+
+def evaluate_assertions(
+    response: httpx.Response,
+    body: Any,
+    response_time_ms: float,
+    *,
+    status_code: Optional[int] = None,
+    status_range: Optional[Tuple[str, Tuple[int, int]]] = None,
+    fields: Optional[List[str]] = None,
+    values: Optional[Dict[str, Any]] = None,
+    headers: Optional[Dict[str, str]] = None,
+    contains: Optional[str] = None,
+    not_contains: Optional[str] = None,
+    max_time_ms: Optional[float] = None,
+) -> List[AssertionResult]:
+    """
+    Run every requested assertion independently and return one result each.
+
+    Only the checks whose argument is given are run, so with no keyword
+    arguments the result is an empty list. Results keep a stable order:
+    status code, status range, fields, values, headers, contains,
+    not-contains, then response time.
+
+    Args:
+        response: The completed response, used for the status code and headers.
+        body: The parsed response body, JSON when it parsed, otherwise raw text.
+        response_time_ms: How long the request took, in milliseconds.
+        status_code: Exact status code the response must have.
+        status_range: ``(label, (low, high))`` inclusive range the status code
+            must fall in. The label (for example ``"2xx"``) is only used for
+            reporting.
+        fields: Dot-notation paths that must exist. For a JSON array body, a
+            path passes when at least one item has it. For a non-JSON body the
+            entry is matched as a plain substring.
+        values: Dot-notation path to exact expected value. Numeric path parts
+            index into lists (``items.0.id``). A missing path fails, even when
+            the expected value is ``None``. One result is produced per path.
+        headers: Header name to expected text. Names are case-insensitive and
+            the value passes when it *contains* the expected text, ignoring
+            case, so ``"application/json"`` matches
+            ``"application/json; charset=utf-8"``. An empty string only checks
+            that the header is present. One result is produced per header.
+        contains: Text the serialized body must contain.
+        not_contains: Text the serialized body must not contain.
+        max_time_ms: Upper limit, inclusive, for ``response_time_ms``.
+
+    Returns:
+        One ``AssertionResult`` per check. ``expected`` and ``actual`` are set
+        so a failure can be explained without re-running the request.
+    """
+    results: List[AssertionResult] = []
+    actual_status = response.status_code
+
+    if status_code is not None:
+        results.append(
+            AssertionResult(
+                "status_code", actual_status == status_code, status_code, actual_status
+            )
+        )
+
+    if status_range is not None:
+        label, (low, high) = status_range
+        results.append(
+            AssertionResult(
+                "status_code_range", low <= actual_status <= high, label, actual_status
+            )
+        )
+
+    for field in fields or []:
+        if isinstance(body, dict):
+            exists = get_nested_fields(body=body, field_path=field)
+        elif isinstance(body, list):
+            # For JSON arrays, check whether at least one item
+            # (if dict) contains the expected field.
+            exists = any(
+                (
+                    get_nested_fields(body=item, field_path=field)
+                    if isinstance(item, dict)
+                    else field in str(item)
+                )
+                for item in body
+            )
+        else:
+            # Scalar or plain-text response like substring match.
+            exists = field in str(body)
+        results.append(
+            AssertionResult(
+                "response_field_exist",
+                exists,
+                field,
+                "field is present" if exists else "field is missing",
+            )
+        )
+
+    for path, expected in (values or {}).items():
+        found, actual = get_nested_value(body, path)
+        results.append(
+            AssertionResult(
+                f"response_value:{path}",
+                found and values_equal(expected, actual),
+                expected,
+                actual if found else "field is missing",
+            )
+        )
+
+    for name, expected in (headers or {}).items():
+        actual_header = response.headers.get(name)
+        # header exists and its value contains the expected text, so that
+        # "application/json" also matches "application/json; charset=utf-8"
+        ok = actual_header is not None and expected.lower() in actual_header.lower()
+        results.append(
+            AssertionResult(
+                f"response_header:{name.lower()}",
+                ok,
+                expected,
+                actual_header if actual_header is not None else "header is missing",
+            )
+        )
+
+    if contains is not None:
+        results.append(
+            AssertionResult(
+                "response_contains", contains in body_as_text(body), contains, None
+            )
+        )
+
+    if not_contains is not None:
+        results.append(
+            AssertionResult(
+                "response_not_contains",
+                not_contains not in body_as_text(body),
+                not_contains,
+                None,
+            )
+        )
+
+    if max_time_ms is not None:
+        results.append(
+            AssertionResult(
+                "max_response_time_ms",
+                response_time_ms <= max_time_ms,
+                f"<= {max_time_ms:g}",
+                round(response_time_ms, 2),
+            )
+        )
+
+    return results

{mcp_api_test-0.2.0 → mcp_api_test-0.3.0}/src/mcp_api_test/flags.py

@@ -12,7 +12,7 @@ CURL_VALUE_FLAGS: dict[str, str] = {
     "--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",
+    "-u": "user",  # basic auth, applied via httpx.BasicAuth
     "--user": "user",
     "--url": "url_flag",  # explicit --url form
     "-A": "user_agent",
@@ -53,9 +53,4 @@ CURL_BOOLEAN_FLAGS: set[str] = {
 
 # 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",
-}
+CURL_WARN_FLAGS: dict[str, str] = {}

{mcp_api_test-0.2.0 → mcp_api_test-0.3.0}/src/mcp_api_test/models.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from typing import List, Any
+from typing import Dict, List, Any, Optional
 
 
 @dataclass
@@ -20,3 +20,4 @@ class APITestResult:
     response_time_ms: float
     assertions: List[AssertionResult] = field(default_factory=list)
     response_body: Any = None
+    response_headers: Optional[Dict[str, str]] = None