mcp-systemone
Allows the server to use local or hosted Ollama as the System One decision-model endpoint, enabling workflow routing, readiness and invariant gating, shell-command risk assessment, and answering typed questions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-systemone
An MCP server that gives coding agents four quick judgment tools backed by a
System One model (by default clef and clef-flash):
Tool | Asks | Returns |
| Which workflow fits this request? | workflow, |
| Is this plan / design / diff ready? Does it touch or break an invariant? |
|
| How risky is this shell command? | base |
| Any typed questions you supply | one answer per question |
It speaks only the System One protocol: POST {model, state, questions} → {answers}.
Any server that implements it works: a local Ollama, hosted Ollama, or another compatible server.
Project knowledge (invariants, workflows, risk rules) lives in a .systemone.json
file in your repository, never in the server code.
Requirements
Node.js 24 or newer
A System One endpoint serving a decision model (see Models)
Related MCP server: Hivelore
Models
The server works with any model served behind the System One protocol. Pick one model for
SYSTEMONE_MODEL and, optionally, a smaller or faster one for SYSTEMONE_FAST_MODEL.
Model | Where | Setup |
Ollama library |
| |
Ollama library |
| |
| not on Ollama | serve it with llama.cpp or another System One-compatible server, then point |
To use a hosted endpoint instead of a local server, see Hosted Ollama.
Install
No install step is needed: the agent setups below run the published package with
npx -y mcp-systemone, which downloads it on first use.
To pin it globally instead:
npm install -g mcp-systemone # then use `mcp-systemone` as the commandOr run from a clone:
git clone https://github.com/Meirdrarel/mcp-systemone.git
cd mcp-systemone
npm ci
node bin/mcp-systemone.js # stdio transportConfiguration (environment variables)
Connection settings come from the environment only; secrets never go in a repository file.
Variable | Default | Notes |
|
| |
|
| Appended to the base URL (base path prefixes are kept). |
| — | Full URL; overrides base URL + path. |
| — | Optional. Sent as |
|
| Used by |
|
| Used by |
|
| Positive integer. |
|
| 0 to 1. Answers below it are listed as low confidence (see Confidence). |
| — | Explicit path to a |
Blank values count as unset.
Hosted Ollama
SYSTEMONE_BASE_URL=https://ollama.com
SYSTEMONE_API_KEY=<your ollama.com API key>Agent setup
Add SYSTEMONE_* variables as needed. From a clone, replace npx -y mcp-systemone with
node /abs/path/to/mcp-systemone/bin/mcp-systemone.js.
Claude Code
claude mcp add --transport stdio systemone -- npx -y mcp-systemoneWith a hosted endpoint (keep --transport stdio between the --env pairs and the name):
claude mcp add --env SYSTEMONE_BASE_URL=https://ollama.com --env SYSTEMONE_API_KEY=<key> \
--transport stdio systemone -- npx -y mcp-systemoneAdd --scope user to enable it in every project.
Key from a secret store, Node from nvm
Claude Code starts the server without a login shell, so npx from nvm is often not on
PATH, and --env SYSTEMONE_API_KEY=<key> stores the key in plain text in the client
config. examples/mcp-systemone-wrapper.sh handles
both: it reads the key from the macOS Keychain (the script's comments show the Linux
libsecret line), resolves nvm's default Node at each start instead of a pinned
~/.nvm/versions/node/vX.Y.Z, and execs npx -y mcp-systemone. It stops with an error if
the key or Node cannot be found. Copy it from the repository, then:
security add-generic-password -s systemone-api-key -a "$USER" -w # prompts for the key
chmod +x ~/.local/bin/mcp-systemone-wrapper.sh
claude mcp add --scope user systemone ~/.local/bin/mcp-systemone-wrapper.shOther clients can use the same script as their command.
Codex
~/.codex/config.toml:
[mcp_servers.systemone]
command = "npx"
args = ["-y", "mcp-systemone"]
# env = { SYSTEMONE_BASE_URL = "https://ollama.com", SYSTEMONE_API_KEY = "<key>" }Codex starts the server without a shell, so $VAR and ~ are not expanded in command, args, or env.
opencode
opencode.json (project) or ~/.config/opencode/opencode.json (global):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"systemone": {
"type": "local",
"command": ["npx", "-y", "mcp-systemone"],
"environment": {
"SYSTEMONE_API_KEY": "{env:SYSTEMONE_API_KEY}"
}
}
}
}
}Older opencode (V1 config) puts the server directly under mcp instead of mcp.servers.
Project config: .systemone.json
{
"version": 1,
"invariants": {
"api-compat": "Public REST endpoints keep backward-compatible request and response shapes"
},
"workflows": {
"build": "New feature, component, or functionality to create",
"bugfix": "Fix a defect, failing test, or unexpected behavior",
"release": "Prepare, tag, or publish a release"
},
"risk_rules": {
"prod-db": { "description": "Connects to or modifies the production database", "level": "dangerous" }
}
}A fuller example is in examples/.systemone.json.
Discovery (first match wins)
SYSTEMONE_CONFIG. If it points to a missing file, every tool call fails.The MCP client's roots, in the order reported (if the client supports roots).
The server's working directory, walking up to the git root (the first directory containing
.git). Outside a git repository only the working directory is checked.Nothing found: built-in defaults (no invariants, no risk rules, default workflows).
The file is re-read when it changes, so edits apply without restarting the agent.
Every tool result ends with config: <path> or config: none (defaults).
Validation
A malformed file is a tool error naming the file and the problem. It never falls back to defaults silently.
versionis required and must be1; unknown top-level keys are rejected.Ids match
^[a-z][a-z0-9_-]{0,47}$; descriptions are non-empty strings of at most 300 characters.invariants: at most 12.risk_rules: at most 12,levelisneeds_confirmordangerous.workflows: 1–25 entries;other("None of the above") is appended when missing.
Merge rule
The project file replaces the built-in defaults; the calling agent can only add.
Default |
| Tool argument | |
Workflows ( |
| replaces | not accepted (use |
Invariants ( | none | sets |
|
Risk rules ( | none | sets |
|
Caller entries are validated like the file. An id that collides with the project's is an error, and the limits apply to the combined set.
Risk rules only raise risk
check always asks the fixed base risk question, in its own request that never contains
rule text. Each rule is one yes/no question, asked in a second, parallel request;
final_risk is the highest of the base rating and the level of every rule answered
"yes" with P ≥ 0.5 (safe < needs_confirm < dangerous). A repository or an agent can make
a command look riskier, never safer. If the model's reply is missing an answer, check
treats it as the risky case.
The base levels follow reversibility. safe covers only local commands that read or are
trivially reversible; read-only remote queries such as git fetch or gh pr list usually
rate safe too, but a push never does. Pushing to a new or existing feature branch is
needs_confirm; force pushes, pushes to the default or a protected branch, deleting remote
branches or tags, and publishing a release or package are dangerous. The model only sees
the command and its context: a bare git push with no context tends toward dangerous, so
pass the current branch in context, or add a risk rule for pushes to the default branch.
The first line names the rules involved: raised by lists the rules that set final_risk
above the base rating, and matched lists every rule answered "yes", including those at or
below the base, e.g. final_risk: dangerous (matched: shared-branch). The JSON has the same
in computed.final_risk.raisedBy and computed.final_risk.matched ([{id, level}]).
gate wording follows kind
With kind: "diff" or kind: "mr", ready and verdict ask whether the change is ready
to merge (approve = "Correct and ready to merge"). With plan, design or no kind, they
ask whether the plan is concrete enough to implement. Invariant questions are the same for
every kind.
Touched vs. violated invariants
Each invariant first gets a relevance question, invariant.<id>: does the change touch it?
Those answered "yes" (P ≥ 0.5) are listed in touches_invariants.flagged. Only when at least
one is flagged, gate sends a second request with one holds.<id> question per flagged
invariant: after this change, does it still hold? violated lists the flagged invariants with
P(holds) < 0.5; a missing answer counts as violated.
touches_invariants: yes (P=0.9; flagged: b, c; holds: b P=0.95, c P=0.2)
violated: cviolated catches a break the artifact shows, such as an added override. A break by
omission, a file that should have changed but is absent from the diff, can still come out as
holding, so treat a flagged invariant that holds as "check it", not as cleared. The JSON has
computed.touches_invariants.holds ({id: P}) and computed.violated ([id]).
Confidence
Each choice answer carries probabilities over its options; each yes/no (noul) answer carries
P(true). route, gate and check score how decided every choice and noul answer is:
confidence = (Σ pᵢ² − 1/k) / (1 − 1/k) k = number of options
= (2p − 1)² for a yes/no answer (k = 2)It is 0 when every option is equally likely and 1 when one option has all the probability,
whatever the number of options. It is not the probability that the answer is right: P=0.82
with the rest split between two options gives about 0.55. For choice answers it equals the
confidence field the endpoint reports.
Answers below SYSTEMONE_MIN_CONFIDENCE (default 0.2; for a yes/no answer, P between about
0.28 and 0.72) are listed in computed.uncertain and on a line such as
low confidence: risk, holds.c (ask the user)A missing or malformed answer is listed too. The list never changes final_risk,
touches_invariants or violated: it tells the agent to confirm with the user before acting
on those answers. urgency (a score) and decide answers are not scored.
Development
npm test # unit and server tests (mock System One server, no network)
npm run smoke # live calls against the configured endpoint; costs tokensReleasing
A release is one commit and one annotated tag on main:
On an up-to-date
mainwith a clean tree, add a## [X.Y.Z] - YYYY-MM-DDheading right under## [Unreleased], so the unreleased entries move under it andUnreleasedis empty.npm version <patch|minor|major> --no-git-tag-versionbumpspackage.jsonandpackage-lock.jsonwithout committing or tagging.npm test, then commitCHANGELOG.md,package.jsonandpackage-lock.jsonaschore: release X.Y.Z.git tag -a vX.Y.Z -m vX.Y.Z, thengit push origin main vX.Y.Z.
The Release workflow checks that the tag matches package.json and that CHANGELOG.md has
a non-empty section for the version, runs the tests, publishes to npm through trusted
publishing with provenance, then creates the GitHub release with that section as notes
(scripts/release-notes.mjs). The new version can take a few minutes to appear on npm after
the workflow succeeds.
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup, tests and pull request guidelines. Coding agents should also read AGENTS.md.
License
Licensed under either of
Apache License, Version 2.0 (LICENSE-APACHE)
MIT License (LICENSE-MIT)
at your option.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Deterministic allow/require_approval/deny verdicts for agent actions, before they happen.
The system of record for AI agent authority: playbooks, routed policy questions, reusable rules.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Your coding agent asks the business logic of your repository and checks commits before they land
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with queryable, version-controlled project rules and coding standards. Enables validation, rule-based guidance, and task summaries to keep AI work aligned with your project's conventions without repeating context.2MIT
- AlicenseAqualityBmaintenanceEnforces team knowledge and workflow policies for AI coding agents by providing context, decisions, and gates before code changes are made.165Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI coding agents to evaluate actions against team-defined policies, record decisions, and obtain human approvals for potentially risky operations.63 npm1-
- AlicenseAqualityFmaintenanceEnables agentic coding clients to enforce portable policy guardrails by evaluating proposed shell, file write, git, and network actions and returning allow, deny, or ask decisions.2MIT