Skip to main content
Glama
seb4ez

JevGuard MCP Server

by seb4ez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

JevGuard MCP Server

Official Model Context Protocol (MCP) server for JevGuard, the deterministic evaluation and certainty calibration runtime for TypeSafe AI.

This package exposes core JevGuard primitives through JSON-RPC 2.0 over standard input/output (stdio), adhering to the MCP 2024-11-05 specification.

Architectural Principles

  1. Zero External Dependencies: Implemented strictly with the Python standard library (sys, json, sqlite3, hashlib, urllib).

  2. Protocol Fidelity: Full compliance with the MCP 2024-11-05 standard, supporting initialize handshakes, ping, tool discovery, and tool execution.

  3. Deterministic Execution: State sanitization, closed-world neutral escape injection, probability dispersion analysis, and SHA-256 fingerprint caching.

  4. Process Isolation: Runs as an independent stdio subprocess compatible with Claude Desktop, Cursor IDE, LibreChat, and custom MCP clients.

Related MCP server: Omni-NLI

Empirical Benchmark (5 Vanilla vs 5 JevGuard MCP)

A live benchmark was conducted directly against the official TypeSafe AI endpoint (https://api.typesafe.ai/v1/systemone, model jev-latest) comparing 5 vanilla API calls against 5 JevGuard MCP tool calls.

JevGuard MCP Benchmark

Key Empirical Findings

  1. Deterministic Cache Speedup (0.099 ms): Repeated queries containing dynamic timestamps and trace IDs are intercepted locally. Volatile key masking matches the canonical SHA-256 fingerprint, resulting in a 7,400x speedup and 0 tokens consumed.

  2. Closed-World Trap Mitigation: In Scenario 3 (an off-topic inquiry about corporate tax offices in Zurich), Vanilla TypeSafe AI forced an arbitrary classification (credit_card_chargeback). JevGuard MCP automatically injected UNRESOLVED_OR_OTHER, safely catching the out-of-distribution input with 100% certainty.

  3. Ambiguity Calibration: In Scenario 1, boundary uncertainty on is_outage (noul=0.49, distance 0.01 to threshold) and flat distribution on severity (0.08 gap) were detected and flagged as AMBIGUOUS_STATE.

  4. Standard Library Overhead: Local middleware execution latency remained below 0.3 ms for cold requests and 0.099 ms for warm cache lookups.

Available Tools

1. jevguard_evaluate

Executes the deterministic JevGuard evaluation pipeline:

  • Prunes incoming state data to eliminate empty keys and duplicate whitespace.

  • Normalizes question schemas and injects closed-world escape alternatives (UNRESOLVED_OR_OTHER) to prevent false positives.

  • Computes canonical SHA-256 fingerprints with volatile key masking.

  • Queries the zero-token cache on hit or dispatches upstream to TypeSafe AI when credentials are configured.

  • Calibrates response certainty and dispersion metrics.

2. jevguard_calibrate

Analyzes response probability distributions to prevent false certainty:

  • Flags low confidence when the top probability falls below 0.40 (top_prob < 0.40).

  • Flags flat distributions when the gap between top and runner-up choices is below 0.15 (dispersion_gap < 0.15).

  • Evaluates boundary uncertainty for continuous noul probability ranges near 0.50 (|prob - 0.50| < 0.12).

  • Returns structured verdicts: AMBIGUOUS_STATE or CONFIDENT.

3. jevguard_prune_state

Sanitizes structured input states:

  • Removes null values and empty strings/collections from mapping objects.

  • Normalizes and collapses repeated whitespace.

  • Detects circular references and replaces them with <cyclic_ref> tokens.

  • Calculates an input token count estimate.

4. jevguard_cache_fingerprint

Calculates a canonical SHA-256 fingerprint:

  • Recursively strips volatile fields (timestamp, trace_id, request_id, created_at, updated_at, nonce).

  • Orders dictionary keys deterministically.

  • Produces identical hashes for semantically identical states regardless of key ordering or volatile timestamp variance.

Installation

Install the package directly in editable mode or as a standalone module using standard Python:

cd /path/to/jevguard-mcp
pip install -e .

Alternatively, run directly with Python without installing:

python -m jevguard_mcp.server

Client Configurations

1. Claude Desktop

Add the server to your claude_desktop_config.json:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jevguard": {
      "command": "python",
      "args": [
        "-m",
        "jevguard_mcp.server"
      ],
      "env": {
        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
      }
    }
  }
}

2. Cursor IDE

Add the server in Cursor Settings under Features -> MCP Servers -> Add New MCP Server, or save directly into .cursor/mcp.json:

{
  "mcpServers": {
    "jevguard": {
      "command": "python",
      "args": [
        "-m",
        "jevguard_mcp.server"
      ],
      "env": {
        "TYPESAFE_API_KEY": "your_typesafe_api_key_here"
      }
    }
  }
}

3. LibreChat

Add the server to your librechat.yaml configuration file:

mcpServers:
  jevguard:
    type: stdio
    command: python
    args:
      - "-m"
      - "jevguard_mcp.server"
    env:
      TYPESAFE_API_KEY: "your_typesafe_api_key_here"

Running the Test Suite

Run the unit tests with Python's standard unittest runner:

python -m unittest test_mcp_server.py -v

License

MIT License. Copyright (c) 2026 Seb4Ez.

Available Tools

4 tools
jevguard_cache_fingerprintB

Calculates a canonical SHA-256 fingerprint from state and questions with volatile key masking (timestamp, trace_id, request_id) for 0-token deterministic caching.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoTarget model identifier (default: jev-latest).jev-latest
stateYesState payload to include in fingerprint computation.
questionsNoQuestion definitions dictionary or list.
ignore_keysNoList of volatile keys to mask in addition to standard defaults.
auto_inject_escapesNoWhether to consider escape injection logic when computing fingerprint (default: true).

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool performs masking of volatile keys (timestamp, trace_id, request_id) and that it is for deterministic caching, which is a non-obvious behavior. However, it does not describe the output format (e.g., the fingerprint string), side effects, or whether the tool is pure (read-only). It does not contradict annotations since none exist, but it could add more.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that packs in the core purpose, method, and key behaviors (masking, deterministic caching). It is efficient and front-loads the essential information. The main minor issue is that it could be split into two sentences for readability, but it's not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters and no output schema, the description provides enough to understand the main flow but omits details on how the fingerprint is returned, what the format is, and how to interpret the output for caching. It also doesn't mention edge cases like when auto_inject_escapes might be disabled. For a caching-related tool, more specifics on output and usage would be helpful, but it's adequate for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documentation covers all parameters (100% coverage), so the description doesn't need to add much. However, the description adds context on how parameters are used: it mentions volatile key masking that relates to ignore_keys and the standard defaults, and it clarifies the role of state and questions. This is slightly above baseline but not substantial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool computes a SHA-256 fingerprint from state and questions, with a specific purpose (0-token deterministic caching) and mentions volatile key masking. It distinguishes itself from siblings like jevguard_calibrate and jevguard_evaluate, which are about other operations. However, it could be more explicit about what makes it different from jevguard_prune_state, but overall purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (for caching by computing a fingerprint) but does not explicitly state when not to use it or what alternatives exist (e.g., if you need to evaluate or calibrate, use those tools). It does not mention any prerequisites or situations where this tool is inappropriate. Thus, usage guidance is implied but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevguard_calibrateA

Evaluates probability distributions across answers to identify ambiguity, low confidence (top_prob < 0.40), and flat distributions (dispersion_gap < 0.15).

ParametersJSON Schema
NameRequiredDescriptionDefault
answersYesDictionary mapping question names to answers with probabilities or confidence values.
min_top_probNoMinimum confidence threshold for top choice (default: 0.40).
min_dispersion_gapNoMinimum probability gap between top choice and runner up (default: 0.15).
noul_uncertainty_marginNoUncertainty margin around 0.50 boundary for noul probabilities (default: 0.12).

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the internal decision logic (thresholds for top_prob and dispersion_gap) and implies a non-mutating evaluation, but it does not state whether the tool returns a report, modifies state, or requires specific permissions. This is a meaningful but not fatal gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with zero filler. Every phrase contributes: the verb, the resource, and the two key detection criteria. It is compact and immediately scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters, a nested object, no annotations, and no output schema, so the description should compensate by explaining return values and side effects. It covers the evaluation logic but omits what the tool returns, whether it is read-only, and the role of noul_uncertainty_margin. An agent would not know what to expect from invoking it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly linking min_top_prob to 'top_prob < 0.40' and min_dispersion_gap to flat distributions, clarifying the thresholds' roles. It does not mention noul_uncertainty_margin, but the schema already documents that parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies a specific verb ('Evaluates') and resource ('probability distributions across answers'), and specifies the purpose (identify ambiguity, low confidence, flat distributions). However, it does not differentiate from sibling 'jevguard_evaluate', so it stops short of full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied: use this tool when you need to assess answer distributions for ambiguity or low confidence. There is no explicit when/when-not guidance or mention of alternatives like jevguard_evaluate, so it lacks the explicit routing that a 5 would require.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevguard_evaluateA

Executes the deterministic JevGuard evaluation pipeline including state pruning, closed-world escape injection, certainty calibration, and 0-token caching.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoTarget model identifier (default: jev-latest).jev-latest
stateYesInput state payload to evaluate against criteria.
api_keyNoOptional TypeSafe AI API key (defaults to TYPESAFE_API_KEY environment variable).
timeoutNoHTTP request timeout in seconds (default: 30.0).
endpointNoUpstream API endpoint (default: https://api.typesafe.ai/v1/systemone).https://api.typesafe.ai/v1/systemone
questionsYesDictionary or list of question definitions (noul, score, choice).
bypass_cacheNoBypass deterministic cache lookup.
mock_answersNoOptional raw answers dictionary for testing or offline execution.
auto_inject_escapesNoAutomatically inject neutral escape alternatives into categorical choices.

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so description must disclose behavior. It lists key pipeline steps (state pruning, escape injection, calibration, caching) giving a good sense of what happens. However, it doesn't mention that the tool may be deterministic and cache results (beyond '0-token caching'), nor does it note any potential side effects or side effects of bypassing cache. But the explicit pipeline components add transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence but packs a lot of specific terminology. It is front-loaded with the main action and lists key pipeline components efficiently. It is appropriately concise, though it might benefit from a brief example or more plain-language explanation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters and a nested object (questions), the description provides a high-level overview but does not clarify the exact input format for 'questions' beyond the schema. It doesn't explain the return value or error handling. Since output schema is absent, the description should hint at what the result looks like, but it doesn't. Still, the components listed give a good sense of the pipeline.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are well-documented in schema. The description doesn't add much beyond the schema. However, it clarifies that 'questions' can be a dictionary or list and mentions 'escape injection' and 'caching' which relate to parameters like auto_inject_escapes and bypass_cache. But the schema already describes those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a 'deterministic JevGuard evaluation pipeline' with specific components (state pruning, closed-world escape injection, certainty calibration, 0-token caching). This gives a clear verb and resource, though it could be more specific about what 'evaluate' means (e.g., evaluating an AI system's state against criteria). It is distinguishable from siblings but not fully explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is the main evaluation entry point, but does not explicitly state when to use it vs. siblings (e.g., calibrate, prune_state, cache_fingerprint). It doesn't mention any prerequisites or exclusions. The sibling names suggest related utilities, but no direct routing is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jevguard_prune_stateA

Sanitizes and prunes complex JSON state payloads by removing nulls, empty collections, collapsing whitespace, and protecting against cyclic references.

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYesThe state payload (dict, list, or primitive) to sanitize and prune.
prune_listsNoWhether to strip empty values and nulls from lists (default: false).

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden and does reveal meaningful behavior: removing nulls/empty collections, collapsing whitespace, and cycle protection. However, it omits whether the input is mutated or a new payload is returned, and how the prune_lists flag interacts with the described 'empty collections' behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the verb and resource, with every clause adding a specific behavior. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with a fully described schema, the description covers the core behavior, but with no output schema it should state what is returned (or whether mutation occurs). It also lacks any usage context, so an agent is left to infer how the result is consumed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds general context about JSON payloads and cycles but no parameter-specific detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with specific verbs 'Sanitizes and prunes' and names the exact resource ('complex JSON state payloads'), then enumerates concrete operations. This is clearly distinct from siblings like jevguard_calibrate, jevguard_evaluate, and jevguard_cache_fingerprint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to choose this tool over alternatives, no exclusions, and no mention of sibling tools. The only usage cue is the verb 'prune,' which is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedjevguard_cache_fingerprint
    • First observedjevguard_calibrate
    • First observedjevguard_evaluate
    • First observedjevguard_prune_state
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: calibration assesses probability distributions, evaluate runs the full pipeline, prune_state sanitizes JSON, and cache_fingerprint computes hashes. No overlap or ambiguity between them.

Naming Consistency5/5

All tools follow a consistent 'jevguard_' prefix with verb_noun naming (calibrate, evaluate, prune_state, cache_fingerprint). The pattern is uniform and predictable.

Tool Count5/5

Four tools is well within the ideal range for a focused server. Each tool serves a specific step in the JevGuard workflow without unnecessary bloat.

Completeness4/5

The tools cover the core pipeline stages (calibration, evaluation, state pruning, caching) but might benefit from a dedicated tool for retrieving or reporting results. Minor gap, but the set is largely complete for its stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers