Skip to content

Agents and MCP

nodemode-ai edited this page Nov 8, 2026 · 1 revision

Agents and MCP

formlit speaks the Model Context Protocol so Claude, Codex and Cursor can work on your photos with tools, and it ships skills for agents that work on formlit's own code.

Use formlit from Claude

  1. Add the formlit plugin from the Form marketplace: in the Claude app open Customize, Plugins, or run /plugin in Claude Code. Claude's tools then appear under the name formlit.
  2. Open formlit. On a Mac the plugin opens it for you when it is closed; elsewhere Claude asks you to open it.
  3. Ask Claude for what you want: cull a shoot, develop a look, export for a client.
  4. The first time, formlit asks in its own window, for example "Claude Code wants to use formlit", with Allow, Not now and Block. Allow lets every agent on this computer in until you change it, Not now refuses only the request that was waiting, and Block turns outside agents off.

Change the answer any time in Preferences (File menu), AI agents: Agent access is Ask me, Allowed or Blocked, and Seen lists the agents that have called since formlit started. Claude waits up to two minutes for your answer, then tells you it is still waiting.

The plugin works in Cowork in the Claude desktop app and in Claude Code, which run on your computer. Claude chat on the web or the phone cannot reach apps on your computer.

Claude Code inside formlit

formlit's terminal dock (Window, Show Terminal, Ctrl or Cmd+J) runs real shells, and its Claude Code button (the sparkle in the title bar, or Ctrl or Cmd+Shift+J) opens your own Claude Code in a dock tab with formlit already attached. Install Claude Code from https://claude.com/claude-code and run claude once in any terminal to sign in; formlit finds it on the PATH, in the usual install folders or through your login shell, and FORMLIT_CLAUDE_BIN names it otherwise.

The tab starts in ~/Formlit/Agent (FORMLIT_AGENT_DIR) with formlit's server added over HTTP and its tools allowed, so you see Claude work in the terminal and the catalog change in the window at the same time. You started it, so it does not get the outside-agent prompt; it is listed as Claude Code in formlit under Seen, and Blocked still refuses it. Type in the tab as in any terminal, or use the Ask line under the dock: it sends your request with the selected photo ids, starting Claude Code when it is not running.

./formlit claude (formlit.bat claude on Windows, through setup/claude_launch.py) starts the same thing in your own terminal over stdio; that session is an outside agent and goes through the prompt.

The server

The engine serves MCP over streamable HTTP at http://127.0.0.1:8390/mcp, on this computer only and with no token or header needed. The desktop app keeps its engine on port 8390 so the plugin's bridge finds it; if something else already holds 8390 the app picks a free port, which the plugin cannot follow. For development, ./formlit mcp is the stdio shim agents run; it starts the engine when it is not running. .mcp.json (Claude Code), .codex/config.toml and .cursor/mcp.json point at it for this repository, and ./formlit agents install registers it for your user account in all three.

There are 67 curated tools in eight groups (Look, Import and organize, Jobs and templates, Cull and people, Develop, Enhance and merge, Output, Window and history) plus run_command, which reaches any of the engine's 238 commands except the terminal and Claude Code ones. Jobs and templates: setup_shoot runs a shoot recipe (a collection set with All Photos and Picks, To Edit, Edited, Portfolio and Rejects intelligent collections limited to the shoot, then an optional import with the recipe's naming, metadata template and keyword set, and noise reduction by ISO); list_templates and apply_template cover the built-in filename, folder, metadata, keyword set, intelligent collection and export templates; noise_by_iso is formlit's take on Lightroom's ISO adaptive presets. Seven more prompts cover starting a job from a template, concerts, stock, night sky, wildlife, social batches and catalog maintenance. Professional practice has its own tools: import_photos takes the full ingest (copy or DNG, folder and rename templates, a copyright metadata preset, a develop preset, a second copy, duplicate skipping, previews), refine_photos runs a multi-pass cull, match_exposures is Match Total Exposures, and virtual_copy and snapshot keep alternate versions. Ten prompts describe professional workflows step by step: pro_ingest_and_cull, wedding_event_workflow, portrait_session_workflow, landscape_workflow, news_sports_workflow, real_estate_workflow, product_workflow, client_delivery, plus culling_workflow and develop_strategy. match_look fits a photo's tone, white balance and colour bands to a reference photo in one call; develop_set, develop_patch, apply_preset, sync_settings and match_look take report to return the measurement after the change, get_preview takes analyze, and analyze_photo takes ids for a set, so an agent rarely needs a follow-up call. save_preset stores a photo's look as a user preset; add_ai_mask takes people and landscape parts. analyze_photo measures a photo as developed, or with proposed values or a preset without saving: luminance percentiles, Adobe's five tonal zones, clipping, saturation, the cast of near-neutral pixels and each colour-mixer band, with findings that suggest develop values. get_preview previews a preset at any amount, and list_presets searches by purpose (query) and describes every preset. Two prompts, culling_workflow and develop_strategy, give agents a starting order of work. GET /api/mcp/status reports the endpoint, the counts and the protocol versions, and the tool get_agent_access reports the AI agents setting and which agents have called.

Skills

  • formlit-driving (.claude/skills and its .agents/skills mirror, and carried by the formlit plugin) teaches agents to use formlit: what to do before the first call, the measure, propose, check and commit loop, the develop ids, checking with previews. references/editing-guide.md explains every develop control the way Lightroom photographers use it, from Adobe's documentation and photography publications, with a source on each claim and single-source numbers flagged. Its references/tools.md and references/presets.md are generated by ./formlit agents sync; run it after changing backend/app/routers/mcp.py or the built-in presets.
  • formlit-harness (.claude/skills/formlit-harness) is the pack for changing formlit. Its director routes to engine-builder, pipeline-builder, ui-builder and release-keeper, with catalog-keeper, cull-assistant, develop-artist and output-producer as the photo depth behind the driving skill.

Safety

Outside agents are asked once. With Agent access on Ask me, the first tool call from an agent waits for your answer in formlit's window; Allowed lets calls run, and Blocked refuses them with a message that says where to change it. The check covers every tool call, from the plugin and from ./formlit mcp; connecting and listing the tools never needs it, and formlit's own window is never held up by it. It governs the MCP tools: any program on your computer that you run yourself can still reach the engine's local address, as the window does.

Deleting photos or folders and opening or creating catalogs are reserved for the person in the window unless FORMLIT_MCP_ALLOW_DELETE=1. An agent cannot answer its own prompt, and no agent can open, read or type into the terminal dock: run_command refuses terminal.*, claudecode.* and chat.* (the dock's Chat tab, which runs claude -p with formlit's tools only) whatever the settings. Every agent change is a command, so it is undoable like any other.

Clone this wiki locally