MCP

Plugin MCP

Schemas in package.json (tinker.mcp.tools); handlers in src/mcp.ts; shared helpers in share/lib/mcp.ts.

Arguments

• plugin-name: plugin folder name (e.g. tinker-image-compressor, image-compressor)

References

Tool design

Pick granularity by plugin shape — not by toolbar button count.

Don't expose one MCP tool per toolbar control (e.g. cropper rotate/flip/undo). If headless save is blocked by a dialog, add an optional path arg to the existing save* method — don't invent a separate MCP-only API.

Implement

1. package.json

Under tinker.mcp.tools:

• description — for agents; note prerequisites (Call open first…)
• inputSchema (optional) — JSON Schema; CLI validates before callTool

Tool names: snake_case. Put type/range/required constraints in inputSchema — do not re-validate them in mcp.ts. Cross-field rules the schema can't express stay in the handler.

2. src/mcp.ts

import { createPluginMcpApi, type PluginMcp } from 'share/lib/mcp'
import type { Store } from './store'
import pkg from '../package.json'

interface MyToolArgs {
  path: string
  quality?: number
}

export function createMcpApi(getStore: () => Store): PluginMcp {
  return createPluginMcpApi(getStore, pkg, {
    my_tool: myTool,
  })
}

async function myTool(store: Store, args: MyToolArgs) {
  if (!store.ready) {
    throw new Error('Not ready. Call open first.')
  }
  const quality = args.quality ?? store.quality
  return { ok: true, path: args.path, quality }
}

Only when the plugin has AiChat: export getToolArgSummary(name, args) for tool-arg previews if the default (command / content / path / …) is not enough. Return the full string — ToolCard truncates in the UI (tinker-regexp). Do not add getToolArgSummary when the plugin has no AiChat.

3. Wire store

import { createMcpApi } from './mcp'

export class Store extends BaseStore {
  readonly mcp = createMcpApi(() => this)
}

Call existing store APIs. Don't add store methods solely for MCP unless the UI would need the same headless path. Canvas/ffmpeg that only lives in UI handlers may sit in mcp.ts when it still ends in the same store calls (setCroppedImage + applyCroppedImage).

4. Handler rules

Host and AiChat catch thrown errors and format them as Error: ... (AiChat also marks the tool as error). CLI validates inputSchema before callTool, so required fields can be typed as required.

const quality = args.quality ?? store.quality

5. Verify

cd <plugin-name> && npm run build
cd <plugin-name> && npx tsc --noEmit 2>&1 | rg "mcp\.ts" || true

Live tool checks in this repo must use ./bin/tinker-dev from the tinker repo root (see .agents/skills/tinker-dev/SKILL.md). Do not use the packaged tinker CLI while developing here.

# from tinker repo root
./bin/tinker-dev relaunch   # after package.json MCP changes
./bin/tinker-dev open <plugin>
./bin/tinker-dev tools <plugin>
./bin/tinker-dev call <plugin> --tool <name> --args '{}'

MCP registers after the plugin window finishes loading; if call fails with "not ready", wait briefly and retry.

Run the lint skill on changed files afterward.

Audit

Read <plugin-name>/package.json, src/mcp.ts, and src/store.ts. Check against the Implement rules above (schema ↔ args, handler map ↔ tool names, store wiring, throw-not-return errors, no JSON.stringify, design granularity, no getToolArgSummary unless AiChat is wired).

Report:

[Category] file/path:line — description

If clean: No MCP violations found. Otherwise list by category with total count.