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

{mcp_api_test-0.2.1/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.1
+Version: 0.3.0
 Summary: MCP server for testing REST API with built-in assertions
 Author: Ryan Febriansyah
 License-Expression: MIT

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

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-api-test"
-version = "0.2.1"
+version = "0.3.0"
 description = "MCP server for testing REST API with built-in assertions"
 readme = "README.md"
 license = "MIT"

{mcp_api_test-0.2.1 → 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.1"
+__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.1 → 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

{mcp_api_test-0.2.1 → mcp_api_test-0.3.0}/src/mcp_api_test/server.py

@@ -7,13 +7,17 @@ from urllib.parse import urlparse
 from typing import Optional, Dict, Any, List, Union
 from mcp.server.mcpserver import MCPServer
 from .logger import get_logger
-from .models import APITestResult, AssertionResult
+from .assertions import evaluate_assertions
+from .models import APITestResult
 from .utils import (
+    DEFAULT_MAX_BODY_CHARS,
+    OUTPUT_FORMATS,
     render_console_template_result,
     render_error_result,
+    render_json_result,
     build_fullpath_url,
+    expand_env,
     redact_curl,
-    get_nested_fields,
 )
 from .flags import CURL_BOOLEAN_FLAGS, CURL_VALUE_FLAGS, CURL_WARN_FLAGS
 
@@ -191,10 +195,21 @@ async def run_test_api(
     method: str = "GET",
     headers: Optional[Dict[str, str]] = None,
     payload: Optional[Union[Dict[str, Any], List[Any]]] = None,
+    query_params: Optional[Dict[str, Any]] = None,
+    timeout: float = 30,
+    follow_redirects: bool = False,
+    verify_tls: bool = True,
     required_status_code: Optional[int] = None,
     required_status_code_range: Optional[str] = None,
     required_response_fields: Optional[List[str]] = None,
+    required_response_values: Optional[Dict[str, Any]] = None,
+    required_response_headers: Optional[Dict[str, str]] = None,
     required_response_contains: Optional[str] = None,
+    response_not_contains: Optional[str] = None,
+    max_response_time_ms: Optional[float] = None,
+    include_response_headers: bool = False,
+    max_body_chars: int = DEFAULT_MAX_BODY_CHARS,
+    output_format: str = "text",
 ) -> str:
     """
     Test a given API services, it will supports either:
@@ -202,21 +217,38 @@ async def run_test_api(
     1. Shared cURL command and it will be structured
     2. Or, pre-defined structured requests data
 
+    Use ``${ENV_VAR}`` in the cURL command, URL, headers, query params or
+    payload to inject secrets from the server environment (or its .env file)
+    without handling them directly.
+
     Example prompt:
     `Please test this API based on this cURL, ensure status
     code is 2xx, and response contains 'id'`
     """
+    # log the command before env expansion so secrets never reach the log
     logger.info(
         message=f"Testing API: {api_name} with cURL: {redact_curl(curl_command) if curl_command else None}"
     )
-    follow_redirects = False
-    verify_tls = True
+    fmt = output_format if output_format in OUTPUT_FORMATS else "text"
     auth: Optional[tuple[str, str]] = None
-    status_range = (0, 0)
+    status_range: Optional[tuple[str, tuple[int, int]]] = None
 
     try:
+        if output_format not in OUTPUT_FORMATS:
+            raise ValueError(f"`output_format` must be one of {OUTPUT_FORMATS}")
+        if max_body_chars < 0:
+            raise ValueError("`max_body_chars` must be >= 0")
         if required_status_code_range is not None:
-            status_range = parse_status_code_range(required_status_code_range)
+            status_range = (
+                required_status_code_range,
+                parse_status_code_range(required_status_code_range),
+            )
+        curl_command = expand_env(curl_command)
+        base_url = expand_env(base_url)
+        endpoint = expand_env(endpoint)
+        headers = expand_env(headers)
+        payload = expand_env(payload)
+        query_params = expand_env(query_params)
         if curl_command:
             parsed = parse_curl_command(command=curl_command)
         elif not base_url or not endpoint:
@@ -230,6 +262,7 @@ async def run_test_api(
             method=method.upper(),
             url=base_url or "",
             error=f"ValueError: {e}",
+            output_format=fmt,
         )
 
     if curl_command:
@@ -238,13 +271,16 @@ async def run_test_api(
         endpoint = parsed["endpoint"]
         headers = parsed["headers"]
         payload = parsed["request_payload"]
-        follow_redirects = parsed["follow_redirects"]
-        verify_tls = parsed["verify_tls"]
+        # cURL flags (-L, -k) switch the option, the parameters set the default
+        follow_redirects = follow_redirects or parsed["follow_redirects"]
+        verify_tls = verify_tls and parsed["verify_tls"]
         auth = parsed["auth"]
 
     assert base_url and endpoint  # validated above
 
     full_path_url = build_fullpath_url(base_url=base_url, endpoint=endpoint)
+    if query_params:
+        full_path_url = str(httpx.URL(full_path_url).copy_merge_params(query_params))
     method = method.upper()
 
     content: Optional[str] = None
@@ -261,7 +297,7 @@ async def run_test_api(
     start_time = time.perf_counter()
     try:
         async with httpx.AsyncClient(
-            timeout=30, follow_redirects=follow_redirects, verify=verify_tls
+            timeout=timeout, follow_redirects=follow_redirects, verify=verify_tls
         ) as client:
             response = await client.request(
                 method=method,
@@ -278,7 +314,11 @@ async def run_test_api(
             message=f"Error occurred while testing API: {api_name}, error: {str(e)}"
         )
         return render_error_result(
-            api_name=api_name, method=method, url=full_path_url, error=str(e)
+            api_name=api_name,
+            method=method,
+            url=full_path_url,
+            error=str(e),
+            output_format=fmt,
         )
 
     try:
@@ -289,87 +329,23 @@ async def run_test_api(
         )
         resp_body = response.text
 
-    assertions: List[Dict[str, Any]] = []
-
-    if required_status_code is not None:
-        passed = response.status_code == required_status_code
-        assertions.append(
-            {
-                "assertion": "status_code",
-                "expected": required_status_code,
-                "actual": response.status_code,
-                "passed": passed,
-            }
-        )
-
-    if required_status_code_range is not None:
-        # low refers to 1xx - 2xx and high refers to 3xx - 5xx
-        low, high = status_range
-        passed = low <= response.status_code <= high
-        assertions.append(
-            {
-                "assertion": "status_code_range",
-                "expected": required_status_code_range,
-                "actual": response.status_code,
-                "passed": passed,
-            }
-        )
-
-    if required_response_fields:
-        for field in required_response_fields:
-            if isinstance(resp_body, dict):
-                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(
-                {
-                    "assertion": "response_field_exist",
-                    "field": field,
-                    "passed": is_exist,
-                    "expected": field,
-                    "actual": "field is present" if is_exist else "field is missing",
-                }
-            )
-
-    if required_response_contains is not None:
-        body_str = (
-            json.dumps(resp_body) if isinstance(resp_body, dict) else str(resp_body)
-        )
-        found = required_response_contains in body_str
-        assertions.append(
-            {
-                "assertion": "response_contains",
-                "expected": required_response_contains,
-                "passed": found,
-            }
-        )
-
-    assertion_objects = []
-    for a in assertions:
-        assertion_objects.append(
-            AssertionResult(
-                assertion=a["assertion"],
-                passed=a["passed"],
-                expected=a.get("expected"),
-                actual=a.get("actual"),
-            )
-        )
+    assertions = evaluate_assertions(
+        response,
+        resp_body,
+        response_time_ms,
+        status_code=required_status_code,
+        status_range=status_range,
+        fields=required_response_fields,
+        values=required_response_values,
+        headers=required_response_headers,
+        contains=required_response_contains,
+        not_contains=response_not_contains,
+        max_time_ms=max_response_time_ms,
+    )
 
     # 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
+    overall_result = all(a.passed for a in assertions) if assertions else False
 
     result = APITestResult(
         api_name=api_name,
@@ -378,12 +354,15 @@ async def run_test_api(
         url=full_path_url,
         status_code=response.status_code,
         response_time_ms=response_time_ms,
-        assertions=assertion_objects,
+        assertions=assertions,
         response_body=resp_body,
+        response_headers=dict(response.headers) if include_response_headers else None,
     )
 
     logger.info(message="Finished testing API, now returning the result to MCP core...")
-    return render_console_template_result(result=result)
+    if fmt == "json":
+        return render_json_result(result=result, max_body_chars=max_body_chars)
+    return render_console_template_result(result=result, max_body_chars=max_body_chars)
 
 
 # expose this function so it can be called in toml files

mcp_api_test-0.3.0/src/mcp_api_test/utils.py

@@ -0,0 +1,206 @@
+"""Utility functions for MCP API testing"""
+
+import json
+import os
+import re
+from typing import Any, Optional, Tuple
+from .models import APITestResult
+
+DEFAULT_MAX_BODY_CHARS = 2000
+OUTPUT_FORMATS = ("text", "json")
+
+_SENSITIVE_HEADER = re.compile(
+    r"(?i)((?:proxy-)?authorization|cookie|set-cookie|x-api-key|x-auth-token)"
+    r"(\s*:\s*)[^'\"]*"
+)
+_USER_FLAG = re.compile(r"(?i)(\s(?:-u|--user)[\s=])(?:'[^']*'|\"[^\"]*\"|\S+)")
+_ENV_VAR = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def redact_curl(command: str) -> str:
+    """
+    Mask credentials (auth headers, cookies, -u user:pass) in a cURL command
+    so it is safe to write to the log file
+    """
+    command = _SENSITIVE_HEADER.sub(r"\1\2***", command)
+    return _USER_FLAG.sub(r"\1***", command)
+
+
+def expand_env(value: Any) -> Any:
+    """
+    Replace ``${VAR}`` with the value of the environment variable VAR, walking
+    through nested dicts and lists. Raises ``ValueError`` when VAR is not set, so
+    a literal ``${TOKEN}`` is never sent to the server by accident
+    """
+    if isinstance(value, str):
+
+        def _sub(match: "re.Match[str]") -> str:
+            name = match.group(1)
+            if name not in os.environ:
+                raise ValueError(f"Environment variable '{name}' is not set")
+            return os.environ[name]
+
+        return _ENV_VAR.sub(_sub, value)
+    if isinstance(value, dict):
+        return {k: expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env(v) for v in value]
+    return value
+
+
+def _compact(value: Any) -> str:
+    """Serialize without padding whitespace, to spend as few tokens as possible"""
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def _body_text(body: Any, limit: int) -> str:
+    text = body if isinstance(body, str) else _compact(body)
+    if len(text) > limit:
+        text = text[:limit] + f"...[truncated {len(text) - limit} chars]"
+    return text
+
+
+def render_console_template_result(
+    result: APITestResult, max_body_chars: int = DEFAULT_MAX_BODY_CHARS
+) -> str:
+    """
+    Render the test result as compact text. Passing assertions are listed by
+    name only, failing ones carry the expected and actual values.
+
+    ``max_body_chars`` truncates the response body, 0 omits it entirely
+    """
+    status = "PASS" if result.passed else "FAIL"
+    head = (
+        f"[{status}] {result.api_name} | {result.method} {result.url}"
+        f" | {result.status_code} | {result.response_time_ms:.0f}ms"
+    )
+    lines = [head]
+
+    if result.assertions:
+        passed = sum(1 for a in result.assertions if a.passed)
+        lines[0] += f" | {passed}/{len(result.assertions)} assertions"
+        for a in result.assertions:
+            if a.passed:
+                lines.append(f"ok {a.assertion}")
+            else:
+                lines.append(
+                    f"FAIL {a.assertion}: expected {a.expected!r}, actual {a.actual!r}"
+                )
+    else:
+        lines.append("no assertions provided")
+
+    if result.response_headers:
+        lines.append("headers:")
+        lines.extend(f"  {k}: {v}" for k, v in result.response_headers.items())
+
+    if max_body_chars > 0:
+        lines.append("body: " + _body_text(result.response_body, max_body_chars))
+
+    return "\n".join(lines)
+
+
+def render_json_result(
+    result: APITestResult, max_body_chars: int = DEFAULT_MAX_BODY_CHARS
+) -> str:
+    """
+    Render the test result as a single line of compact JSON
+    """
+    data: dict[str, Any] = {
+        "api_name": result.api_name,
+        "passed": result.passed,
+        "method": result.method,
+        "url": result.url,
+        "status_code": result.status_code,
+        "response_time_ms": round(result.response_time_ms, 2),
+        "assertions": [
+            {
+                "assertion": a.assertion,
+                "passed": a.passed,
+                "expected": a.expected,
+                "actual": a.actual,
+            }
+            for a in result.assertions
+        ],
+    }
+    if result.response_headers:
+        data["response_headers"] = result.response_headers
+    if max_body_chars > 0:
+        body = result.response_body
+        # keep the parsed object when it fits, otherwise fall back to
+        # a truncated string
+        oversized = (
+            len(body if isinstance(body, str) else _compact(body)) > max_body_chars
+        )
+        data["response_body"] = _body_text(body, max_body_chars) if oversized else body
+    return _compact(data)
+
+
+def render_error_result(
+    api_name: str,
+    method: str,
+    url: str,
+    error: str,
+    output_format: str = "text",
+) -> str:
+    """
+    Render a runtime error in the same format as a successful result
+    """
+    if output_format == "json":
+        return _compact(
+            {
+                "api_name": api_name,
+                "passed": False,
+                "method": method,
+                "url": url,
+                "error": error,
+            }
+        )
+    return f"[ERROR] {api_name} | {method} {url}\nerror: {error}"
+
+
+def get_nested_value(body: Any, field_path: str) -> Tuple[bool, Any]:
+    """
+    Resolve a dot-notation path (numeric parts index into lists, for example
+    ``items.0.name``). Returns ``(found, value)``
+    """
+    current = body
+    for part in field_path.split("."):
+        if isinstance(current, dict):
+            if part not in current:
+                return False, None
+            current = current[part]
+        elif isinstance(current, list):
+            try:
+                current = current[int(part)]
+            except (ValueError, IndexError):
+                return False, None
+        else:
+            # can't descend further
+            return False, None
+    return True, current
+
+
+def get_nested_fields(body: Any, field_path: str) -> bool:
+    """
+    Utility functions to check whether a dot-notation field path exists
+    in the nested structure
+    """
+    return get_nested_value(body, field_path)[0]
+
+
+def build_fullpath_url(base_url: str, endpoint: str) -> str:
+    """
+    Safely join base_url and endpoint without double "//" or incorrectly
+    dropped a particular path segments
+    """
+    base = base_url.strip("/")
+    _endpoint = endpoint.strip()
+
+    if not _endpoint:
+        _endpoint = "/"
+
+    if not _endpoint.startswith("/"):
+        # automaticaly prepend the '/' before raise an assertion
+        _endpoint = "/" + _endpoint
+
+    return base + _endpoint

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-api-test
-Version: 0.2.1
+Version: 0.3.0
 Summary: MCP server for testing REST API with built-in assertions
 Author: Ryan Febriansyah
 License-Expression: MIT