# LIWENJSON MCP server: local deployment guide

LIWENJSON is the execution gate for LLM output. `liwenjson mcp` runs that gate
as a Model Context Protocol server on your own machine: one native binary,
JSON-RPC 2.0 over stdin/stdout, no socket, no network, no API key, and no model
output leaving the machine.

This document is the canonical deployment guide. The host-side surfaces
(Python, Node, HTTP, the versioned `serve` protocol) are in
[INTEGRATIONS.md](INTEGRATIONS.md); the engine and its guarantees are in
[../README.md](../README.md).

## 1.5.2: the protocol contract the tools publish is now the one they satisfy

Every MCP tool publishes an `outputSchema`, and a strict client validates
`structuredContent` against it. Before 1.5.2 none of the four did:

| tool | what failed | what it is now |
| --- | --- | --- |
| `liwenjson_gate` | the schema required `text`, and the default response omits it (it is the rendered form of `value`, sent only for `with_text`) | `text` is optional in the schema; `with_text` is documented as the opt-in |
| `liwenjson_repair` | the schema required `rule`/`name`/`confidence_class`; the response had `code`/`threshold`/`confidence` | one record shape, written by `repair_record_json()` and described by `repair_record_fields()`; `analyze`, `repair`, `validate` and all four tools emit it |
| `liwenjson_validate` | same repair-record drift | same fix |
| `liwenjson_readiness` | the response carried `events`, which the schema neither declared nor allowed | `events` is declared, with `event`, `path`, `permille` |

The server also accepts its **own** published `inputSchema` as `schema_json`:
`additionalProperties: false` is implemented (SR-43), so the declarations this
server publishes are declarations it can enforce. `code/tests/mcp_contract_check.py`
runs the whole matrix against a built binary.

**A real client's handshake is replayed by a gate.** `code/tests/mcp_client_replay.py`
replays the requests Claude Code 2.1.308 sends on connect — `server/discover`,
`initialize`, `notifications/initialized`, `tools/list` — against the built
binary, and checks that every request is answered, that the handshake
negotiates a revision the server implements, and that the tool list arrives.
`code/tests/record_mcp_handshake.sh` re-records it.

The recording found a real defect: Claude Code sends `server/discover` *before*
`initialize`, and the server answered the probe with `-32002 not initialized`.
That refuses a question that needs no session, and a client less tolerant than
Claude Code would simply not connect. `server/discover` is now answered with the
same identity the handshake reports, plus the tool list.

**JSON-RPC 2.0 is now checked, not assumed.** `jsonrpc` must be exactly `"2.0"`,
`method` must be a string, `id` must be a string/number/null, `params` must be an
object or an array; anything else is `-32600`. A JSON-RPC **batch** is answered
with an array exactly on the revisions that require it (`2025-03-26`,
`2024-11-05`) and refused with a reason on `2025-06-18`, which dropped batching.
It used to answer a batch with a single `missing method`.

**`executable` is a JSON/schema verdict, not an authorization.** The label is
`JSON/SCHEMA POLICY PASSED`, the payload carries `business_authorized: false`,
and the summary the model reads says so in one line. A path that escapes its
root, a tool the user may not call, a `write` the user did not ask for: none of
those are visible to this component. Host policy still applies (audit §7.1).

**A refusal says whether a retry is safe.** `refusal.kind` is `syntax`
(retry it), `schema_or_intent` (do **not** retry automatically: the retry may
come back with a different action), `host_declaration` (fix the declaration) or
`provider` (nothing to retry). Only `syntax` has `auto_retry: true`
(audit §7.2).


## Why local

The gate sits between a model's raw output and the tool call a host is about to
execute. That position has three consequences:

- **The input is the sensitive part.** Tool arguments routinely contain user
  data, internal identifiers, and names that have not been authorized yet.
  Sending them to a remote validator would leak exactly what the gate is
  supposed to protect. `liwenjson mcp` opens no socket and makes no request, so
  the data path is `client → local process → client`.
- **There is no secret to manage.** No account, no token, no quota, no
  telemetry. A client starts the server with nothing but an executable path, so
  there is nothing to leak, rotate, or accidentally commit.
- **The decision does not depend on the network.** The same engine that the
  test suite pins makes the decision, offline, on every call. An outage cannot
  silently turn the gate into a pass-through, and an air-gapped machine gets
  the same behaviour as a connected one.

The trade-off is explicit: availability is the local machine's problem, and the
server never executes the JSON it inspects. It only decides, and returns the
sentence to send back to the model when the answer is no.

## What the server is

| Property | Value |
| --- | --- |
| Command | `liwenjson mcp` |
| Alias | `liwenjson-mcp` — the same binary under that name starts the MCP server with no arguments |
| Transport | stdio: one JSON-RPC 2.0 object per line on stdin, one per line on stdout |
| Protocol revisions | `2025-06-18`, `2025-03-26` and `2024-11-05` are all accepted verbatim; any other requested revision is answered with `2025-06-18` and is **never echoed back** |
| Server identity | `serverInfo.name = "liwenjson"`, `serverInfo.title = "LIWENJSON — the execution gate"`, `serverInfo.version` = engine version (`1.5.2`) |
| Capabilities | `tools.listChanged: false` (tools only; no resources or prompts) |
| Tools | `liwenjson_gate` (primary), `liwenjson_repair`, `liwenjson_validate`, `liwenjson_readiness` — all read-only |
| Request line limit | 8 MiB (8,388,608 bytes); a longer line is answered with JSON-RPC `-32700` and discarded through the next LF |
| Engine limits | nesting depth (`Options::max_depth`, default 512; the ceiling on it is documented in [`../SECURITY.md`](../SECURITY.md) and above it the option is refused with `E050`), input 67,108,864 UTF-16 code units, single token 16,777,216; a *declaration* deeper than the schema bound in `SECURITY.md` is refused with `E070` |
| Stdout | JSON-RPC messages only; diagnostics go to stderr |
| Notifications | never answered (`notifications/initialized`, `notifications/cancelled`) |
| State | stateless: every tool call is independent |
| Lifecycle | `initialize` first: a request that arrives before it is answered with JSON-RPC error `-32002` (only `initialize` and `ping` are exempt) |

The server is implemented once, in the native binary (`code/cmd/liwenjson/mcp.mbt`).
The pip launcher replaces its own process with `<binary> mcp`; the npm launcher
spawns it with inherited stdio. Neither reimplements the protocol, so there is
exactly one server and one engine.

## Install the engine

Pick one install path; each ends with a working `liwenjson` binary. Every
launcher and client below needs that binary, so verify it first:

```sh
liwenjson --version          # liwenjson 1.5.2
```

> **Technical preview.** The prebuilt binary comes from the GitHub release, which
> builds four binaries across three operating systems: `linux-x86_64`,
> `linux-arm64`, `macos-arm64` and `windows-x86_64`. Building
> from source needs the MoonBit toolchain `moon 0.1.20261016`. The mooncakes
> counterpart **0.13.0 was published on 2026-10-29**, and `interjson-moonbit@1.5.1`
> reached npm and PyPI on 2026-10-30, so both language packages install with one
> command. **1.5.2 is `liwenjson` on npm and on PyPI (2026-11-20)**; the mooncakes
> counterpart `0.14.0` is not published there yet.

### One command: `install.sh`

`code/install.sh` is the installer the release serves as
`liwenjson-install.sh`. It works out the platform, downloads the matching asset,
verifies its SHA-256 against the release's own `SHA256SUMS`, installs to
`~/.local/bin` (override with `LIWENJSON_DIR`) and prints the `PATH` line to add
if that directory is not already on `PATH`. A checksum that does not match is a
hard failure: the file is deleted and nothing is installed.

```sh
curl -fsSL https://github.com/wenhuang2333/LIWENJSON/releases/latest/download/liwenjson-install.sh | sh
```

`latest` serves `liwenjson-install.sh` and the `liwenjson-*` assets from `v1.5.2`
on, and the one-liner above is verified against that release: it checks the
release's own `SHA256SUMS` and installs `liwenjson 1.5.2`. Releases before it keep
the `interjson-install.sh` name — use that URL for `v1.5.1` and earlier.

Environment: `LIWENJSON_VERSION` (tag; default = latest release),
`LIWENJSON_DIR` (default `$HOME/.local/bin`), `LIWENJSON_REPO` (default
`wenhuang2333/LIWENJSON`). Exit codes: `0` installed, `1` download or
checksum failure, `2` unsupported platform.

### Build from source

The CLI is native-only (`supported_targets = "native"`), built with the pinned
toolchain `moon 0.1.20261016`. This is the install path for the `liwenjson`
surface today:

```sh
git clone https://github.com/wenhuang2333/LIWENJSON
cd LIWENJSON/code
moon build cmd/liwenjson --target native --release
./_build/native/release/build/cmd/liwenjson/liwenjson.exe --version   # liwenjson 1.5.2
```

Put the binary on `PATH` under the name `liwenjson` (or point
`LIWENJSON_BIN` at it); a second copy or symlink named `liwenjson-mcp` starts
the MCP server with no arguments:

```sh
ln -s "$PWD/_build/native/release/build/cmd/liwenjson/liwenjson.exe" /usr/local/bin/liwenjson
ln -s /usr/local/bin/liwenjson /usr/local/bin/liwenjson-mcp           # macOS / Linux
```

On Windows, copy `liwenjson.exe` to `liwenjson-mcp.exe` instead of creating a
symlink.

### Release assets

The release assets are `liwenjson-linux-x86_64`,
`liwenjson-linux-arm64`, `liwenjson-macos-arm64`,
`liwenjson-windows-x86_64.exe`, `liwenjson-probe.wasm`,
`liwenjson-demo.js`, `liwenjson-install.sh` and `SHA256SUMS`. There is **no
Intel macOS asset**: the MoonBit toolchain publishes no `darwin-x86_64` target,
so no runner can build one. `v1.5.2` publishes exactly these eight names. The
assets already published keep the name of the release that produced them:
`v1.4.0`–`v1.5.1` were published as InterJSON, with `interjson-*` assets and
`interjson_*` tool names, and `v1.3.0` and earlier as JSONMend, with
`jsonmend-*` assets and `jsonmend_*` tool names. No published asset is renamed
retroactively, so use the release whose prefixes match the CLI you install.

The 1.5.2 release is tagged `v1.5.2` and is published with those eight assets;
the mooncakes counterpart `0.14.0` is the 1.5.2 correspondence, so the installer
above installs the 1.5.2 binaries.

### pip: `liwenjson`

The Python distribution is `liwenjson` — the bare name, no suffix — and the
import is `liwenjson` too; it installs two console scripts.

```sh
pip install liwenjson
liwenjson --version          # liwenjson 1.5.2: the engine the launcher needs
liwenjson-mcp --version      # same output, through the console script
liwenjson-http --help        # HTTP facade; not needed for MCP
```

The wheel carries the engine for every release platform, so this is the whole
install: `liwenjson-mcp` starts with no `LIWENJSON_BIN` and no `liwenjson` on
`PATH`. Installing from a checkout (`python3 -m pip install ./code/python`)
builds the client without the binaries and needs one of the paths below.

`liwenjson-mcp` is a launcher: it resolves the engine, then replaces itself with
`<binary> mcp`, so stdin/stdout stay a clean JSON-RPC channel with no Python in
the middle. Resolution order:

1. `LIWENJSON_BIN` — an absolute path to the binary;
2. `liwenjson` on `PATH`;
3. the bundled binary for this platform (`liwenjson/bin/<platform>/`), which
   the PyPI wheel carries;
4. a binary placed directly in `liwenjson/bin/`;
5. the development build inside this repository.

If none is found it raises `FileNotFoundError` naming the install options; on a
platform the release does not build for (Intel macOS) the message names the
platforms the wheel does carry instead of suggesting a reinstall that cannot
help.

### npm: `liwenjson`

```sh
npm install -g liwenjson   # or: npm install liwenjson
liwenjson --version                # the native engine must resolve first
liwenjson-mcp --version            # passed through to `<binary> mcp --version`
```

Without a resolvable engine, `liwenjson-mcp --version` exits `127` with the
install instructions on stderr.

The package is `liwenjson` — the bare name, no suffix; its bin is
`liwenjson-mcp`, which runs
`mcp.cjs`. The versions on npm up to 1.5.1 are published as
`interjson-moonbit`; 1.5.2 is the first under this name. **The npm package is the JS engine — repair, partial parsing, and the
gate for in-process callers — not the MCP server. The server is the native
binary.** The launcher resolves the engine in this order:

1. `LIWENJSON_BIN`;
2. `liwenjson` on `PATH`;
3. the development build inside this repository.

It then spawns `<binary> mcp` with inherited stdio. With no binary it exits
`127` and prints the install options on stderr. An npm-only install therefore
gives you the library; build the native engine (or point `LIWENJSON_BIN` at a
release asset) as well before configuring a client.

## Configure a client

Every client below runs the same command. `liwenjson mcp --print-config=CLIENT`
prints the exact snippet, so prefer copying it:

```sh
liwenjson mcp --print-config=claude     # Claude Code command
liwenjson mcp --print-config=cursor     # mcpServers JSON (Cursor, Cline, Windsurf)
liwenjson mcp --print-config=vscode     # servers JSON
liwenjson mcp --print-config=codex      # TOML
liwenjson mcp --print-config=zed        # context_servers JSON
liwenjson mcp --print-config=json       # generic mcpServers JSON (the default)
```

`--print-config` prints `liwenjson` as the command, so it assumes the binary is
on `PATH`. If the client cannot see your shell `PATH` — common for GUI apps on
macOS — replace the command with an absolute path, or set `LIWENJSON_BIN` in
the environment the client starts the server with.

### Claude Code

```sh
claude mcp add liwenjson -- liwenjson mcp
claude mcp list          # shows `liwenjson` and whether it connected
```

Add `--scope project` to write `.mcp.json` into the repository instead of the
default local scope.

### Cursor, Cline, Windsurf (JSON, `mcpServers`)

```json
{
  "mcpServers": {
    "liwenjson": { "command": "liwenjson", "args": ["mcp"] }
  }
}
```

Cursor reads a global `mcp.json` (typically `~/.cursor/mcp.json`) or a project
`.cursor/mcp.json`; Windsurf reads its MCP config (typically
`~/.codeium/windsurf/mcp_config.json`); Cline uses the same `mcpServers` shape
in its MCP settings. The server name is a label only — the
tool names come from the binary you point at: `liwenjson_*` for `v1.5.2` and
later, `interjson_*` for the `v1.4.0`–`v1.5.1` binaries.

### VS Code

`.vscode/mcp.json` uses a `servers` object and requires an explicit transport
type:

```json
{
  "servers": {
    "liwenjson": {
      "type": "stdio",
      "command": "liwenjson",
      "args": ["mcp"]
    }
  }
}
```

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.liwenjson]
command = "liwenjson"
args = ["mcp"]
```

### Zed

`settings.json`:

```json
{
  "context_servers": {
    "liwenjson": {
      "command": {
        "path": "liwenjson",
        "args": ["mcp"]
      }
    }
  }
}
```

### Any other MCP client

```json
{
  "mcpServers": {
    "liwenjson": { "command": "/absolute/path/to/liwenjson", "args": ["mcp"] }
  }
}
```

Nothing in the configuration is LIWENJSON-specific beyond the command: the
server speaks plain MCP over stdio. If a client starts the server through
`liwenjson-mcp` instead, drop the `args` entry.

## The four tools

All four accept `text` (the raw model output) and optional `schema` /
`schema_json`. `liwenjson_gate` and `liwenjson_repair` also accept `profile`;
`liwenjson_validate` and `liwenjson_readiness` do not, because they never
repair.

| Tool | Title | Answers |
| --- | --- | --- |
| `liwenjson_gate` | Gate: may I execute this? | May this output be executed? `decision`, `executable`, `exactness`, ambiguity, schema satisfaction, `value`, `retry` |
| `liwenjson_repair` | Repair malformed JSON | What is the repaired document, and what was changed? |
| `liwenjson_validate` | Validate without repairing | Is this legal JSON, and does it satisfy the declaration? |
| `liwenjson_readiness` | When do fields become final? | At which input fraction is each declared field final? |

`profile` is one of `permissive`, `interactive`, `execution`, `agent`, `strict`.
**`liwenjson_gate` defaults to `agent` when the caller omits `profile`**, so a
host that never sets it still gets refusal instead of invention — even if the
server was started with a looser `--policy`. The other three tools use the
process-level `--policy` when one was given, and the engine default
(`permissive`) otherwise; an explicit `profile` argument always wins over the
process default.

That default is **exactly `Options::for_agent()`**, protocol included: the gate
resolves a profile by name through `Options::for_profile`, which applies the
safety knobs *and* the protocol the profile implies. For `agent` that means
`skip_prose: true`, so the most common shape of chat-channel output — a sentence
followed by the arguments:

```text
Here are the args:
{"a":1}
```

is **accepted by default**. Selecting `agent` by name used to apply only the
safety half, so the flagship tool refused that input with `E002`; the other four
profiles still refuse it (`execution`, `strict`, `interactive` and `permissive`
do not skip prose). `schema` is the declaration language
(`{!query:string,!limit:integer}`); `schema_json` is the tool's existing JSON
Schema subset (`type`, `properties`, `required`, `items`, `enum`, `const`,
`minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `minLength`,
`maxLength`, `pattern`). Unsupported keywords are refused with `E070` instead
of being silently ignored.

The subset is read as JSON Schema reads it, which means **the keywords on one
node are conjunctive and the order they are written in means nothing**:

- `const` and `enum` on the same node admit exactly `{const}` ∩ `enum`. When the
  constant is not in the enumeration the declaration can never be satisfied and
  is refused with `E070` — the gate never falls back to one of the two sets, so
  reordering the two keys cannot turn a refusal into an allow.
- A node with `const`/`enum` **and** `properties`/`items` enforces both: the
  value must be in the set *and* its required members / element kinds must hold.
- The root node is checked like every other node: `{"type":"string"}` refuses
  the number `42`.
- `items` is only accepted together with `type: "array"`, and
  `properties`/`required` only with `type: "object"`. The skeleton has no
  conditional, so a keyword the declared kind never reads is an `E070` rather
  than a silent drop.
- A declaration that can never be satisfied (an empty `enum`, a `const` outside
  its `enum`, `minimum` above `maximum`, a quantifier past `Int32`) is an
  `E070` at modelling time, not a gate that rejects everything at runtime.

All four tools honour the declaration they are given. `liwenjson_repair` parses
it — an unsupported keyword is `E070` — and refuses a repaired document that
violates it, so a declaration passed to `repair` is checked rather than
silently ignored.

Every `tools/list` entry carries a `title`, an `outputSchema` that is a real
per-tool schema, and annotations that say what the server can do to the world.
Each `outputSchema` is **closed** (`additionalProperties: false`) and names its
required fields:

| Tool | `outputSchema` properties | required |
| --- | --- | --- |
| `liwenjson_gate` | `decision`, `label`, `exactness`, `ambiguous`, `information_loss`, `valid_json`, `normalized`, `ambiguity`, `execution`, `executable`, `syntax_ready_permille`, `schema_total`, `schema_satisfied`, `schema_missing`, `error`, `repairs`, `retry`, `repairs_truncated`, `value`, `text` | all twenty |
| `liwenjson_repair` | `text`, `exactness`, `ambiguous`, `completeness`, `repairs`, `repairs_truncated` | all six |
| `liwenjson_validate` | `valid`, `schema`, `error`, `repaired`, `exactness`, `ambiguous`, `repairs` | `valid` |
| `liwenjson_readiness` | `syntax_permille`, `schema_permille`, `settled_permille`, `step`, `verdict` | the first four |

Before 1.5.0 the declaration was `{type: object, additionalProperties: true}`,
which told a client nothing and validated nothing. The annotations are:

```json
"annotations": {
  "title": "LIWENJSON",
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false
}
```

A successful `tools/call` carries the payload **once**. The two channels are
different views of the same call, not two copies:

- **`content[0].text`** is a short summary the model can act on. For the gate it
  is `decision=… executable=… exactness=…`, then `error=…` when there is one,
  then `retry (send this back to the model): <prompt>` when the call was
  refused. For `repair` it is the exactness line plus the repaired text; for
  `validate` it is `valid=…` and the error; for `readiness` it is the three
  fractions.
- **`structuredContent`** is the machine-readable object, once. A client that
  understands `structuredContent` reads it and never parses the text channel.

Before 1.5.0 both channels carried the same complete object, so a gate response
was two full copies of the payload on the wire — including the repaired document
inside each copy. A host pays for every byte, and the model only reads the text
channel, so the text channel is now a summary.

A tool *execution* failure is `isError: true` with a message the model can read
and **no `structuredContent`** (a JSON-RPC success, as the protocol requires).
A protocol-level failure is a JSON-RPC `error` envelope — see
[JSON-RPC error codes](#json-rpc-error-codes).

### `liwenjson_gate` result fields

| Field | Meaning |
| --- | --- |
| `decision` | `safe`, `cosmetic_repair`, `lossy_repair`, `ambiguous`, `invalid` |
| `executable` | the only field a host has to branch on; true only when the decision is `safe` or `cosmetic_repair` and a value exists |
| `exactness` | `exact`, `cosmetic`, `lossy` |
| `ambiguity` | `none`, `syntactic`, `semantic` |
| `information_loss` | true when a repair invented, dropped, or changed content |
| `valid_json` | whether the input was legal JSON as written |
| `normalized` | true when the value changed only in notation |
| `execution` | `allowed` or `blocked`; follows `executable` |
| `value` | what the engine parsed; **`null` whenever `executable` is `false`** (see below) |
| `text` | what the engine rendered; `""` whenever `executable` is `false` (see below) |
| `schema_total`, `schema_satisfied`, `schema_missing` | declared members, how many match, which are missing |
| `error` | `{code, message}` for the first refusal, or `null` |
| `repairs` | rule, position, severity, ambiguity class, confidence per change |
| `retry` | `{code, prompt}` — the prompt to send back to the model; **non-null with a non-empty `prompt` whenever `executable` is `false`, and `null` whenever it is `true`** |

`executable` is a property of the document, not of the profile: `permissive`
will repair a truncated document for display and still answer
`executable: false`, because executing it would mean executing a value the
model never wrote.

**The refusal contract.** A non-executable result always carries
`value: null`, `text: ""` and a non-empty `retry.prompt`; an executable result
always carries a live `value` and `retry: null`. This is not a property of one
profile — it holds under every profile. Branch on `executable` alone.

1.4.x broke this in the case that matters most: a document that was *accepted*
(nothing was refused) but *not executable* — a lossy repair under `permissive`,
or a value that fails its declaration — serialised as `"retry": null` while the
tool description told the caller to send `retry.prompt` back. The refusal had no
prompt, and the object carried a live `value` next to `executable: false`, which
is the one combination a host must never see. Both halves are now fixed and
asserted by `code/regression_1_5_wbtest.mbt` (TC-R-07, TC-R-08, TC-R-09).

### `liwenjson_repair`

Returns `text`, `exactness`, `ambiguous`, `completeness`, `repairs[]`, and
`repairs_truncated`. A profile that refuses a repair (`execution` or `agent`
with a lossy or ambiguous change) turns the call into `isError: true` with the
error code and message.

### `liwenjson_validate`

Returns `valid`, and when the text is repairable also `error`, `repaired`,
`exactness`, `ambiguous`, and `repairs`. With a declaration, a valid document
also gets `schema`: `{total, satisfied, missing, mismatched, ok}`.

### `liwenjson_readiness`

Returns `syntax_permille`, `schema_permille`, `settled_permille`, `step`, and
`schema`-style `verdict`: the input fraction, in per mille, at which the
document's syntax, its declared members, and both together are already final.
This is the call a host uses to stop a generation early.

## A real gate call

The model was asked for tool arguments and was cut off at `max_tokens`. The
host sends the raw text to the gate before executing anything, with the tool's
`inputSchema` as `schema_json`. No `profile` is sent, so the gate applies its
own default, `agent`.

Request (`id: 2`; the session's `initialize` is elided):

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"liwenjson_gate","arguments":{"text":"{\"query\":\"weather in Par","schema_json":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"}},"required":["query"]}}}}
```

`result.content[0].text` is the summary the model reads (this is the whole
text channel, verbatim):

```text
decision=lossy_repair executable=false exactness=lossy
error=E010 E010 StrictViolation at 1:25 (offset 24): R010 CloseString: exactness lossy exceeds max_loss cosmetic
retry (send this back to the model): LIWENJSON refused the arguments: E010 R010 CloseString at line 1 column 25 (offset 24).
Reason: exactness lossy exceeds max_loss cosmetic
Context: {"query":"weather in Par
                                 ^
Re-emit the arguments as valid JSON with exactly one reading.
```

Response, decoded from `result.structuredContent` (the payload once;
`result.isError` is `false`):

```json
{
  "decision": "lossy_repair",
  "label": "REJECT (a value was changed)",
  "exactness": "lossy",
  "ambiguous": false,
  "information_loss": true,
  "valid_json": false,
  "normalized": true,
  "ambiguity": "none",
  "execution": "blocked",
  "executable": false,
  "error": {
    "code": "E010",
    "message": "E010 StrictViolation at 1:25 (offset 24): R010 CloseString: exactness lossy exceeds max_loss cosmetic"
  },
  "retry": {
    "code": "E010",
    "prompt": "LIWENJSON refused the arguments: E010 R010 CloseString at line 1 column 25 (offset 24).\nReason: exactness lossy exceeds max_loss cosmetic\nContext: {\"query\":\"weather in Par\n                                 ^\nRe-emit the arguments as valid JSON with exactly one reading."
  },
  "value": null,
  "text": ""
}
```

`retry.prompt` is the message to hand back to the model, unchanged:

```text
LIWENJSON refused the arguments: E010 R010 CloseString at line 1 column 25 (offset 24).
Reason: exactness lossy exceeds max_loss cosmetic
Context: {"query":"weather in Par
                                 ^
Re-emit the arguments as valid JSON with exactly one reading.
```

The host re-sends it, the model re-emits complete arguments, and the second call
is the one that may execute:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"liwenjson_gate","arguments":{"text":"{\"query\":\"weather in Paris\",\"limit\":3}","schema_json":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"}},"required":["query"]}}}}
```

```json
{
  "decision": "safe",
  "label": "SAFE TO EXECUTE",
  "exactness": "exact",
  "executable": true,
  "execution": "allowed",
  "schema_total": 2,
  "schema_satisfied": 2,
  "schema_missing": [],
  "error": null,
  "retry": null,
  "value": { "query": "weather in Paris", "limit": 3 }
}
```

The loop is the whole interface: execute only when `executable` is `true`;
otherwise send `retry.prompt` back and try the re-emitted arguments. A
conforming host applies the same rule to every tool call, not just to the ones
where the model remembered to ask.

## JSON-RPC error codes

Two kinds of failure look similar in a log and mean opposite things. The
distinction is the difference between "the tool ran and refused" and "the tool
was never called correctly":

| Code | When | What it means | `structuredContent`? |
| --- | --- | --- | --- |
| `-32002` | a request other than `initialize` or `ping` arrives before the handshake | the session is not initialized | no |
| `-32602` | `tools/call` with an unknown `name`, or with `arguments` that is not an object | the *call* is malformed; no tool ran | no |
| `-32602` | `tools/call` with no `name` at all | the call is malformed | no |
| `-32601` | an unknown `method` | the method does not exist on this server | no |
| `-32700` | a line that is not valid JSON, or longer than 8 MiB | framing/parse failure; the line is discarded through the next LF | no |
| (no error) | a valid call whose document is refused | **this is a success**: the tool ran, `isError` is `false`, `executable` is `false` | yes |

The last row is the one to internalise. A gate refusal is not an error — it is
the product working. `-32602` for an unknown tool used to come back as a
tool-level `isError: true` result, which told the host "the tool ran and
refused" and hid a typo in the tool name behind a document-level failure; a
non-object `arguments` used to be read as "no arguments" and produced a
confusing complaint about a missing `text`. Both are protocol errors now
(`code/cmd/liwenjson/mcp.mbt`).

## Privacy and security model

**What leaves the machine:** nothing. `liwenjson mcp` is a stdio process. It
creates no listening socket, resolves no host name, and issues no request; the
MCP input is the only data it reads, and the answer is the only data it writes.
You can confirm the absence of a network surface from the process itself:

```sh
lsof -p "$(pgrep -f 'liwenjson mcp' | head -1)"     # no TCP/UDP entries
```

**What it stores:** nothing. There is no cache, no temp file, no database, and
no state between calls. The text lives in process memory and dies with the
process. The server writes diagnostics to stderr only; whether a client keeps
those logs is the client's decision.

**What it can do:** only answer. All four tools are annotated read-only,
idempotent, non-destructive, and closed-world. The server never evaluates,
executes, or interpolates the JSON it inspects — it parses it, and returns a
verdict plus, when refused, a sentence describing what to change. A model that
calls the gate cannot use it to run a command, read a file, or reach a host.

**What it does not protect you from:** a model that emits *valid* JSON with the
wrong values. The gate checks syntax, exactness, ambiguity, and the declared
schema; it cannot know that `{"amount": 100}` should have been `1000`. Treat
`executable: true` as "safe to hand to the tool", not as "semantically correct".
It is also not an authorization system: the host still decides which tools a
model may call.

**Plain MCP is advisory.** `liwenjson_gate` is a tool the model *may* call. A
model can skip it, and the protocol gives the host no way to make the call
mandatory — so "the client is configured for LIWENJSON" means "the gate is
available", not "every tool call passed the gate". Nothing here detects or
prevents that; it is a property of MCP, not of this server.

What makes it mandatory is a host-side insertion point the model cannot route
around:

- a Claude Code **`PreToolUse` hook**, which runs on every matching tool call
  before execution and can deny it with the retry prompt;
- one **`gate(args)` call in the host SDK** on the path that turns a tool call
  into an execution;
- `liwenjson serve`, the npm/pip packages, or the HTTP facade, all of which run
  on the host side.

Recipes for the first two are in
[INTEGRATIONS.md](INTEGRATIONS.md#making-the-gate-mandatory).

**Resource limits:** one request line may not exceed 8 MiB; a longer line gets
`-32700` and is discarded through the next LF. The engine's own limits (depth,
input 67,108,864 code units, token 16,777,216) apply per call and are reported
as `E020`/`E021`/`E022`; a declaration past the schema bound is `E070`, and a
`max_depth` above the ceiling in [`../SECURITY.md`](../SECURITY.md) is `E050`. A
client should still run one server process per session and supervise it.

**Hardening notes:** run the server as the user who owns the data, not as root;
point `LIWENJSON_BIN` (or the client's command) at an absolute path you control
rather than trusting a writable `PATH` entry; verify `SHA256SUMS` for a
downloaded binary. Do not bridge stdio to a TCP port without adding
authentication and TLS — MCP over stdio has no authentication because there is
no network peer to authenticate.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Client shows no tools / "server failed to start" | The client cannot find `liwenjson` (GUI apps often do not inherit the shell `PATH`) | Use an absolute path in the client config, or set `LIWENJSON_BIN` for the client's environment |
| `liwenjson-mcp: the LIWENJSON engine was not found.` (exit `127`) | npm bin installed without the native engine | Build the native engine or set `LIWENJSON_BIN` |
| `FileNotFoundError: the liwenjson engine was not found` | the launcher could not resolve an engine — a checkout install rather than the PyPI wheel | `pip install liwenjson` from PyPI, or put `liwenjson` on `PATH`, or set `LIWENJSON_BIN` |
| JSON-RPC `-32700 parse error` on every line | Something other than the server wrote to stdout (a wrapper banner, `print`, a shell profile) | Run `liwenjson mcp` directly; keep stdout for JSON-RPC and send logs to stderr |
| JSON-RPC `-32602` with ``unknown tool `…` `` | The call itself is wrong, not the document | Check `tools/list`; the tool name must be one of the four |
| JSON-RPC `-32602` with `` `arguments` must be an object `` | `arguments` was an array, a string or a number | Send `arguments` as a JSON object |
| JSON-RPC `-32002` `server not initialized` | A request arrived before `initialize` | Send `initialize` first; only `initialize` and `ping` are answered before the handshake |
| `result.isError: true` with `E070 SchemaError` | The declaration uses a keyword the subset does not support, is unsatisfiable, or the value (or the repaired document) violates it | Use the listed subset, or drop `schema_json`; the message names the offending keyword or member |
| `executable: false` and no error | This is a successful refusal: the gate did its job | Send `retry.prompt` to the model and re-emit |
| `-32700 message exceeds MAX_LINE` | One request line is over 8 MiB (8,388,608 bytes, measured on the UTF-8 line) | Split the work into smaller calls; the cap is fixed |
| Client asks for an unknown `protocolVersion` | Only `2025-06-18`, `2025-03-26` and `2024-11-05` are implemented | The server answers `2025-06-18` and never echoes the unknown string; upgrade the client or accept the negotiated revision |
| `liwenjson-mcp` is "not found" on Windows | A symlink is not the native way to alias an executable | Copy `liwenjson.exe` to `liwenjson-mcp.exe`, or use `liwenjson.exe mcp` in the config |

The server never prints a banner, a version, or a warning on stdout. If a client
reports a JSON-RPC framing error, the first thing to check is the wrapper around
the server, not the server.

## Verification

Run these from a checkout; `B` is the built binary.

```sh
B=./code/_build/native/release/build/cmd/liwenjson/liwenjson.exe

"$B" --version                     # liwenjson 1.5.2
"$B" mcp --print-config=claude     # claude mcp add liwenjson -- liwenjson mcp
"$B" mcp --help                    # names liwenjson_gate and the six named clients
```

A full handshake without a client library:

```sh
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | "$B" mcp
```

The first line must report `"name":"liwenjson"`, `"protocolVersion":"2025-06-18"`,
and a non-empty `instructions`; the second must list the four tools with
`readOnlyHint: true` and a closed `outputSchema`.

The repository's own gates cover the same surface:

```sh
# 19 protocol/MCP conformance groups, including the mcp group
python3 code/tests/conformance/run_conformance.py --cli "$B"

# command line assertions, including --print-config and initialize
bash code/tests/cli_smoke.sh
```

`19/19 conformance groups passed` and `122 passed, 0 failed` are the expected
lines. The conformance suite starts the server itself, performs
`initialize` (including the `2024-11-05` fallback), checks that a notification
produces no response, and calls `tools/list` and each tool — it is the
executable definition of this document.

## Relationship to the other surfaces

| Surface | Side of the loop | Transport |
| --- | --- | --- |
| `liwenjson mcp` | model-side: the model **may** call the gate as a tool (advisory) | MCP over stdio |
| Claude Code `PreToolUse` hook | host-side: every matching tool call is gated before execution | hook process, [INTEGRATIONS.md](INTEGRATIONS.md#claude-code-pretooluse-hook) |
| `liwenjson serve` | host-side: the application gates every tool call | versioned JSONL, [PROTOCOL.md](PROTOCOL.md) |
| npm / pip packages | host-side: in-process or one long-lived client | JS bundle / stdio client |
| `liwenjson-http` | host-side: gateways and no-code tools | HTTP, [INTEGRATIONS.md](INTEGRATIONS.md) |

MCP is the discovery surface: it works with any MCP client without code. The
host-side surfaces are where the guarantee is strongest, because they run
whether or not the model chose to ask — MCP alone is advisory, and this document
says so rather than implying otherwise.
