MCP server¶
pydiggs[mcp] serves pydiggs to AI assistants and other clients of the
Model Context Protocol (MCP). An MCP host starts
pydiggs serve --mcp as a child process and talks to it over stdin and stdout; the
model can then validate a DIGGS document, look up what a rule means, and read what is
in the document: its boreholes and other features, their samples and tests, and the
rows of each test's result tables.
pip install 'pydiggs[mcp]'
pydiggs serve --mcp # the host runs this; it waits for MCP messages on stdin
It is built on the official MCP Python SDK (mcp 2.x) and works with hosts that speak
either the initialize handshake or the stateless 2026-07-28 protocol.
Text from the file is untrusted data
The message, location.xpath, location.gml_id and files[].path fields of a
validation, and every name, description, remark, value and element text in a read
result, are copied from the document (or the name the caller gave it). A crafted file
can put any text there, including text written to look like instructions. Show these
fields as data; never let a model follow them. The text summary of a result never
contains them (see What the model reads).
Connecting a host¶
Most MCP hosts are configured with a JSON entry naming the command to start. With pydiggs installed in the environment the host uses:
Without installing it first, uv can fetch and run it:
{
"mcpServers": {
"pydiggs": {
"command": "uvx",
"args": ["--from", "pydiggs[mcp]", "pydiggs", "serve", "--mcp"]
}
}
}
Pin a version (pydiggs[mcp]==1.14.0) for a repeatable setup. The exact file and key
names depend on the host; check its documentation for "MCP servers" or "stdio servers".
Options go after --mcp:
| Option | Default | Meaning |
|---|---|---|
--max-bytes N |
10,485,760 (10 MiB) | largest decoded document |
--max-findings N |
200 | findings kept per document |
--timeout SECONDS |
60 | hard limit per validation (the worker is killed) |
--log-level L |
warning |
debug, info, warning, error or critical |
--log-format F |
text |
text or json lines on stderr |
Exit status: 0 when the host closes stdin or the process is interrupted; 2 for bad
arguments, a missing [mcp] extra, or stdin/stdout that are not usable.
Tools¶
All eight tools are read-only, with the annotations readOnlyHint: true,
destructiveHint: false, idempotentHint: true and openWorldHint: false. None of
them accepts a file path or a URL.
| Tool | Arguments | Result (structuredContent) |
|---|---|---|
validate_diggs |
content_base64 (string, required), name (string, at most 255 characters), checks (array of step names), diggs_version (2.5.a, 2.6, 3.0.0, or the experimental 3.1-dev) |
a whole one-file diggs-findings 1.2 document; the tool's outputSchema is the packaged findings schema |
explain_rule |
rule_id (string, at most 256 characters) |
one RuleInfo: id, pattern, step, description, severities, help_uri, known, guidance |
list_rules |
step (optional step name) |
{"rules": [RuleInfo, ...]} |
supported_versions |
none | pydiggs_version, findings_schema_version, findings_schema_url, diggs_versions, reference_data |
list_features |
content_base64 (required), kind (such as borehole), cursor |
one page of the document's features: key, kind, name, location, total_depth, parent, and how many samples and measurements refer to each; total and next_cursor |
get_feature |
content_base64 (required), key (required, from list_features) |
the whole diggs-model feature, and the samples, measurements and lithology layers that refer to it (at most 500 of each; not_listed counts the rest); trimmed |
list_measurements |
content_base64 (required), feature (a feature key), without_feature (true for those that name no feature), procedure (such as AtterbergLimitsTest), cursor |
one page of the document's measurements, and of other members that hold result tables: key, kind, name, procedure, feature, and how many tables and rows each has; total and next_cursor |
get_results |
content_base64 (required), measurement_key (required, from list_measurements or get_feature), table (from 0), columns (names or dictionary keys), cursor, max_rows (1 to 200, default 100) |
one page of one result table: the measurement, the columns (name, key, unit, SI factor, and role: index for where the row is, result for a value) and rows as arrays in column order; row_count and next_cursor |
validate_diggs takes the document as standard, padded base64 (no line breaks), so its
bytes, encoding declaration and SHA-256 are exactly those of the file. name is only
for display: it is reduced to a basename and becomes files[].path. checks runs only
the listed steps (structure, schema, dictionary, schematron, geometry,
deprecation, context). The result equals pydiggs validate --format json on the
same file, apart from path and the limits below: at most 200 findings and
512-character messages, where the CLI keeps 10,000 findings and 4,096 characters.
A malformed or invalid document is a normal result with findings, never an error.
Reading a document¶
list_features, get_feature, list_measurements and get_results read the document into
diggs-model 1.0, the same model pydiggs.read() returns, and answer one
slice of it. Each tool's outputSchema is built from the frozen diggs-model 1.0
definitions, so a feature, a quantity or a position has exactly the shape the model
schema gives it. A schema-invalid file still reads; run validate_diggs for a verdict.
A typical sequence: list_features to see the boreholes, get_feature on one of them
to see its samples and tests, then get_results on a test for its rows. Not every test
names a feature (a laboratory test may name only its sample), so list_measurements
lists them all: every measurement, then any other member that holds result tables, such
as a grouting activity. without_feature: true gives the ones no feature leads to.
Pages. list_features and list_measurements answer 100 items at a time and
get_results up to max_rows rows. When there are more, the result has a
next_cursor: call the same tool again with the same document and arguments and
cursor set to it. A cursor is short (under 128 characters) whatever the arguments
were. It names the document and the request it continues, so one sent with another
file or other arguments (another max_rows or columns too) is refused
(invalid-parameter).
Parsing. The server keeps no state between calls, so every call sends the document.
The worker keeps the last few models it read, by content hash, so the calls after the
first do not parse the file again. There are two models per file: one without table
values, which the three listing tools share, and one with them, which get_results
uses. A file cut short by a work limit is kept too; one cut short by the time limit is
read again.
Sizes. Every string in a read result is cut to 512 characters, ending in …,
names of unknown elements included. Node keys and references to them (key, feature,
parent …) are the exception, since a caller sends them back: they are cut only at
4,096 characters. A result is at most 1 MiB of JSON. A feature larger than that comes
without its extra elements and field provenance, with trimmed: true; a page of rows
larger than that is the error result-too-large (ask for fewer rows or columns).
What the model reads¶
Each result also has a TextContent block for the model. For the read tools it holds
only counts (features, samples, measurements, rows, the page) and the reminder that
file text is untrusted; never a name, a key or a value. For validate_diggs it is
built from a fixed template: the verdict, the status of each step, counts per step and
severity, and the rule ids found, followed by a reminder that finding fields are
untrusted. It never contains a message, an XPath, a gml:id or the file name, so text
planted in a document does not reach the model through the summary. A client that hands
structuredContent to the model gives it the untrusted fields too.
Resources¶
| URI | MIME type | Contents |
|---|---|---|
pydiggs://capabilities |
application/json |
a diggs-capabilities 1.0 document: every operation the server's pydiggs offers, with its stability, inputs, outputs, options, the extras it needs and whether they are installed |
It holds no text from any document, and reading it runs no worker.
Limits¶
| Limit | Value |
|---|---|
| Document size | 10 MiB decoded (--max-bytes); checked from the length of the base64 text before anything is decoded |
| Findings | 200 per document (--max-findings); a structure.findings-truncated finding says when more were dropped |
| Message length | 512 characters; longer messages end in … |
| Concurrency | one validation or read at a time, in one worker process |
| Time | 60 s per call (--timeout); the worker is then killed and replaced |
| Reading | the work limits of pydiggs.read(); a read result also cuts strings to 512 characters (keys to 4,096), lists 100 features or measurements or at most 200 rows per page, and is at most 1 MiB |
Only the bundled DIGGS schemas, dictionaries and Schematron rules are used. The server never reads local dictionaries, never fetches anything over the network, and never copies document snippets into a result.
Errors¶
A problem with the request or the document is a tool result with isError: true and
one text block, pydiggs error <code>: <message>. For bad arguments the message ends
with parameter: problem pairs separated by ;, and for internal errors with
(correlation id <hex>). Messages are fixed texts: they never repeat a value the
caller sent. An error result has no structuredContent, because that must match the
tool's outputSchema.
code |
When |
|---|---|
invalid-parameter |
a missing or wrong argument, or base64 that is not standard and padded |
input-too-large |
the document is larger than --max-bytes |
compressed-input |
the document is gzip-compressed |
input-unreadable |
the document could not be read |
invalid-document |
read tools: the bytes are not a DIGGS document |
result-too-large |
read tools: the document's model, or the page asked for, is too large to answer |
timeout |
the call did not finish in time; the file was not checked or read |
resource-error |
pydiggs's bundled reference data could not be loaded |
internal |
anything else; the details are logged to stderr with the correlation_id |
An unknown tool name or a malformed MCP request is a JSON-RPC error instead
(-32602 for an unknown tool).
stdout and stderr¶
stdout carries MCP messages only, one JSON message per line. Before the server starts,
pydiggs moves its own stdout to stderr, so a stray print, a write from C code or a
worker process cannot corrupt the message stream. Logs go to stderr; a host should read
stderr or send it to a file or the null device, since an unread pipe eventually blocks
the server.
From Python¶
pydiggs.mcp_server.create_server() returns the SDK's MCPServer, for embedding or for
tests with the SDK's in-process client:
import base64
import anyio
from mcp import Client
from pydiggs.mcp_server import create_server
async def main() -> None:
server = create_server(max_findings=50)
async with Client(server) as client:
with open("BH-01.xml", "rb") as fh:
content = base64.b64encode(fh.read()).decode("ascii")
result = await client.call_tool(
"validate_diggs", {"content_base64": content, "name": "BH-01.xml"}
)
print(result.content[0].text)
if __name__ == "__main__": # the worker process is spawned: keep this guard
anyio.run(main)
The streamable HTTP transport is not offered; use the HTTP API for network access.