MCP Sigil Resolver Server

Download PDF

MCP Sigil Resolver Server – Design Proposal

Background

Sigils are currently resolved inside the Django application through core.sigil_resolver, which inspects the SigilRoot configuration, looks up model instances, and falls back to a gway subprocess for unknown roots. The resolver supports nested sigils, dynamic model lookups, environment variables, and per-thread context provided through core.sigil_context. Sigil metadata is surfaced in the admin via the Sigil Builder view, which lists known roots and lets administrators experiment with resolution.

The product roadmap calls for exposing the same capabilities outside of Django via OpenAI's Model Context Protocol (MCP) so connectors can resolve sigils over SSE.

Goals

Provide an MCP-compliant server that exposes the existing resolution logic without duplicating business rules.
Enable secure remote resolution for arbitrary text with nested sigils as well as utility discovery (e.g., which roots exist).
Support opt-in per-session context (current user, current entity instances) so downstream agents can resolve contextual sigils accurately.
Keep the gway fallback so existing external integrations remain functional, but make it optional when MCP adoption is complete.

Non-Goals

Replacing the in-process Django resolver.
Offering arbitrary database access beyond the existing sigil semantics.
Shipping a production-grade authentication service; the first version will rely on API keys and reverse proxies.

Protocol Surface

The server will expose the following MCP constructs:

Type	Name	Purpose
Tool	`resolveSigils`	Resolve one or more sigils inside a text payload using the current session context. Input schema: `{ "text": string, "context": {"model": {"app_label.ModelName": "pk"}}, "options": {"skipUnknown": bool}}`. Returns `{ "resolved": string, "metadata": {"unresolved": [string]}}`.
Tool	`resolveSingle`	Resolve a single sigil token and return its value or unresolved form. Thin wrapper that validates the sigil shape before delegating to `resolveSigils` for reuse.
Tool	`describeSigilRoot`	Provide metadata for a given sigil root (fields, context type) leveraging the same data that powers the Sigil Builder view.
Tool	`setContext`	Update the thread-local sigil context using `set_context` to mimic how the resolver infers instances from request state.
Resource	`sigilRoots` (optional streaming)	Publish changes to `SigilRoot` objects so long-lived MCP sessions can react to new roots without polling. Implemented via Django signals.

The server’s list_tools handler simply advertises the tools above, while call_tool dispatches to a per-session service class that wraps resolve_sigils and _resolve_token logic so every invocation reuses the battle-tested paths.

Server Architecture

manage.py mcp_sigil_server
└── SigilResolverServer (mcp.server.sse.SseServer)
    ├── SigilSessionState (per-connection context)
    │   └── SigilContextAdapter ↔ core.sigil_context
    ├── SigilResolverService
    │   └── uses core.sigil_resolver.resolve_sigils
    └── SigilRootCatalog (queries SigilRoot + caches metadata)

Entry point – New Django management command mcp_sigil_server imports django.setup(), instantiates an SseServer from the modelcontextprotocol reference implementation, and serves it over an HTTP listener (default 127.0.0.1:8800).
Session state – On accept_session, capture authentication headers, initialize a SigilSessionState, and register a connection-specific logger so unresolved sigils continue to log warnings via logger.warning just like the in-process resolver.
Resolver service – Wrap the existing resolve_sigils function. Before each call, apply any session context by temporarily invoking set_context / clear_context. After resolution, detect which tokens remained unresolved by diffing the output against the input and by checking the metadata returned from _failed_resolution.
Sigil root catalog – Provide cached metadata for describeSigilRoot and resource streaming by reusing the query logic from core.sigil_builder (select related content type, list fields, etc.).
Gway integration – Keep _resolve_with_gway untouched; the MCP server simply imports resolve_sigils, so the fallback path still shells out when no root is found.

Configuration & Security

Dependencies – Add modelcontextprotocol (Python MCP reference SDK) to requirements.txt and vendor reusable schemas in a small core/mcp/schemas.py module to avoid duplicating JSON schema definitions across handlers.
Settings – Introduce settings.MCP_SIGIL_SERVER = {"host": "127.0.0.1", "port": 8800, "api_key": "..."}. The management command reads these values and optionally the --public flag to bind to 0.0.0.0 behind an ingress controller.
Authentication – Expect an Authorization: Bearer <token> header on createSession. Reject the request unless the token matches settings.MCP_SIGIL_API_KEYS (list) so multiple connectors can be provisioned without redeploying the service.
Rate limiting – Start with a simple per-session throttle (e.g., options.maxRequestsPerMinute) enforced inside the session state. Upgrade to Redis-backed limits later if required.

Implementation Plan

Foundations
- Add the dependency and create core/mcp/__init__.py, core/mcp/server.py, and core/mcp/schemas.py with Pydantic models to validate tool arguments before passing them to Django.
- Implement SigilResolverService that exposes resolve_text, resolve_single, set_context, and describe_root. It should call resolve_sigils and interact with SigilRoot directly.
MCP server
- Wire the service into an SseServer inside the management command. Handle lifecycle events (session start/end) to clear context using clear_context to prevent leaks.
- Expose the tools and resources by implementing the relevant decorators from the MCP SDK.
Admin & Ops
- Document how to create API keys and register the connector. Provide example curl traces to validate the SSE handshake.
- Extend deployment scripts (e.g., start.sh or a systemd unit) so the MCP server can run alongside Django in production.
Testing
- Unit-test the service class against fixtures already used by tests/test_sigil_resolution.py to ensure parity with in-process resolution.
- Add an async integration test that spins up the SSE server on an ephemeral port, runs through list_tools and call_tool, and verifies resolution and authorization behavior.
- Reuse existing factories to assert context-aware lookups (e.g., entity sigils with filter_field rules).

Operational Considerations

Observability – Emit structured JSON logs for each tool call (input length, number of tokens resolved, duration). Ship basic metrics via Prometheus or StatsD.
Error handling – Map Django validation errors to MCP ToolError responses so clients get actionable messages. Unexpected exceptions should surface as InternalError while still logging stack traces.
Scalability – Because the resolver relies on Django ORM calls, keep the MCP server colocated with the Django app or share the same settings module/environment to avoid mismatched configuration.

Future Enhancements

Add prompt registrations so LLM clients can request example instructions for building sigils.
Support long-running background resolution jobs via MCP jobs once the reference SDK stabilizes.
Replace the gway fallback with a dedicated MCP tool that proxies to whatever eventually supersedes gway, allowing observability and retries over the same channel.