General Decision MCP

中文指南

An advisory-only MCP server for deployment/security decisions, coding-loop control and plan comparison. It calls the native System One API, not Chat Completions. One implementation serves stdio and stateless Streamable HTTP.

Architecture and implementation choice

Client → General Decision MCP → CLIProxy /v1/systemone → configured decision provider. The existing gateway handles provider credentials and routing; this service holds only its downstream key. Alternatively, typesafe mode calls the official native endpoint directly.

This is a small source derivative of pinned MIT references jkudish/jev-mcp and burnigtm/jev-mcp. It reuses pure tool/question/policy and transport-boundary patterns, not either complete runtime. See notices.

The official MCP SDK handles protocol negotiation. Unlike the unmodified reference implementation, this package has dependency-injected providers, explicit output schemas, native structuredContent, no inference deadline, no automatic retry, and mandatory separate HTTP authentication. The TypeSafe SDK's mandatory positive request timeout is why the native transport uses Node HTTP/HTTPS rather than that SDK. No shell, file-reading, arbitrary URL fetching, feedback storage or infrastructure execution tool exists.

This standalone repository runs independently of CLIProxy's Go source tree. It is not a gateway-hosted /v0/mcp/servers/general-decision endpoint and does not modify existing clients or production configuration. Its repository is https://github.com/Magnetic015/GeneralDecisionMCP; private: true in package.json only prevents accidental npm publication.

Related MCP server: Effort MCP Server

Install and start

Requires Node >=22. Use the repository-approved runtime manager if installing Node. From this package directory:

npm ci --ignore-scripts --registry=https://registry.npmjs.org

npm run build

Create a private .env using .env.example. Set the full native endpoint and gateway downstream key. Do not copy placeholder values unchanged or commit real keys. On POSIX keep secret files mode 0600; on Windows restrict their ACL to the service/user account.

JEV_PROVIDER=compatible
JEV_API_BASE_URL=https://gateway.example.com/v1/systemone
JEV_API_KEY=REPLACE_WITH_GATEWAY_KEY
JEV_MODEL=jev-latest
JEV_MCP_TRANSPORT=stdio

The endpoint is sent exactly as configured; nothing is appended. JEV_MODEL and legacy JEV_MCP_MODEL are accepted, but conflicting values fail startup. A configured provider never changes because an unrelated credential exists in the environment. Unsupported providers fail explicitly.

Local stdio:

node --env-file=.env dist/index.js

HTTP mode requires an independent random token of at least 32 characters:

DECISION_HTTP_HOST=127.0.0.1
DECISION_HTTP_PORT=8737
DECISION_MCP_TOKEN=REPLACE_WITH_A_SEPARATE_LONG_RANDOM_TOKEN
DECISION_MAX_IN_FLIGHT=4

node --env-file=.env dist/index.js --http

--http overrides JEV_MCP_TRANSPORT. /mcp accepts authenticated POST requests; /health reports only liveness, not upstream access. This is static header-based Bearer authentication for controlled clients, not an OAuth authorization server. URL/path/query tokens are rejected. The upstream key and MCP token must differ.

For non-loopback/container binds, set DECISION_HTTP_ALLOWED_HOSTS to exact client-facing authorities (including a non-default port). Requests with an Origin header must match DECISION_HTTP_ALLOWED_ORIGINS (comma-separated exact origins); without an override, only the local service origin is allowed for loopback binds. Client applications without Origin are accepted after authentication. Do not depend on CORS as authentication or trust forwarded headers implicitly.

Cancellation follows the original HTTP request's abort/disconnect signal. Because this endpoint is stateless, separate legacy notifications/cancelled POSTs cannot identify an earlier client's stream safely: they are explicitly rejected (409, or 429 while saturated), not silently acknowledged. A client that only sends those notifications should use stdio instead; merely sending a notification does not cancel the original inference. HTTP batch calls are rejected. A shared call-level limiter also bounds stdio inference, and duplicate active stdio IDs abort the original work.

Pre-authentication sockets are capped at max(16, 4 * DECISION_MAX_IN_FLIGHT). There is no inference deadline or inbound receive timer in this service. Slow authenticated callers can occupy bounded slots; a public deployment therefore requires a trusted ingress with header/body receive limits and connection/rate controls. Do not expose this listener directly to the Internet.

Each credential accepts a mutually exclusive _FILE source: JEV_API_KEY_FILE, TYPESAFE_API_KEY_FILE, DECISION_MCP_TOKEN_FILE. Files are read at startup only, must be regular non-symlinks, at most 8192 bytes, and private on POSIX. An HTTP token is not required for stdio.

Client registration

Copy/merge one selected template; do not overwrite existing configuration:

Replace the Windows paths for your checkout. Local examples explicitly use Node's --env-file, not assumed client interpolation. Remote examples intentionally use different environment syntax: ${NAME} for Code client, ${env:NAME} for Cursor, {env:NAME} for OpenCode, and bearer_token_env_var for Codex. These variables must be visible to the client process. DECISION_MCP_URL is the deployed HTTPS MCP /mcp URL, not the native inference endpoint. Register either stdio or HTTP for one instance to avoid duplicate tool catalogs.

Optional container

compose.example.yaml is opt-in and is not automatically started. It publishes only 127.0.0.1:8737, runs non-root with a read-only root filesystem and no host repository/Docker socket. Its two file secrets must be readable by the container service UID (default 1000) and retain private permissions; Compose file-backed secrets preserve host ownership/mode, so prepare them accordingly. Override the container user when the deployment requires a different UID/GID. The host endpoint and its port must match the allowed-host setting.

TLS termination, remote routing, production key provisioning and firewall changes require a separate deployment decision. No public endpoint is provisioned by this repository change. The example image is pinned; rebuild and review it before production use.

Tools and output

Nine tools are registered. No aliases or upstream tools outside this list are implied:

Use all nine calls and the advertised tools/list schemas for exact nested fields. Evidence/items/claims use {id,text}; candidates/classes use {id,description}. Optional scope defaults to unknown on every tool. For jev_risk, environment and consequence scope are independent: staging/development never imply local, and scope=local cannot override a production/security floor. evidence_complete defaults to false. Caller-provided facts are claims, never independent proof or authorization. Unknown input fields cannot override endpoint, model, thresholds or credentials.

Every result has schema_version, status, tool, provider, requested_model, actual model (nullable), validated native answers, policy, evidence, usage (nullable), and tool-specific summary. Opaque native question IDs are mapped to meaningful labels/IDs by summary. The JSON text fallback equals structuredContent.

policy.advisory_only is always true and policy.authorization is always not_granted. requires_human=false is a low-risk advisory classification, not permission to execute. Provider/tool-handler failures have isError:true, a fixed safe error code, and human review required. SDK-level argument/protocol validation may instead return text-only isError or a JSON-RPC error; clients must check errors before accessing structured data. Upstream error bodies, credentials and stack traces are not reflected.

Confidence and operational safeguards

• Native Choice confidence describes distribution concentration, not correctness: for Typesafe, (pmax - 1/n) / (1 - 1/n). It is not the top-two margin. Both the native value and original distribution are retained.

• Score remains on its original ordered 0..n-1 scale, with exact legend and expected-value consistency checks.

• Noul contains only p; no fake native confidence is added. Missing confidence forces review where the policy needs it. Missing usage is null, never fabricated as zero.

• Choice advisory floors are fixed: native confidence >=0.85, winning probability >=0.85 and top-two difference >=0.20. Rubrics pass independently; favorable dimensions never average away a dangerous one. These are conservative starting rules, not measured accuracy guarantees.

• Production scope, security operations, GeoIP restrictions, fail2ban, SSH, new public exposure, irreversible changes and missing critical evidence require human review regardless of probability.

• Firewall reviews include IPv4/IPv6, forwarding/return traffic, administrative access, dependencies and tested rollback. Fail2ban reviews include trustworthy client IPs, proxies/shared exits, containers, matching breadth and bans/whitelists. GeoIP reviews include database staleness, legitimate users, VPN/CDN/shared addresses and rotating IPv6 prefixes; location is not maliciousness.

• Coding-loop facts can override a model proposal: repeated failures cannot produce another blind retry; failed/unverified tests cannot support stop-as-complete. Proposed capability tiers are labels, not actual model selection.

• Screening does not make untrusted content trusted. The server never runs instructions contained in logs, diffs, documents or option descriptions.

• Before operational use, evaluate false acceptance, false rejection and evidence coverage on labeled local cases. Pin an actual model version if reproducibility matters; jev-latest can change upstream behavior.

Provider extensions

Implemented today:

• compatible: full native endpoint, JEV_API_KEY, JEV_MODEL. Works with a gateway or self-hosted service that actually implements the System One contract.

• typesafe: fixed https://api.typesafe.ai/v1/systemone, TYPESAFE_API_KEY or _FILE. Uses the same timeout-free JSON transport, not the SDK's request timer.

OpenRouter's documented native Decisions API is https://openrouter.ai/api/alpha/decisions, not Chat Completions. A compatible profile can point there with its own key and a native model such as ~typesafe/jev-latest; this routing has not been live-tested here. Generic JSON-generating chat models do not acquire native calibrated probabilities merely by imitating this schema.

Cloudflare Clef is not implemented in this release; selecting cloudflare fails rather than silently routing somewhere else. A future adapter must map its per-model endpoint /client/v4/accounts/<account>/ai/run/@cf/cloudflare/clef (or clef-flash), bearer token and the documented short body selector clef/clef-flash, unwrap the actual v4 response, then call the existing validator. Do not copy the reference's typesafe/ slug prefix. See extension contract. Validate its question/context limits and instructions; never silently truncate evidence.

To compare providers, run two named MCP instances with separate environment/secret files. Their models, keys and endpoint state are isolated. Invoke both only on an explicit request. Keep disagreement visible and escalate rather than average probabilities or claim consensus proves safety.

Verification and limits

npm run typecheck

npm test

Tests use only loopback fixture providers and official MCP clients. They cover all primitives, schema failures, policy floors, exact URL/auth mapping, redirects/no retries, request cancellation, body/concurrency limits, stateless HTTP, stdio, and absence of inference during initialize/list. Native request body is capped at 256 KiB, response at 1 MiB, question count at 64. Oversized input is rejected, not truncated. This package imposes no inference timeout; callers must cancel abandoned work. Gateway policies may independently retry or time out and should be assessed separately.

No live inference, client installation or production deployment is part of the test suite. Container packaging is an optional example and needs its own build/run verification on the target host. Existing gateway MCP tests/build remain separate.

References

• TypeSafe confidence semantics

• Official MCP TypeScript SDK

• Cloudflare Clef

• OpenRouter Jev Decisions

• Code client MCP

• Cursor MCP

• Codex MCP

• OpenCode MCP