# Void

Void is a universal no-op MCP server that turns tool calls into freely shaped spaces for thought. Descriptions and input schemas guide what an agent articulates, while configured results can cue recursive in-context self-correction.

Technically, you supply one or more MCP tool definitions as inline JSON or JSON files when launching Void. Each definition freely sets the tool's description and object-rooted input schema, along with its name and fixed result. Void advertises the description and schema unchanged, performs no work with the arguments, and returns the result verbatim. In mutable mode, an agent can create and remove the same kind of tool during the session through `void_create_tool` and `void_remove_tool`.

It uses the MCP TypeScript SDK v2 and serves stdio only.

## Thinking with Void

[`examples/universal.json`](examples/universal.json) makes the loop explicit:

1. Choose a form that suits the current move: a napkin, decision ledger, glassboard, test sweep, or something invented in the moment.
2. Write the artifact into the tool call.
3. React to that artifact in thinking and visible response text: say what became apparent and what changes because of it.
4. Call `Universal` again with the improved understanding, continuing until the work settles.

[`examples/anything.json`](examples/anything.json) is the opposite extreme: an unrestricted object-shaped scratch space with no prescribed feedback. Use it when even naming the form would constrain the thought too early.

## Tool definitions

Every input source must contain a top-level JSON array. Each item has this shape:

```json
[
  {
    "name": "assumption_check",
    "description": "Stress-test the assumption most likely to break the current approach.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "assumption": {
          "type": "string",
          "description": "The load-bearing assumption."
        },
        "evidence": {
          "type": "string",
          "description": "What currently supports or contradicts it."
        },
        "change": {
          "type": "string",
          "description": "What you will change if it fails."
        }
      },
      "required": ["assumption", "evidence", "change"]
    },
    "result": "Now revise the approach around what you found."
  }
]
```

`description` is optional. `name`, `inputSchema`, and `result` are required. Tool names follow MCP's 1–128 character `A-Z`, `a-z`, `0-9`, `_`, `-`, and `.` convention. An empty result string is valid.

The input schema is checked before the tool is registered and then advertised unchanged through `tools/list`. Void deliberately does **not** validate custom tool calls against it. Arguments that violate the advertised schema still receive the configured result.

## Run

Pass one or more inline arrays, JSON files, or a mixture. Void concatenates their definitions in argument order and rejects duplicate names before starting the protocol transport. At least one definition source is required unless `--mutable` is enabled.

```sh
void-mcp ./base-tools.json ./project-tools.json '[{"name":"nope","inputSchema":{"type":"object"},"result":"Nope."}]'
```

Stdout belongs exclusively to MCP JSON-RPC. Startup errors and diagnostics go to stderr.

### Claude Code

After running `pnpm build`, add a project-scoped `.mcp.json` and replace `/absolute/path/to/void-mcp` with this repository's absolute path:

```json
{
  "mcpServers": {
    "void": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/void-mcp/dist/src/cli.js",
        "/absolute/path/to/void-mcp/examples/universal.json"
      ]
    }
  }
}
```

Claude Code asks for approval before using a project-scoped MCP server. Open `/mcp` to inspect the connection and exposed `Universal` tool.

## Live tools

Add `--mutable` to expose two management tools:

- `void_create_tool` invites the agent to invent and register a new thinking tool for the lifetime of the server process.
- `void_remove_tool` removes an ordinary tool present in the current session, whether loaded at startup or created live.

```sh
void-mcp --mutable
```

Mutable mode can start without any definition sources because its management tools can populate the server after startup. You can still pass startup definitions when useful. Created tools are ephemeral: an agent can try a first version, use it, remove it, and invent a better one without persisting the definition.

Creating or removing a tool emits `notifications/tools/list_changed` through the SDK. Management tools validate their own arguments because they mutate server state. They are reserved and cannot remove themselves.

Some clients expose a newly created tool only after the next turn boundary. This is client discovery behavior; the server registers the tool immediately.

For protocol debugging, `--debug-log <file>` appends structured JSONL events without writing to MCP stdout. The trace includes schemas and tool names, but only argument keys and configured-result lengths—not custom call values or result text.

```sh
void-mcp --mutable --debug-log ~/tmp/void-mcp/claude-code.jsonl ./tools.json
```

Without `--mutable`, neither management tool is exposed.

## Development

```sh
pnpm install
```

```sh
pnpm check
```