Schema Sentinel

Contract-first gatekeeper between LLMs and tools/MCP.

Validates every tool call against JSON Schema, attempts deterministic structured repair (coerce → strip unknown → fill defaults) within a repair budget, redacts secrets from args/logs, and emits a hash-chained audit ledger of pass / fail / repaired / denied.

Runs as a library (@schema-sentinel/core) or as an MCP STDIO server (@schema-sentinel/mcp-proxy).

Why

LLM tool calling is trust-boundary #1. Schema Sentinel fails closed (deny-by-default), caps payload size, never needs a live LLM for repair, and keeps an integrity-checked trail of what was allowed — with secrets redacted.

Packages

Package	Role
@schema-sentinel/core	SchemaRegistry, Validator, RepairLoop, Redactor, AuditLedger, OpenAPI import, Policy gate
@schema-sentinel/mcp-proxy	MCP server exposing ss_* tools
@schema-sentinel/inspector	Static HTML audit viewer

Quick start

git clone https://github.com/SanjoyDat1/schema-sentinel.git
cd schema-sentinel
npm install
npm run build
npm test

Library

import { SchemaSentinel } from "@schema-sentinel/core";

const ss = new SchemaSentinel({
  policy: {
    denyUnknownSchemas: true,
    maxPayloadBytes: 65_536,
    maxRepairAttempts: 4,
    maxRepairDepth: 8,
    allowRepair: true,
  },
});

ss.registry.register({
  id: "add",
  schema: {
    type: "object",
    additionalProperties: false,
    required: ["a", "b"],
    properties: {
      a: { type: "number" },
      b: { type: "number" },
    },
  },
});

const result = ss.gateCall({
  schemaId: "add",
  args: { a: "1", b: 2, junk: true }, // coerced + stripped
});
// result.allowed === true, result.repaired === true

CLI

node bin/schema-sentinel.js gate --schema http_request \
  --args '{"method":"GET","url":"https://example.com"}'

node bin/schema-sentinel.js serve   # MCP STDIO

Cursor / Claude MCP config

{
  "mcpServers": {
    "schema-sentinel": {
      "command": "node",
      "args": [
        "/absolute/path/to/schema-sentinel/packages/mcp-proxy/dist/cli.js"
      ]
    }
  }
}

Or after npm link / global install:

{
  "mcpServers": {
    "schema-sentinel": {
      "command": "schema-sentinel",
      "args": ["serve"]
    }
  }
}

MCP tools

Tool	Description
ss_register_schema	Register/update a JSON Schema
ss_validate	Pure validate (no repair)
ss_repair	Deterministic repair + validate
ss_gate_call	Policy → validate → repair → redact → audit
ss_redact	Standalone secret redaction
ss_audit_query	Filter ledger entries
ss_export_ledger	Export chain + tip hash
ss_import_openapi	Import schemas from OpenAPI 3.x

Example schemas preloaded on boot: http_request, file_write, shell_exec (dangerous-pattern deny).

Security features

• Deny-by-default unknown schemas
• Locked built-in schemas (examples cannot be overwritten via MCP)
• MCP registration gated by SCHEMA_SENTINEL_ALLOW_REGISTER=1 (off by default)
• Max payload size (DoS / flood guard)
• Repair budget (maxRepairAttempts, maxRepairDepth)
• Differential audit (redacted before/after)
• Hash-chained ledger (SHA-256)
• Redaction: JWTs, API keys, Bearer tokens, emails, secret field names (__proto__-safe)
• Example schemas: command allowlist + dangerous denies, path traversal blocks, SSRF denials

Inspector

Open apps/inspector/public/index.html in a browser, paste output from ss_export_ledger / schema-sentinel export-ledger.

node bin/schema-sentinel.js export-ledger --out ledger.json
node bin/schema-sentinel.js inspect ledger.json

Architecture

See docs/ARCHITECTURE.md and docs/PLAN.md.

Development

npm run build
npm run typecheck
npm test

Requires Node 20+.

License

MIT