LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
"""Guards that turn a malformed request into something the agent can act on.
Three layers, each covered here because each was added or changed without
coverage and each fails invisibly:
* ``valid_uuid`` — rejects an unparseable id *before* it reaches a UUID-typed
ORM filter, where Django's field would raise ``ValidationError`` ahead of the
call site's own ``is None`` check.
* the transport's JSON-RPC envelope guards — malformed body, non-object
``params``, and a preflight that raises something unexpected. Each exists to
stop a Django 500 reaching a client that is parsing for an envelope.
* the platform view's CSRF gate — exempting only bearer-authenticated requests.
"""
from __future__ import annotations
import json
from unittest.mock import MagicMock, patch
from django.test import SimpleTestCase
from rest_framework.test import APIRequestFactory
from mcp_server.constants import JSONRPC
from mcp_server.exceptions import MCPToolError
from mcp_server.registry import MCPTool, MCPToolRegistry
from mcp_server.sanitize import valid_uuid
from mcp_server.transport import BaseMCPView
GOOD_UUID = "88888888-8888-8888-8888-888888888888"
class ValidUuidTest(SimpleTestCase):
def test_a_valid_uuid_passes_through_unchanged(self) -> None:
assert valid_uuid(GOOD_UUID, "execution id", "hint") == GOOD_UUID
def test_malformed_ids_are_agent_errors(self) -> None:
for bad in ("not-a-uuid", "", "1234", None, 42):
with self.subTest(bad):
with self.assertRaises(MCPToolError) as caught:
valid_uuid(bad, "execution id", "Call listExecutions.")
message = str(caught.exception)
assert "not a valid execution id" in message
# The hint is what makes this actionable rather than just a
# refusal, so it is part of the contract.
assert "Call listExecutions." in message
def test_the_field_name_and_hint_reach_the_message(self) -> None:
with self.assertRaises(MCPToolError) as caught:
valid_uuid("x", "pipeline id", "Call listPipelines to see valid ids.")
assert "pipeline id" in str(caught.exception)
assert "listPipelines" in str(caught.exception)
class ExecutionScopeGuardTest(SimpleTestCase):
"""The call site refuses before touching the ORM."""
def test_a_malformed_execution_id_never_reaches_the_filter(self) -> None:
from mcp_server.tools.execution import get_execution_status
context = MagicMock()
context.api.workflow_id = "wf"
with (
patch(
"mcp_server.tools.execution.WorkflowExecution.objects.filter"
) as scope_filter,
patch(
"mcp_server.tools.execution.ExecutionQuerySerializer.is_valid",
return_value=True,
),
patch(
"mcp_server.tools.execution.ExecutionQuerySerializer.validated_data",
{
"execution_id": "not-a-uuid",
"include_metadata": False,
"include_metrics": False,
"include_extracted_text": False,
},
),
):
with self.assertRaises(MCPToolError):
get_execution_status(context, execution_id="not-a-uuid")
scope_filter.assert_not_called()
class TransportEnvelopeGuardTest(SimpleTestCase):
"""Malformed input comes back as JSON-RPC, never as a Django error page."""
def _view(self, registry=None):
reg = registry or MCPToolRegistry()
class Probe(BaseMCPView):
authentication_classes: list = []
permission_classes: list = []
registry = reg
def resolve_context(self, **kwargs):
return MagicMock()
def server_instructions(self, context):
return ""
return Probe.as_view()
def _post(self, body: str):
request = APIRequestFactory().post(
"/mcp/", data=body, content_type="application/json"
)
return self._view()(request)
def test_malformed_json_is_a_parse_error_envelope(self) -> None:
"""DRF would answer 400 with its own body; a JSON-RPC client is
parsing for an envelope and would see a transport fault instead.
"""
response = self._post("{not json")
body = json.loads(response.content)
assert body["error"]["code"] == JSONRPC.PARSE_ERROR
# Unparseable input carries no id, so the spec requires null.
assert body["id"] is None
def test_non_object_params_is_an_invalid_params_envelope(self) -> None:
"""A JSON array is valid JSON-RPC and survives `or {}`, then reaches
params.get() downstream as an AttributeError — a Django 500.
"""
response = self._post(
json.dumps(
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": [1, 2]}
)
)
body = json.loads(response.content)
assert body["error"]["code"] == JSONRPC.INVALID_PARAMS
assert body["id"] == 1
def test_a_scalar_params_is_also_refused(self) -> None:
response = self._post(
json.dumps({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": "x"})
)
body = json.loads(response.content)
assert body["error"]["code"] == JSONRPC.INVALID_PARAMS
def test_absent_params_is_still_accepted(self) -> None:
"""`params` is optional — the guard must not reject its absence."""
response = self._post(
json.dumps({"jsonrpc": "2.0", "id": 3, "method": "tools/list"})
)
body = json.loads(response.content)
assert "error" not in body
assert body["id"] == 3
def test_a_preflight_raising_an_unexpected_error_stays_in_the_envelope(
self,
) -> None:
"""A resolver filtering a UUID column by a malformed string raises
Django ValidationError. Before the catch-all it escaped post() and the
client got no envelope at all.
"""
from django.core.exceptions import ValidationError
def exploding_preflight(context, **kwargs):
raise ValidationError("bad uuid")
registry = MCPToolRegistry()
registry.register(
MCPTool(
name="probeTool",
description="",
input_schema={"type": "object", "properties": {}},
handler=lambda context, **kw: {"ok": True},
preflight=exploding_preflight,
)
)
request = APIRequestFactory().post(
"/mcp/",
data=json.dumps(
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {"name": "probeTool", "arguments": {}},
}
),
content_type="application/json",
)
response = self._view(registry)(request)
body = json.loads(response.content)
assert body["error"]["code"] == JSONRPC.TOOL_EXECUTION_ERROR
assert body["id"] == 4
class PlatformCsrfGateTest(SimpleTestCase):
"""CSRF is waived for the bearer key, not for everything.
``CustomAuthMiddleware`` falls through to session auth on this path, so an
unconditional exemption would let a logged-in browser session reach the
org-wide write and billable surface with CSRF off.
"""
def _initialize(self, with_key: bool):
from mcp_server.platform_views import PlatformMCPServerView
request = APIRequestFactory().post("/api/v1/unstract/org/mcp/", data={})
if with_key:
request.platform_api_key = MagicMock()
view = PlatformMCPServerView()
view.initialize_request(request)
return request
def test_a_bearer_request_is_exempt(self) -> None:
request = self._initialize(with_key=True)
assert getattr(request, "csrf_processing_done", False) is True
def test_a_session_request_is_not_exempt(self) -> None:
request = self._initialize(with_key=False)
assert getattr(request, "csrf_processing_done", False) is not True
class PlatformPollDeploymentResolutionTest(SimpleTestCase):
"""The platform poll resolves the deployment the execution actually used.
`get_platform_execution_status` finds the execution, resolves its deployment,
then delegates to the deployment-scoped `get_execution_status`. That inner
check filters on `pipeline_id`, so if the outer resolution picks a *different*
deployment sharing the same workflow, the inner check rejects an execution the
caller legitimately owns.
`APIDeployment.workflow` has no uniqueness constraint (`related_name="apis"`),
so "different deployment, same workflow" is a supported configuration rather
than a hypothetical.
"""
def test_the_deployment_is_resolved_by_pipeline_id(self) -> None:
from mcp_server.tools import platform_execution
execution = MagicMock(pipeline_id="dep-that-ran", workflow_id="shared-wf")
context = MagicMock()
context.org_name = "org-mcp"
with (
patch(
"mcp_server.tools.observability._org_workflow_ids", return_value=["w"]
),
patch(
"workflow_manager.workflow_v2.models.execution."
"WorkflowExecution.objects.filter"
) as exec_filter,
patch.object(platform_execution, "APIDeployment") as deployment_model,
patch(
"mcp_server.tools.execution.get_execution_status",
return_value={"ok": True},
),
):
exec_filter.return_value.only.return_value.first.return_value = execution
resolver = deployment_model.objects.for_user.return_value.filter
resolver.return_value.first.return_value = MagicMock()
platform_execution.get_platform_execution_status(
context, execution_id=GOOD_UUID
)
# The lookup must name the recorded deployment, not the workflow: a
# workflow filter returns an arbitrary sibling and the delegated check
# then refuses the caller's own execution.
resolver.assert_called_once_with(id="dep-that-ran")
def test_a_non_deployment_execution_is_still_refused(self) -> None:
"""Pipeline and ETL runs have no APIDeployment, and must not resolve to
an unrelated one just because they share a workflow.
"""
from mcp_server.tools import platform_execution
execution = MagicMock(pipeline_id=None, workflow_id="shared-wf")
context = MagicMock()
context.org_name = "org-mcp"
with (
patch(
"mcp_server.tools.observability._org_workflow_ids", return_value=["w"]
),
patch(
"workflow_manager.workflow_v2.models.execution."
"WorkflowExecution.objects.filter"
) as exec_filter,
patch.object(platform_execution, "APIDeployment") as deployment_model,
):
exec_filter.return_value.only.return_value.first.return_value = execution
resolver = deployment_model.objects.for_user.return_value.filter
resolver.return_value.first.return_value = None
with self.assertRaises(MCPToolError) as caught:
platform_execution.get_platform_execution_status(
context, execution_id=GOOD_UUID
)
assert "did not come from an API deployment" in str(caught.exception)
class ExecutionDetailDegradationTest(SimpleTestCase):
"""A partial `files` list must announce itself.
`getExecutionDetail` answers "which files failed, and why". If the per-file
load fails it keeps whatever it got — some detail beats none — but a short
or empty list then reads to an agent as "no files failed", which is the
opposite of the truth and the exact wrong premise for it to act on.
"""
def _execution(self, total_files: int = 3):
execution = MagicMock()
execution.id = GOOD_UUID
execution.workflow_id = "wf"
execution.status = "ERROR"
execution.total_files = total_files
execution.successful_files = 0
execution.failed_files = total_files
execution.error_message = ""
execution.execution_time = 1
execution.created_at = "2026-01-01"
return execution
def _run(self, execution):
from mcp_server.tools import observability
context = MagicMock()
context.org_name = "org-mcp"
with (
patch.object(observability, "_org_workflow_ids", return_value=["w"]),
patch.object(observability.WorkflowExecution.objects, "filter") as f,
):
f.return_value.first.return_value = execution
return observability.get_execution_detail(context, execution_id=GOOD_UUID)
def test_a_failed_file_load_is_announced(self) -> None:
execution = self._execution()
execution.file_executions.all.side_effect = RuntimeError("db gone")
result = self._run(execution)
assert result["files_complete"] is False
assert "incomplete" in result["files_note"]
# The count the agent should trust instead is still present.
assert result["failed_files"] == 3
def test_a_complete_load_says_nothing(self) -> None:
"""The marker must not appear on the happy path, or it means nothing."""
execution = self._execution(total_files=1)
row = MagicMock(id="f1", file_name="a.pdf", status="ERROR", execution_error="")
execution.file_executions.all.return_value = [row]
result = self._run(execution)
assert "files_complete" not in result
assert "files_note" not in result
assert len(result["files"]) == 1
def test_a_capped_list_is_also_announced(self) -> None:
"""Same wrong premise, different cause: hitting LOG_LIMIT truncates
silently unless the response says so.
"""
from mcp_server.tools.observability import LOG_LIMIT
execution = self._execution(total_files=LOG_LIMIT + 5)
rows = [
MagicMock(id=f"f{i}", file_name=f"{i}.pdf", status="ERROR", execution_error="")
for i in range(LOG_LIMIT)
]
execution.file_executions.all.return_value = rows
result = self._run(execution)
assert result["files_complete"] is False
assert str(LOG_LIMIT) in result["files_note"]