liriliri/tinker/mcp

Tinker MCP

Plugins can expose MCP tools via tinker.mcp.tools in package.json. The CLI bridges them with `tinker call` (one-shot) and `tinker mcp` (stdio server for clients).

Plugins with MCP are tagged [mcp] in tinker list <plugin> output. The plugin must be running before any tool call (tinker open <plugin>).

For plugins that declare MCP tool open with an arg property, you can seed content in one step:

tinker open code-editor .
tinker open json-editor ./data.json

If the plugin has no open({ arg }) tool, the optional arg is ignored.

No [mcp] tag → no tools / call API. Use the ui skill instead (see When MCP is not available).

The MCP loop

tinker list --short
tinker list <plugin>…                    # confirm [mcp]
tinker open <plugin>
tinker tools <plugin>                    # names + inputSchema (source of truth)
tinker call <plugin> --tool <name> [--args '<json-object>']

For MCP clients that spawn a server process, use tinker mcp <plugin> instead of call.

Direct tool calls

tinker open json-editor
tinker tools json-editor
tinker call json-editor --tool get
tinker call json-editor --tool set --args '{"content":"{\"hello\":true}"}'
tinker call json-editor --tool format

• --args must be a JSON object (default {}).
• Results print as plain text or JSON depending on the tool.
• Always run tinker tools <plugin> before the first call on an unfamiliar plugin.

Stdio MCP server

tinker open json-editor
# MCP client config: command `tinker`, args `["mcp", "json-editor"]`
tinker mcp json-editor

The server fetches tool definitions from the plugin package, exposes them via listTools, and forwards callTool to the running plugin over IPC.

mcp needs an active IPC connection (auto-launch may not cover it — start Tinker first if needed). Keep the plugin open while the client session is active.

Wire into an MCP client

1. tinker list --short / tinker list <plugin> — pick a [mcp] plugin.
2. Client config: command tinker, args ["mcp", "<plugin>"].
3. Before tools are used: tinker open <plugin>.
4. Keep Tinker running for the session.

Recover from stale state

tinker restart <plugin>              # stuck / stale plugin window

After changing tinker.mcp.tools in package.json:

tinker relaunch
tinker open <plugin>
tinker tools <plugin>
tinker call <plugin> --tool <name> --args '{}'

When MCP is not available

tinker skills path ui
tinker open <plugin>
tinker ui <plugin> snapshot --inline

Command reference

Lifecycle (list / open / ps / restart): see core.

Troubleshooting

`Plugin is not running...` — tinker open <plugin> before call or before the client invokes tools.

`does not support MCP` — Pick a [mcp] plugin, or use ui.

`Unknown tool "..."` — Run tinker tools <plugin>.

`Failed to connect` / `Tinker is not running` — Start Tinker; mcp and call need the IPC socket.

Tool returns an error string — Match --args to inputSchema from tinker tools.

Client lists tools but calls fail — Plugin may have closed; tinker ps and tinker open <plugin> again.

Working safely

MCP tools run in the user's Tinker session with their data. Read tinker tools before unfamiliar calls — some mutate data immediately. Do not put secrets on the command line if shell history matters.