openom-mcp

A thin, deterministic FastMCP server over openom-core - six data verbs, zero inference: om_inspect · om_extract_text · om_extract_images · om_read · om_validate · om_embed, plus one hosted-transport helper om_request_upload (reserves a presigned upload target; HTTP transport only). So tools/list reports seven tools. Two transports: stdio (om-mcp) and hosted Streamable HTTP (om-mcp-http, SSRF-guarded, rate-limited, untrusted-parse-isolated).

pip install openom-mcp           # depends on openom-core (also from PyPI)
# from a clone (openom-core is not yet on PyPI): install core first, then mcp:
pip install -e ./core && pip install -e "./mcp[dev]"

Connect it to an MCP client (stdio)

Add to your client's MCP config (e.g. Claude Desktop claude_desktop_config.json, or any mcp.json):

{
  "mcpServers": {
    "openom": { "command": "om-mcp" }
  }
}

Hosted HTTP

om-mcp-http serves Streamable HTTP at the /mcp path (e.g. http://127.0.0.1:8080/mcp). By default it binds loopback (127.0.0.1:8080) - safe out of the box, not a world-open server. The free public grounding endpoint at https://mcp.openom.app/mcp is a serverless Cloudflare Worker (/mcp-worker) exposing the read-side om_read + om_validate via the byte-parity /js core; run om-mcp-http yourself for the full six-tool surface (extract/embed/inspect). Two-tier validation: schema errors block, consistency warnings never do; market truth is out of scope.

Tool inputs. The PDF-taking tools (om_inspect/om_read/om_extract_*/om_embed) accept a pdf object that is exactly one of: {"path": "..."} (stdio, a local file), {"url": "https://..."} (HTTP transport, fetched under the SSRF rules), or {"blobId": "..."} (HTTP, a prior om_request_upload). om_validate takes a payload object.

Stability. The seven-tool surface + result shapes are versioned with the spec (specVersion 0.1); the om_read/om_validate shapes match the public Worker ([Ma9]). Breaking tool-surface changes ship under a new spec minor. See the repo spec/CHANGELOG.md.

Configuration (env)

Every knob is an environment variable; defaults are safe for local use:

When you bind publicly (0.0.0.0) always set OPENOM_MCP_ALLOWED_HOSTS/_ORIGINS - the server logs a warning if you don't.

Production backends (env-selectable):

(Both boto3 and redis are imported lazily - neither is a hard dependency.) For anything further, build_http_app(...) accepts blob_store / rate_limiter injections directly.

Grounding an AI agent

Treat an openOM payload as the broker's asserted opinion, not fact: attribute every figure to assertedBy as of assertedDate, don't use a payload whose verification.hashValid isn't true, and never present an OM figure as verified truth (an OM is an advertisement / opinion of value). The full guide - MCP config, tool usage, and a system-prompt snippet - is Grounding AI agents in openOM (served at …/openom/docs/grounding-ai.html).

Tests: pytest mcp -q.