Adds Open-Jev context to Hermes prompts via a pre_llm_call plugin, supplying calibrated probabilities derived from planner-generated questions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@open-jev What are the calibrated probabilities on this plan? Run a Jev analysis before responding."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Every prompt you send to Claude Code or Hermes goes through this pipeline:
prompt ──► local LLM planner (Ollama, JSON-schema output) ──► 2-5 typed questions (noul/choice/score)
──► local Open-Jev server (/v1/systemone) ──► calibrated probabilities
──► injected as context ──► the main agent decides what to do with itThe pipeline fails open: if Ollama or Jev is down or slow, the prompt goes through unchanged.
Failures are logged to ~/.cache/openjev-mcp/errors.log. Each successful run is logged to
~/.cache/openjev-mcp/runs.jsonl with the questions, answers and latencies.
Prompts are sent only to the two localhost services above; nothing leaves your machine. The logs stay local
in ~/.cache/openjev-mcp and are git-ignored.
Requires Python 3.10+, uv, Ollama and an NVIDIA GPU
(about 10 GB of VRAM is enough for Open-Jev-2B plus qwen3.5:4b). Below, <repo> is where you clone this project.
This project and the planner model:
git clone https://github.com/yogeshvar/open-jev-mcp <repo> && cd <repo> && uv sync
ollama pull qwen3.5:4bOpen-Jev with the published 2B checkpoint (the default location is ~/Projects/Open-Jev):
git clone https://github.com/Zefan-Cai/Open-Jev ~/Projects/Open-Jev && cd ~/Projects/Open-Jev
uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e '.[train]' huggingface_hub
.venv/bin/hf download ZefanCai/Open-Jev-2B --revision 0c7aa498b1627be8da4acf34c863ff0ee0a92785 --local-dir models/Open-Jev-2BThe server command:
ln -s <repo>/bin/jev-server ~/.local/bin/jev-server && jev-server startClaude Code: register the MCP server and add the prompt hook to ~/.claude/settings.json:
claude mcp add --scope user open-jev -- uv run --quiet --project <repo> openjev-mcp{ "hooks": { "UserPromptSubmit": [ { "hooks": [
{ "type": "command", "command": "python3 <repo>/hooks/claude_prompt_hook.py", "timeout": 20 } ] } ] } }Hermes: link the plugin, then enable the plugin and the MCP server in ~/.hermes/config.yaml:
ln -s <repo>/hermes_plugin/open-jev ~/.hermes/plugins/open-jevplugins:
enabled:
- open-jev
mcp_servers:
open-jev:
command: uv
args: [run, --quiet, --project, <repo>, openjev-mcp]
enabled: trueRelated MCP server: local-coder-mcp
Path | What it does |
| Ollama writes question designs for the prompt. Test it with |
| Applies Open-Jev's |
|
|
| General questions used when the planner fails but Jev is up |
| MCP tools: |
| Claude Code |
| Hermes |
ollama pull qwen3.5:4b
jev-server start # background Open-Jev server; waits until /health is ready
jev-server status # Jev + Ollama readiness (exit 0 only when Jev is ready)
jev-server stop # also stops a server started by hand on the same port
jev-server restart
jev-server logs [n] # follow ~/.cache/openjev-mcp/jev-server.logbin/jev-server is symlinked into ~/.local/bin. Override with JEV_HOME (default ~/Projects/Open-Jev),
JEV_CHECKPOINT, JEV_DEVICE, JEV_PORT and JEV_START_TIMEOUT.
OPENJEV_URL (default http://127.0.0.1:8791/v1/systemone), OPENJEV_LLM_URL (http://127.0.0.1:11434),
OPENJEV_LLM_MODEL (qwen3.5:4b), OPENJEV_PLAN_TIMEOUT (10 s), OPENJEV_JEV_TIMEOUT (5 s),
OPENJEV_MAX_CHARS (6000), OPENJEV_MAX_QUESTIONS (5), OPENJEV_MAX_CANDIDATES (24),
OPENJEV_FALLBACK (static or none), OPENJEV_DISABLE=1 (turns the pipeline off).
OPENJEV_SOURCE=/path/to/Open-Jev python3 -m unittest discover -s tests -vRun the full pipeline (LLM planner -> local Jev) on any text; returns questions, answers and a summary.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It does disclose the internal progression ('LLM planner -> local Jev') and the high-level return content, which adds behavior context. However, it does not mention potential side effects, latency, cost, authentication needs, or whether the operation is effectively stateless and read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the core verb and resource, then gives the pipeline detail and output items with no filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description is adequate but not complete. It explains what the tool does and what it returns, but with no annotations and no usage-versus-sibling guidance, the agent is left to infer when this tool should be invoked instead of ask/plan/health and whether there are any operational caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter, 'prompt', with no description coverage (0%). The description adds modest value by saying 'any text' tells the agent the prompt is free-form text, but it does not explain length limits, formatting expectations, or how the prompt should be phrased to get optimal questions/answers/summary results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Run the full pipeline'), the input scope ('any text'), and the outputs ('questions, answers and a summary'). It does not explicitly distinguish itself from siblings like jev_ask or jev_plan, but the 'full pipeline' phrasing implies it is the comprehensive analysis entry point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus its siblings, such as jev_ask, jev_plan, or jev_health. 'On any text' is a broad context, not a precise usage rule, and no exclusions or alternative conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the local Open-Jev server typed questions about a state.
questions maps question_id -> {"type": "noul"|"choice"|"score", "instructions": str, "criteria": ...}. choice criteria: {label: description, ...}; score criteria: ordered list of level descriptions (2-10, lowest first); noul: no criteria (or {"true": ..., "false": ...}).
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | ||
| questions | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the question payload format but does not state whether the operation is read-only, whether it has side effects, whether authentication is required, or what the response behavior is. 'Ask' implies a query, but that is not made explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The additional detail about question types is dense but necessary and organized clearly. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters and no annotations, the description leaves a significant gap: the meaning of 'state' is undefined, and there is no usage context relative to siblings. The output schema exists but does not help with state semantics or selection guidance, so an agent may struggle to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description thoroughly documents the 'questions' parameter, including the type enum (noul/choice/score) and the criteria structures for each type. However, the required 'state' parameter is only described as 'a state' with no format, allowed values, or examples, and schema coverage is 0%, so the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Ask'), names the resource ('local Open-Jev server'), and specifies the domain ('typed questions about a state'). It is clear about what the tool does, but it does not explicitly differentiate it from siblings like jev_plan or jev_analyze.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus the sibling tools, nor are any prerequisites or exclusions mentioned. An agent would not know whether to call jev_ask before, after, or instead of jev_plan or jev_analyze.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the local Open-Jev server and the Ollama planner model are available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool reports availability, implying a read-only check, but does not disclose whether it makes network calls, how long it might take, or any failure semantics. This is adequate for a simple health check but lacks context that would help an agent set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It conveys the exact purpose without any fluff, and the resource scope is clearly front-loaded. This is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, a clear purpose, and an output schema that presumably documents the return format). The description adequately covers what the tool does. It lacks explicit guidance on when to call it, but given the simplicity and the existence of an output schema, this is a minor gap. The description is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameter semantics. The baseline of 4 applies. The description does not add extra detail beyond the schema (which is empty), but with no parameters, nothing further is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a clear resource (availability of the Open-Jev server and Ollama planner model). It fully distinguishes this tool from siblings like jev_ask, jev_plan, and jev_analyze, which perform distinct actions. There is no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus its siblings. While it is implicitly a prerequisite check for the other tools, this is not stated. An agent is left to infer that it should be called before other operations, which is a notable omission for a zero-parameter tool that is likely part of a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate (but do not run) the Jev probe the local LLM planner would write for this prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 transparency. It discloses a key non-obvious trait—the tool does not run the probe—and notes the output is what the local LLM planner would write, which sets expectations. It does not cover potential side effects or prerequisites, but for a generation tool this core trait is acknowledged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loaded with the distinguishing 'Generate (but do not run)' phrase. Every word earns its place, making it both concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one self-descriptive parameter and an output schema, the description covers the essential purpose and the non-execution side effect. It doesn't explain the Jev probe concept or sibling relationships, but those are not required for correct invocation given the schema's presence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the prompt parameter only by title, with 0% schema description coverage, so the description must compensate. It minimally ties the parameter to the purpose ('for this prompt'), but does not elaborate on format, constraints, or how the planner uses it. This is adequate but not rich.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (generate) and a specific resource (the Jev probe), and explicitly calls out 'but do not run', which distinguishes it from tools that would execute or otherwise interact with probes. This clearly positions the tool as a planning/generation step within the Jev family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you want the probe written without being executed, but it does not explicitly mention when to prefer this over siblings like jev_ask or jev_analyze, nor does it state when not to use it. Guidance is only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0jev_analyzejev_askjev_healthjev_planScored across 4 tools
Most tools are clearly distinct: health checks availability, plan generates a probe, and analyze runs the full pipeline. The slight overlap is between ask and analyze, since both involve asking the Open-Jev server questions, but ask is a direct query about a state while analyze runs the complete planner-to-Jev flow.
All tool names follow the same jev_<verb> pattern with clear verbs: ask, plan, analyze, and health. This makes the toolset highly predictable and easy for an agent to navigate.
Four tools is well-scoped for this focused server. Each tool covers a meaningful operation without redundancy or unnecessary surface area.
The core workflows are covered: checking health, inspecting a generated plan, asking direct questions, and running the full analysis pipeline. A minor gap is that there is no explicit tool to run a previously generated probe exactly, though analyze effectively covers the end-to-end use case.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Coordinate coding agents through MCP using existing AI plans, saved work, and independent checks.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
