@noamjose/schemasure

@noamjose/schemasure

MCP client for SchemaSure exposing two outcome-shaped tools:

• extract_to_schema(input, schema) turns messy text/HTML into validated JSON.
• extract_image_to_schema(image, schema) reads PNG, JPEG, or WebP invoices, receipts, forms, screenshots, labels, and photographed documents into validated JSON.

Both return data guaranteed to validate against your JSON Schema (Ajv, draft 2020-12), or a typed error.

This package is a thin client: it forwards calls to the hosted SchemaSure API and relays the response. It ships no extraction logic and needs no LLM API key. It runs in one of two modes, selected automatically:

• Evaluation mode (default, no wallet): calls the legacy V1 endpoint POST /extract with a small free allowance.
• Paid mode (wallet configured): set SCHEMASURE_PRIVATE_KEY and the client calls the always-paid production APIs POST /v2/extract and POST /v2/extract-image (x402 V2, USDC on Base mainnet, charge-only-on-success). Your key is used locally to sign the x402 payment and is never sent to SchemaSure, returned in tool output, or logged.

Image extraction is V2-only and always paid. It has no V1 endpoint and no free calls; when no wallet is configured, the image tool returns PAYMENT_REQUIRED without uploading the image.

Benchmarked 100% schema-valid with ~0.99 field F1 and zero hallucinations across a 10-doc-type corpus (11 items, incl. an adversarial prompt-injection tier), p50 latency ~1.5s. Evidence: /.well-known/benchmarks.json.

Install

Run directly with npx (no install, no key):

npx -y @noamjose/schemasure

Claude Desktop / Cursor / Windsurf (mcpServers)

{
  "mcpServers": {
    "schemasure": {
      "command": "npx",
      "args": ["-y", "@noamjose/schemasure"]
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "schemasure": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@noamjose/schemasure"]
    }
  }
}

Configuration

No configuration is required for free evaluation. Environment variables:

Var	Default	Purpose
SCHEMASURE_API_URL	https://schemasure.com	Point at a self-hosted or staging deployment
SCHEMASURE_TIMEOUT_MS	90000	Per-call request timeout (ms)
SCHEMASURE_PRIVATE_KEY	(unset)	0x-prefixed 32-byte EVM key. Presence enables paid x402 V2 mode. Used only to sign payments locally
SCHEMASURE_MAX_PRICE_USD	0.10	Client-side spend cap per call; the client refuses to pay if the server advertises more

Paid mode (x402 V2)

{
  "mcpServers": {
    "schemasure": {
      "command": "npx",
      "args": ["-y", "@noamjose/schemasure"],
      "env": { "SCHEMASURE_PRIVATE_KEY": "0x<your-funded-base-mainnet-key>" }
    }
  }
}

When SCHEMASURE_PRIVATE_KEY is set, the client calls the matching V2 text or image endpoint, decodes the PAYMENT-REQUIRED challenge, signs an exact-scheme USDC authorization on Base mainnet (eip155:8453), and retries with PAYMENT-SIGNATURE. On success it returns { data, meta }; the PAYMENT-RESPONSE receipt is handled internally and never surfaced to the model.

Security notes

• Use a dedicated, low-balance wallet funded only with the USDC you intend to spend.
• The private key never leaves your machine and is never logged or placed in tool output.
• SCHEMASURE_MAX_PRICE_USD caps per-call spend as a guard against a misconfigured/hijacked endpoint.
• In paid mode the client refuses to send payments over plaintext HTTP to non-loopback hosts.

Example

extract_to_schema takes input (text/HTML) and a schema (JSON Schema, draft 2020-12). It returns { data, meta } where data is guaranteed to validate against your schema, or a typed error (and no charge) if it cannot.

For images, pass raw base64 bytes without a data-URL prefix:

{
  "image": { "data": "<base64 PNG/JPEG/WebP bytes>", "mimeType": "image/png" },
  "schema": {
    "type": "object",
    "required": ["invoiceNumber", "total"],
    "properties": {
      "invoiceNumber": { "type": "string" },
      "total": { "type": "number" }
    }
  }
}