From d0f01a515ea7209bdee2ccf96004f20187a343af Mon Sep 17 00:00:00 2001 From: David Mann Date: Thu, 12 Nov 2026 20:02:54 +0100 Subject: [PATCH] The ArtCraft Launcher's agents switch lets agents in Turning on ArtCraft Launcher > Settings > AI agents is the person's consent for every Craft app (craft-ai-integrations#195). While the AI-MCP flag is on and the launcher's app list (ArtCraft/mcp/apps.json) names photocraft, PhotoCraft accepts agents as if Let AI agents connect were ticked: the desktop app watches those files every 2 s and starts or stops the connection, and `mcp --live` checks them before every call. The page shows the box ticked and says the launcher turned it on; PhotoCraft's own choice is kept. Allow Agent Control off still refuses agents. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 2 + apps/photocraft/src/agent_link.rs | 28 +++++++ apps/photocraft/src/main.rs | 2 + book/src/security/automation-security.md | 2 +- crates/automation/Cargo.toml | 3 + crates/automation/src/agent_link.rs | 81 +++++++++++++++++++ crates/automation/src/live.rs | 37 ++++++--- crates/automation/tests/mcp_live.rs | 15 ++++ crates/ui-egui/src/prefs/prefs_ui/agents.rs | 20 ++++- .../src/prefs/prefs_ui/agents_tests.rs | 35 ++++++++ crates/ui-egui/src/services.rs | 7 ++ docs/control-protocol.md | 2 +- docs/mcp.md | 10 +++ 13 files changed, 228 insertions(+), 16 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 5ea10652e8..a725a21b88 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5562,7 +5562,9 @@ dependencies = [ "base64 0.23.1", "cap-std", "clap", + "craft-flags", "craft-psd", + "dirs", "getrandom 0.3.4", "hmac", "photocraft-codecs", diff --git a/apps/photocraft/src/agent_link.rs b/apps/photocraft/src/agent_link.rs index 7cc2e563d3..f9f447edf9 100644 --- a/apps/photocraft/src/agent_link.rs +++ b/apps/photocraft/src/agent_link.rs @@ -111,6 +111,34 @@ fn apply(running: &mut Option, dir: Option<&Path>, integrations: &Integ out } +/// How often [`launcher_watch`] looks at the ArtCraft Launcher's files. +const LAUNCHER_POLL: std::time::Duration = std::time::Duration::from_secs(2); + +/// Whether the ArtCraft Launcher turned agents on for every Craft app +/// ([`agent_link::launcher_allows_agents`]), watched on its own thread so the UI can ask every +/// frame without touching the disk. A change wakes the UI, which then starts or stops the +/// connection. Without a thread (one couldn't be started) the answer stays what it was at launch. +pub fn launcher_watch(ctx: &egui::Context) -> Box bool> { + use std::sync::Arc; + use std::sync::atomic::{AtomicBool, Ordering}; + let on = Arc::new(AtomicBool::new(agent_link::launcher_allows_agents())); + let (seen, ctx) = (on.clone(), ctx.clone()); + let started = std::thread::Builder::new().name("launcher-agents".into()).spawn(move || { + loop { + std::thread::sleep(LAUNCHER_POLL); + let now = agent_link::launcher_allows_agents(); + if seen.swap(now, Ordering::Relaxed) != now { + log::info!("ArtCraft Launcher: agents {}", if now { "on" } else { "off" }); + ctx.request_repaint(); + } + } + }); + if let Err(e) = started { + log::warn!("couldn't watch the ArtCraft Launcher's agents switch: {e}"); + } + Box::new(move || on.load(Ordering::Relaxed)) +} + /// How MCP clients start this install's CLI (`photocraft-cli mcp --live`), or `None` when it /// isn't installed beside the app (a development build of the app alone). pub fn mcp_launch() -> Option { diff --git a/apps/photocraft/src/main.rs b/apps/photocraft/src/main.rs index f259ad7d25..7ff5a50a8e 100644 --- a/apps/photocraft/src/main.rs +++ b/apps/photocraft/src/main.rs @@ -732,6 +732,8 @@ fn main() -> eframe::Result { app.agent_link.mcp_flag = flags.enabled(&craft_flags::AI_MCP); if app.agent_link.mcp_flag { app.services.agent_clients = Some(agent_link::clients(mcp.clone())); + // ArtCraft Launcher › Settings › AI agents turns agents on for every Craft app. + app.services.launcher_agents = Some(agent_link::launcher_watch(&cc.egui_ctx)); } if let Some((listener, token, _)) = control { app.agent_link.launch_flags = true; diff --git a/book/src/security/automation-security.md b/book/src/security/automation-security.md index 000a091d75..bf7549f614 100644 --- a/book/src/security/automation-security.md +++ b/book/src/security/automation-security.md @@ -29,7 +29,7 @@ Automation is a privilege boundary because requests can cause filesystem access, Screenshots are decoded under separate dimension, pixel, and allocation ceilings before downscaling; the 5 MiB PNG limit applies to the returned image. - MCP normally uses stdio and can optionally bridge to loopback control TCP. -- Edit › Preferences › AI Integrations › *Let AI agents connect* (off by default) opens that loopback +- Edit › Preferences › AI Integrations › *Let AI agents connect* (off by default), or ArtCraft Launcher › Settings › AI agents for every Craft app, opens that loopback listener without launch flags. Its token is kept in a user-only file in the settings folder (`agent-control.token`) and stays the same across restarts and port changes: restarting does not revoke it. To revoke an exposed token, delete that file; the next start creates a new one. diff --git a/crates/automation/Cargo.toml b/crates/automation/Cargo.toml index c03900b66e..af29a68b35 100644 --- a/crates/automation/Cargo.toml +++ b/crates/automation/Cargo.toml @@ -39,6 +39,9 @@ hmac = "0.12" sha2 = "0.10" cap-std = "4" clap = { workspace = true } +# The suite's AI-MCP flag and the ArtCraft Launcher's folder: the launcher's agents switch counts as consent. +craft-flags = { workspace = true } +dirs = "7" # Optional native GPU rendering backend photocraft-gpu = { workspace = true, optional = true } diff --git a/crates/automation/src/agent_link.rs b/crates/automation/src/agent_link.rs index 9cfd4ae8d3..d7ebbf7fe2 100644 --- a/crates/automation/src/agent_link.rs +++ b/crates/automation/src/agent_link.rs @@ -186,6 +186,51 @@ pub fn read_integrations(dir: &Path) -> Integrations { .unwrap_or_default() } +// ---- ArtCraft Launcher -------------------------------------------------------------------------- + +/// The id the ArtCraft Launcher lists PhotoCraft under in its app list. +pub const LAUNCHER_APP_ID: &str = "photocraft"; +/// The launcher's app list for the MCP gateway (storytold/craft-ai-integrations, +/// `docs/CRAFT-AI-MCP.md`). The launcher writes it when Settings › AI agents › *Let AI agents use +/// Craft apps* is turned on and removes it when that is turned off. +pub const LAUNCHER_APPS_FILE: &str = "apps.json"; +/// Moves the launcher's folder, as it does for the launcher and the gateway. +pub const LAUNCHER_DIR_ENV: &str = "CRAFT_MCP_DIR"; +/// Version of the launcher's app list this reads. +const LAUNCHER_APPS_VERSION: u64 = 1; + +/// The launcher's folder: [`LAUNCHER_DIR_ENV`], otherwise `ArtCraft/mcp` in the per-user local +/// configuration folder, where the launcher writes it and the gateway reads it. +pub fn launcher_dir(env: impl Fn(&str) -> Option) -> Option { + match env(LAUNCHER_DIR_ENV) { + Some(d) if !d.is_empty() => Some(PathBuf::from(d)), + _ => dirs::config_local_dir().map(|b| b.join("ArtCraft").join("mcp")), + } +} + +/// Whether the launcher's app list in `dir` names PhotoCraft. A list that is missing, too big, +/// not JSON or of another version counts as no. +pub fn launcher_lists_photocraft(dir: &Path) -> bool { + let Some(text) = read_small(&dir.join(LAUNCHER_APPS_FILE)).ok().flatten() else { return false }; + let Ok(list) = serde_json::from_str::(&text) else { return false }; + list.get("version").and_then(Value::as_u64) == Some(LAUNCHER_APPS_VERSION) + && list.get("apps").and_then(Value::as_array).is_some_and(|apps| apps.iter().any(|a| a.get("id").and_then(Value::as_str) == Some(LAUNCHER_APP_ID))) +} + +/// The person turned agents on for every Craft app in the ArtCraft Launcher: the suite's `AI-MCP` +/// flag is on and the launcher's app list names PhotoCraft. That switch is their consent, as +/// *Let AI agents connect* is (storytold/craft-ai-integrations#195), so PhotoCraft accepts agents +/// without its own box ticked. Reads two small files; call it from a timer, not every frame. +pub fn launcher_allows_agents() -> bool { + craft_flags::load().enabled(&craft_flags::AI_MCP) && launcher_dir(|k| std::env::var_os(k)).is_some_and(|d| launcher_lists_photocraft(&d)) +} + +/// Agents may connect: *Let AI agents connect* is on, or the launcher turned agents on +/// ([`launcher_allows_agents`]). Allow Agent Control off still refuses both. +pub fn agents_allowed(integrations: &Integrations, launcher: bool) -> bool { + integrations.connect_agents || launcher +} + // ---- MCP clients -------------------------------------------------------------------------------- /// How an MCP client starts PhotoCraft's MCP server. @@ -646,6 +691,42 @@ mod tests { } } + #[test] + fn the_launcher_list_counts_only_when_it_names_photocraft() { + let dir = temp("launcher"); + assert!(!launcher_lists_photocraft(&dir), "no list: the launcher's switch is off"); + let write = |text: &str| std::fs::write(dir.join(LAUNCHER_APPS_FILE), text).unwrap(); + write(r#"{"version":1,"apps":[{"id":"filmcraft","command":"/x","args":["mcp"]},{"id":"photocraft","command":"/y"}]}"#); + assert!(launcher_lists_photocraft(&dir)); + write(r#"{"version":1,"apps":[{"id":"filmcraft","command":"/x"}]}"#); + assert!(!launcher_lists_photocraft(&dir), "PhotoCraft isn't in the list"); + write(r#"{"version":2,"apps":[{"id":"photocraft","command":"/y"}]}"#); + assert!(!launcher_lists_photocraft(&dir), "another version"); + write(r#"{"version":1,"apps":{"id":"photocraft"}}"#); + assert!(!launcher_lists_photocraft(&dir), "apps not a list"); + write("not json"); + assert!(!launcher_lists_photocraft(&dir)); + std::fs::remove_file(dir.join(LAUNCHER_APPS_FILE)).unwrap(); + std::fs::create_dir(dir.join(LAUNCHER_APPS_FILE)).unwrap(); + assert!(!launcher_lists_photocraft(&dir), "a folder in its place"); + } + + #[test] + fn the_launcher_folder_follows_its_override() { + let at = |v: &str| launcher_dir(|k| (k == LAUNCHER_DIR_ENV).then(|| v.into())); + assert_eq!(at("/portable/mcp"), Some(PathBuf::from("/portable/mcp"))); + assert_eq!(at(""), dirs::config_local_dir().map(|b| b.join("ArtCraft").join("mcp")), "empty means unset"); + } + + #[test] + fn either_switch_lets_agents_in() { + let mut i = Integrations::default(); + assert!(!agents_allowed(&i, false)); + assert!(agents_allowed(&i, true), "the launcher's switch alone"); + i.connect_agents = true; + assert!(agents_allowed(&i, false), "PhotoCraft's box alone"); + } + #[test] fn connection_round_trips_and_only_its_writer_removes_it() { let dir = temp("conn"); diff --git a/crates/automation/src/live.rs b/crates/automation/src/live.rs index c55f0a91c1..894d82234f 100644 --- a/crates/automation/src/live.rs +++ b/crates/automation/src/live.rs @@ -12,7 +12,7 @@ use std::path::{Path, PathBuf}; use std::sync::{Arc, Mutex, PoisonError}; use std::time::{Duration, Instant}; -use photocraft_engine::prefs::{Integrations, WhenAppClosed}; +use photocraft_engine::prefs::WhenAppClosed; use crate::agent_link::{self, Connection, PROBE_TIMEOUT}; use crate::bridge::BridgeClient; @@ -39,11 +39,22 @@ pub struct LiveConfig { /// Starts the app; `None` when this install can't (Flatpak sandbox, no app beside the CLI). pub launch: Option, pub launch_timeout: Duration, + /// Whether the ArtCraft Launcher turned agents on for every Craft app + /// ([`agent_link::launcher_allows_agents`]); tests replace it. + pub launcher_allows: fn() -> bool, } impl LiveConfig { pub fn new(config_dir: PathBuf) -> Self { - LiveConfig { config_dir, when_closed: None, read_root: None, write_root: None, launch: None, launch_timeout: LAUNCH_TIMEOUT } + LiveConfig { + config_dir, + when_closed: None, + read_root: None, + write_root: None, + launch: None, + launch_timeout: LAUNCH_TIMEOUT, + launcher_allows: agent_link::launcher_allows_agents, + } } } @@ -86,13 +97,15 @@ impl Live { return Ok(()); } let dir = self.cfg.config_dir.clone(); - let (found, integrations) = blocking(move || (find_app(&dir), agent_link::read_integrations(&dir))).await?; + let launcher_allows = self.cfg.launcher_allows; + let (found, integrations, launcher) = blocking(move || (find_app(&dir), agent_link::read_integrations(&dir), launcher_allows())).await?; + let allowed = agent_link::agents_allowed(&integrations, launcher); if let Some((c, token)) = found? { self.use_app(&c, token)?; return Ok(()); } match self.cfg.when_closed.unwrap_or(integrations.when_app_closed) { - WhenAppClosed::Error => Err(closed(&integrations)), + WhenAppClosed::Error => Err(closed(allowed)), WhenAppClosed::Headless => { let read = self.cfg.read_root.clone().or_else(|| agent_link::folder(&integrations.read_root)); let write = self.cfg.write_root.clone().or_else(|| agent_link::folder(&integrations.write_root)); @@ -101,13 +114,15 @@ impl Live { self.set(Target::Headless(Arc::new(Mutex::new(Headless::with_workspace(workspace)))), None); Ok(()) } - WhenAppClosed::Launch => self.launch_and_wait(&integrations).await, + WhenAppClosed::Launch => self.launch_and_wait(allowed).await, } } - async fn launch_and_wait(&self, integrations: &Integrations) -> Result<(), String> { - if !integrations.connect_agents { - return Err(closed(integrations)); + /// `allowed`: agents may connect ([`agent_link::agents_allowed`]); otherwise the app would never + /// listen, so it isn't started. + async fn launch_and_wait(&self, allowed: bool) -> Result<(), String> { + if !allowed { + return Err(closed(false)); } let Some(launch) = &self.cfg.launch else { return Err("PhotoCraft isn't running, and this install can't start it from here: open PhotoCraft, then try again.".into()); @@ -157,11 +172,11 @@ fn find_app(dir: &Path) -> Result, String> { Ok(Some((c, token))) } -fn closed(integrations: &Integrations) -> String { - if integrations.connect_agents { +fn closed(allowed: bool) -> String { + if allowed { "PhotoCraft isn't running: open it, then try again.".into() } else { - "PhotoCraft doesn't accept AI agents: open it, turn on Edit › Preferences › AI Integrations › Let AI agents connect, then try again.".into() + "PhotoCraft doesn't accept AI agents: open it, turn on Edit › Preferences › AI Integrations › Let AI agents connect (or ArtCraft Launcher › Settings › AI agents), then try again.".into() } } diff --git a/crates/automation/tests/mcp_live.rs b/crates/automation/tests/mcp_live.rs index 81909d783a..f696db8e5b 100644 --- a/crates/automation/tests/mcp_live.rs +++ b/crates/automation/tests/mcp_live.rs @@ -125,6 +125,8 @@ fn live(dir: &Path, when_closed: Option) -> LiveConfig { let mut c = LiveConfig::new(dir.to_path_buf()); c.when_closed = when_closed; c.launch_timeout = Duration::from_secs(10); + // The machine's own ArtCraft Launcher settings stay out of the tests. + c.launcher_allows = || false; c } @@ -202,6 +204,19 @@ async fn launch_starts_the_app_once_and_only_when_agents_may_connect() { assert_eq!(launches.load(Ordering::SeqCst), 0); client.cancel().await.unwrap(); + // The ArtCraft Launcher's switch alone is consent: the app is started without its own box. + let mut c = config(&dir); + c.launcher_allows = || true; + let client = connect(PhotocraftMcp::live(c)).await; + let r = call(&client, "ui_inspect", json!({})).await; + assert_eq!(r.is_error, Some(false), "{}", text(&r)); + assert_eq!(launches.load(Ordering::SeqCst), 1); + client.cancel().await.unwrap(); + for app in apps.lock().unwrap().drain(..) { + quit(app); + } + launches.store(0, Ordering::SeqCst); + prefs(&dir, json!({"connectAgents": true})); let client = connect(PhotocraftMcp::live(config(&dir))).await; // Two calls at once start one app. diff --git a/crates/ui-egui/src/prefs/prefs_ui/agents.rs b/crates/ui-egui/src/prefs/prefs_ui/agents.rs index 2dbaa69cfd..60ea2d5aaa 100644 --- a/crates/ui-egui/src/prefs/prefs_ui/agents.rs +++ b/crates/ui-egui/src/prefs/prefs_ui/agents.rs @@ -12,10 +12,15 @@ pub(super) const AGENT_LINK_RETRY_S: f64 = 5.0; /// Start, move or stop the agent connection when its settings change /// ([`crate::Services::agent_link`]); the first frame applies the saved settings. A connection /// that is on but failed to start is tried again every [`AGENT_LINK_RETRY_S`], so freeing its -/// port is enough, without touching a setting. +/// port is enough, without touching a setting. The ArtCraft Launcher's agents switch +/// ([`crate::Services::launcher_agents`]) counts as the box ticked: the person turned agents on for +/// every Craft app there. pub(super) fn sync_agent_link(app: &mut PhotocraftApp, ctx: &egui::Context) { + let launcher = app.services.launcher_agents.as_ref().is_some_and(|on| on()); let Some(link) = app.services.agent_link.as_mut() else { return }; - let current = &app.session.prefs().integrations; + let mut effective = app.session.prefs().integrations.clone(); + effective.connect_agents |= launcher; + let current = &effective; let now = crate::gpu_canvas::now_ms() / 1000.0; let retry_due = app.prefs_rt.agent_link_retry.is_some_and(|at| now >= at); if app.prefs_rt.agent_link.as_ref() == Some(current) && !retry_due { @@ -39,6 +44,7 @@ pub(super) fn sync_agent_link(app: &mut PhotocraftApp, ctx: &egui::Context) { // do with `--control` (`PhotocraftApp::new`); the gate stays once agents have connected. app.session.automation_gate = app.session.automation_gate.or(app.services.automation_authorize); app.agent_link = update.status; + app.agent_link.launcher = launcher; } /// The rows of the section. A button click is left in `f["__agentAction"]` for [`agent_action`]. @@ -46,10 +52,18 @@ pub(super) fn integration_rows(ui: &mut egui::Ui, obj: &mut Map, let t = Tokens::get(ui.ctx()); let status = f.get("__agentLink").cloned().unwrap_or(Value::Null); let launch_flags = status.get("launchFlags").and_then(Value::as_bool) == Some(true); + let launcher = status.get("launcher").and_then(Value::as_bool) == Some(true); let mut on = obj.get("connectAgents").and_then(Value::as_bool).unwrap_or(false); let label = humanize("connectAgents"); - ui.add_enabled_ui(!launch_flags, |ui| crate::widgets::checkbox(ui, &mut on, tl!(&label))); + if launcher && !launch_flags { + // On for the whole suite: shown ticked, and PhotoCraft's own choice is kept as it was. + ui.add_enabled_ui(false, |ui| crate::widgets::checkbox(ui, &mut true, tl!(&label))); + ui.label(RichText::new(tl!("Turned on in ArtCraft Launcher › Settings › AI agents, for every Craft app.")).color(t.text_dim)); + } else { + ui.add_enabled_ui(!launch_flags, |ui| crate::widgets::checkbox(ui, &mut on, tl!(&label))); + } obj.insert("connectAgents".into(), json!(on)); + let on = on || launcher; ui.label( RichText::new(tl!("AI apps such as Claude can then open, edit and save documents here. Only programs on this computer can connect.")).color(t.text_dim), ); diff --git a/crates/ui-egui/src/prefs/prefs_ui/agents_tests.rs b/crates/ui-egui/src/prefs/prefs_ui/agents_tests.rs index cef92ee389..eea34c3d84 100644 --- a/crates/ui-egui/src/prefs/prefs_ui/agents_tests.rs +++ b/crates/ui-egui/src/prefs/prefs_ui/agents_tests.rs @@ -50,6 +50,41 @@ fn ai_integrations_start_and_stop_the_agent_connection_through_the_service() { assert!(crate::control::inspect(&app, &ctx).get("agentLink").is_some()); } +/// The ArtCraft Launcher's agents switch counts as the box ticked, and turning it off there stops +/// the connection again; PhotoCraft's own saved choice is never changed by it. +#[test] +fn the_launcher_switch_turns_the_agent_connection_on_without_the_box() { + use std::sync::atomic::{AtomicBool, Ordering}; + let (mut app, _) = app_with_store(); + let ctx = egui::Context::default(); + let calls: Arc>> = Arc::default(); + let seen = calls.clone(); + app.services.agent_link = Some(Box::new(move |p: &prefs::Integrations, _: &egui::Context| { + seen.lock().unwrap().push(p.connect_agents); + crate::AgentLink { + stopped: !p.connect_agents, + status: crate::AgentLinkStatus { port: p.connect_agents.then_some(4321), ..Default::default() }, + ..Default::default() + } + })); + let launcher = Arc::new(AtomicBool::new(false)); + let on = launcher.clone(); + app.services.launcher_agents = Some(Box::new(move || on.load(Ordering::Relaxed))); + tick(&mut app, &ctx); + assert_eq!(*calls.lock().unwrap(), [false]); + launcher.store(true, Ordering::Relaxed); + tick(&mut app, &ctx); + assert_eq!(*calls.lock().unwrap(), [false, true], "the launcher's switch alone starts it"); + assert!(app.agent_link.launcher && app.agent_link.port == Some(4321)); + assert!(!app.session.prefs().integrations.connect_agents, "the box's own value is kept"); + tick(&mut app, &ctx); + assert_eq!(calls.lock().unwrap().len(), 2, "no change, no restart"); + launcher.store(false, Ordering::Relaxed); + tick(&mut app, &ctx); + assert_eq!(*calls.lock().unwrap(), [false, true, false], "off in the launcher stops it"); + assert!(!app.agent_link.launcher && app.agent_link.port.is_none()); +} + /// The buttons that set up an AI app only show once agents may connect, and a click reaches /// the service with the app's id and shows its answer. #[test] diff --git a/crates/ui-egui/src/services.rs b/crates/ui-egui/src/services.rs index 53aa83501c..295cf02806 100644 --- a/crates/ui-egui/src/services.rs +++ b/crates/ui-egui/src/services.rs @@ -371,6 +371,9 @@ pub struct AgentLinkStatus { /// The suite's `AI-MCP` feature flag (`craft-flags`): without it the page shows only the /// connection settings PhotoCraft had before (Allow Agent Control, Control Port). pub mcp_flag: bool, + /// The ArtCraft Launcher turned agents on for every Craft app (Settings › AI agents): that + /// counts as *Let AI agents connect*, whatever the box says. + pub launcher: bool, } /// What [`Services::agent_link`] did after the MCP settings changed. @@ -590,6 +593,10 @@ pub struct Services { pub agent_link: Option, /// Preferences › AI Integrations' buttons that add PhotoCraft to MCP clients (desktop). pub agent_clients: Option, + /// Whether the ArtCraft Launcher turned agents on for every Craft app, cheap enough to ask every + /// frame (the desktop app watches the launcher's files on its own thread). `None` without the + /// suite's `AI-MCP` flag, on the web, and in tests that don't set it. + pub launcher_agents: Option bool>>, /// Encode an RGBA8 image as PNG (used for screenshots and `ui.render`). pub encode_png: Option, /// Open a URL in the system browser (native). Falls back to `ctx.open_url` (web) when unset. diff --git a/docs/control-protocol.md b/docs/control-protocol.md index cbaf2c224c..5c2d2591b3 100644 --- a/docs/control-protocol.md +++ b/docs/control-protocol.md @@ -418,7 +418,7 @@ magenta alignment lines. `ui.pointer` drives the same code, so agents get identi - **Headless** (`photocraft-cli mcp`): an in-process `photocraft_engine::Session`. There is no window. CPU composition is the default; `--gpu` or `PHOTOCRAFT_GPU=1` enables optional GPU rendering with automatic CPU fallback. - **Bridge** (`photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file `): every tool is forwarded to a running `photocraft --control 7878 --control-token-file ` over this protocol, so agents see and drive the live app. Explicit `--gpu` / `--no-gpu` flags are rejected with a usage error because the desktop controls rendering; `PHOTOCRAFT_GPU` is ignored in bridge mode. `--bridge 7878` is short for `--bridge 127.0.0.1:7878`. With no `--bridge`, `PHOTOCRAFT_CONTROL_PORT` selects the bridge port (`127.0.0.1:`), and the CLI says so on standard error; with neither (or the variable empty), the MCP runs headless. A value that is not a port is a usage error naming the variable. `--automation-read-root` or `--automation-write-root` with the variable set is a usage error, since the bridge would drop the roots. -- **Live** (`photocraft-cli mcp --live`): the bridge, with the address and token read before every tool call from `agent-connection.json` in the app's settings folder. The app publishes that file while Edit › Preferences › AI Integrations › *Let AI agents connect* is on (not with `--control`), and removes it when the connection stops; a file left by a crash fails the connection probe and counts as no app. See [MCP conventions](mcp.md#connecting-the-desktop-app-no-terminal). +- **Live** (`photocraft-cli mcp --live`): the bridge, with the address and token read before every tool call from `agent-connection.json` in the app's settings folder. The app publishes that file while Edit › Preferences › AI Integrations › *Let AI agents connect* is on, or the ArtCraft Launcher turned agents on for every Craft app ([MCP conventions](mcp.md#connecting-the-desktop-app-no-terminal)), not with `--control`, and removes it when the connection stops; a file left by a crash fails the connection probe and counts as no app. See [MCP conventions](mcp.md#connecting-the-desktop-app-no-terminal). `ui.inspect` reports the connection as `agentLink`: `port` while agents can connect, `launchFlags` when `--control` manages it, `error`, and `mcpCommand` (how MCP clients start the CLI). diff --git a/docs/mcp.md b/docs/mcp.md index cc440ba629..59c977b119 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -7,6 +7,16 @@ ArtCraft Launcher › Settings › Experimental features, which writes `ArtCraft Craft app, or start PhotoCraft with `CRAFT_FLAGS=AI-MCP`. Without it the page shows only Allow Agent Control and Control Port, as before; a Control Port already set keeps its connection. +**With the ArtCraft Launcher** there is nothing to do in PhotoCraft: turning on Settings › AI +agents › **Let AI agents use Craft apps** there is the person's consent for every Craft app. The +launcher then keeps its app list `ArtCraft/mcp/apps.json` (in the per-user local configuration +folder; `CRAFT_MCP_DIR` moves it), and while that list names `photocraft` and `AI-MCP` is on, +PhotoCraft accepts agents as if **Let AI agents connect** were ticked: the page shows the box ticked +and says the launcher turned it on, and PhotoCraft's own choice is kept for when the launcher's +switch goes off. The app looks at the launcher's files every 2 s, so switching there applies +without a restart; `photocraft-cli mcp --live` looks before every call. Allow Agent Control off +still refuses agents. Storytold/craft-ai-integrations#195 has the whole design. + 1. In PhotoCraft, open **Edit › Preferences › AI Integrations** and turn on **Let AI agents connect (MCP)**. Optionally choose the folders agents can open from and save to, and what happens when an agent needs PhotoCraft while it is closed (open it, work without a window,