common/org.js.lolifamily.minecraftmcp.mcp/McpJson

McpJson

internal object McpJson

Everything this endpoint puts on the wire: JSON-RPC envelopes, MCP tool results and the tools/list prose. All pure functions of their arguments, which is why they are here rather than in McpServer — that file keeps what needs a live server behind it.

Every string here is read by a model, not by a maintainer, and is written to lower FRICTION — not to be complete, and not to be exact. A reader's attention is spent on every call and prose earns none of it back unless it changes which call comes next: a caveat for a corner the caller will not reach, or a "do not do X", is billed on every request and collected on almost none. Cover the path taken, then stop.

One guarantee stands against that: a SUCCESSFUL result is ground truth — a caller may build on it without checking. Nothing else is promised. A description may be incomplete, and a failure report is written to point at the next correct action rather than to account for what happened. Where that account matters it goes in a KDoc, which costs a model nothing.

Types

Param

private class Param(val name: String, val description: String, val required: Boolean = false, val enum: List<String>? = null, val default: String? = null, val type: String = "string")

One tool parameter. enum and default are structured schema fields, so the prose never has to name them; default is written as a string whatever type says, and emitted as that type.

Properties

COMMAND_PROSE

private val COMMAND_PROSE: Map<String, String>

Same for run_command's two identities.

LANE_PROSE

private val LANE_PROSE: Map<String, String>

What each lane IS. Which ones a caller sees, and which is the default, are the schema's enum and default instead — so a host that has no client lane never describes one.

Functions

envelope

private fun envelope(id: JsonElement?): JsonObject

add documents a null value as converted to JsonNull — the "id": null JSON-RPC owes an id-less request.

error

fun error(id: JsonElement?, code: Int, message: String): JsonObject

instructions

fun instructions(): String

The initialize prose: launch constants a script could read for itself, carried here so no eval is spent asking. The mod's own version is not repeated — serverInfo.version has it.

jsonObject

inline fun jsonObject(build: JsonObject.() -> Unit): JsonObject

success

fun success(id: JsonElement?, result: JsonObject): JsonObject

tool

private fun tool(name: String, description: String, vararg params: McpJson.Param?): JsonObject

The MCP envelope every tools/list entry shares. Written once here instead of once per tool: what differs between two tools is their prose, and this is the part that doesn't.

toolImage

fun toolImage(id: JsonElement?, image: ByteArray): JsonObject

toolsList

fun toolsList(): JsonArray

The tools/list payload: the tools' prose. tool carries the shape they share.

toolText

fun toolText(id: JsonElement?, text: String, isError: Boolean): JsonObject

text goes out whole: a clipped result is no longer ground truth, and only the client knows its own context budget — a capable one spools a large result to disk and reads it back on demand.