LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
"""Organization-scoped MCP server.
Mounted on a tenant URL — deliberately *not* under the whitelisted ``/mcp/``
prefix — so ``CustomAuthMiddleware`` runs ahead of it and performs the
authentication. By the time this view executes, the middleware has already:
* resolved the ``Authorization: Bearer <uuid>`` platform key,
* rejected unknown, inactive, and wrong-organization keys,
* rejected keys whose permission tier disallows the HTTP method,
* set ``request.user`` to the key's service account and pinned
``ORGANIZATION_ID`` in the state store.
This view therefore reads that result rather than re-authenticating. Two
consequences worth stating plainly, because both are easy to get wrong:
1. ``authentication_classes`` must NOT be emptied here. The deployment server
empties it because it owns its own auth; doing the same here is harmless
only by accident, and setting DRF authenticators that return a user would
actively override what the middleware resolved.
2. Because the auth lives in middleware, a test that calls this view through
``APIRequestFactory`` bypasses it entirely and would pass against a
completely open endpoint. The auth-boundary tests go through the full URL
stack for exactly this reason.
"""
import logging
from typing import Any
from platform_api.models import ApiKeyPermission
from rest_framework.request import Request
from mcp_server import spend_guard
from mcp_server.context import PlatformMCPContext
from mcp_server.registry import PLATFORM_TOOLS
from mcp_server.transport import BaseMCPView
logger = logging.getLogger(__name__)
class PlatformMCPServerView(BaseMCPView):
"""MCP JSON-RPC endpoint scoped to an organization.
Exposes discovery, observability, state-change and billable tools over the
organization's resources, authenticated by a platform API key. Tool access
is gated twice: by the key's permission tier (``check_tool_allowed``) and,
for tools that cost money, by a per-organization budget
(``check_spend_allowed``).
"""
registry = PLATFORM_TOOLS
# Intentionally not overriding authentication_classes: the project sets no
# DEFAULT_AUTHENTICATION_CLASSES that would resolve a user, so the
# middleware's request.user survives into the view.
permission_classes: list = []
def initialize_request(self, request: Request, *args: Any, **kwargs: Any) -> Request:
"""Skip CSRF, but only for a bearer-authenticated request.
The middleware already marks those CSRF-exempt; this makes the view's
behaviour explicit rather than dependent on that. Gating on the key
matters because ``CustomAuthMiddleware`` falls through to session auth
on this path — exempting unconditionally would let a logged-in browser
session reach the organization-wide write and billable surface with
CSRF off.
"""
if getattr(request, "platform_api_key", None):
request.csrf_processing_done = True
return super().initialize_request(request, *args, **kwargs)
def auth_failure_message(self) -> str:
return "A valid platform API key is required"
def server_instructions(self, context: PlatformMCPContext) -> str:
return (
"Unstract runs LLM-driven extraction over unstructured documents "
"and returns structured JSON. This server is scoped to the "
f"organization '{context.org_name}'. It can discover deployments, "
"workflows, pipelines and Prompt Studio projects, and can change "
"their running state — activating deployments, pausing schedules, "
"triggering pipeline runs. Those writes affect the whole "
"organization and consume quota. Call readMeFirst before any "
"other tool."
)
def resolve_context(
self, request: Request, **kwargs: Any
) -> PlatformMCPContext | None:
"""Read the credential the auth middleware already resolved.
Returns None when the middleware did not attach a platform key. That is
a defence-in-depth check rather than the primary gate: an unauthenticated
request should never reach this view, because the middleware rejects it
first with its own 401. If it does reach here — a whitelist edit, a
routing change — refusing is the safe answer.
"""
platform_key = getattr(request, "platform_api_key", None)
user = getattr(request, "user", None)
# The organization is not a URL kwarg here: the tenant prefix consumes
# it, and OrganizationMiddleware parses it onto the request. Read it
# from there rather than from the route.
org_name = getattr(request, "organization_id", None)
if platform_key is None or user is None or not user.is_authenticated:
logger.warning(
"Platform MCP reached without a resolved platform key "
f"(org '{org_name}'). Check that this path is not whitelisted."
)
return None
return PlatformMCPContext(
user=user,
platform_key=platform_key,
# Fall back to the key's own organization so the context is never
# built with a null org, whatever the routing did.
org_name=org_name or str(platform_key.organization.organization_id),
request=request,
)
def check_tool_allowed(self, tool: Any, context: PlatformMCPContext) -> str | None:
"""Apply the platform key's permission tier to this specific tool.
The middleware already checked the tier, but it can only check it
against the HTTP method of the request — and every JSON-RPC message
arrives as an HTTP POST, whatever the tool inside it does.
That makes its verdict uselessly coarse here: it cannot tell
``listWorkflows`` from ``executePipeline``.
So each tool declares the method its REST equivalent would use, and the
tier is re-evaluated against that. This deliberately reuses
``ApiKeyPermission.allows`` rather than inventing a second permission
scheme, so a tool marked DELETE is full_access-only for exactly the
same reason a REST DELETE is.
**This refuses nothing today, and that is expected.** A ``read`` key
cannot reach the view at all — the middleware rejects POST on tier
before dispatch — and both remaining tiers (``read_write``,
``full_access``) allow POST, while every registered tool declares GET
or POST and none declares DELETE. So the check is prospective:
defense-in-depth that starts refusing the day a DELETE-tier tool is
added, or the day the middleware grows an MCP carve-out that lets a
``read`` key through.
Its future value rests entirely on ``required_method`` being declared
truthfully, which is why ``MCPToolRegistry.register`` refuses a
``writes=True`` tool left at the ``"GET"`` default rather than trusting
a reviewer to catch it.
"""
try:
permission = ApiKeyPermission(context.platform_key.permission)
except ValueError:
# The middleware rejects unrecognised tiers, so this is
# unreachable in practice; refusing is the safe answer if it ever
# becomes reachable.
logger.error(
f"Unrecognised platform key tier "
f"'{context.platform_key.permission}'; refusing tool access."
)
return "This API key has an unrecognised permission tier."
if permission.allows(tool.required_method):
return None
return (
f"Tool '{tool.name}' requires a platform API key permitting "
f"{tool.required_method}; this key is '{permission.value}'."
)
def check_spend_allowed(self, tool: Any, context: PlatformMCPContext) -> str | None:
"""Claim one unit of the organization's billable-call budget.
Only billable tools consume budget; everything else is free. The claim
is made here rather than inside each handler so a new billable tool
cannot be added without being budgeted — the flag on the registry entry
is the only thing it has to get right.
"""
if not tool.billable:
return None
state = spend_guard.consume(context.org_name)
if state.allowed:
return None
return state.message()