Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

Help > Connect an AI tool, Claude Desktop .mcpb bundles + registry server.json, MCP recipes (prompts) and headless viewport_image

islandmedf93b2b38f689
diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
index d06e4770..a1ad567c 100644
--- a/.github/workflows/packages.yml
+++ b/.github/workflows/packages.yml
@@ -148,10 +148,13 @@ jobs:
# AppImageUpdate and similar tools can update it from the newest GitHub release (the .zsync file). The
# AppDir's root gets PNG icons (AppImage managers cannot use the SVG), and appimagetool checks it (#17).
SF_APPIMAGE_TOOLS=.deps/appimage packaging/linux/build-appimage.sh AppDir "${TAG#v}" ${{ matrix.ld }} build
+ - name: Claude Desktop bundle (.mcpb; build_mcpb.py also runs its server)
+ run: python3 tools/release/build_mcpb.py --cli build/sculptforge-cli --version auto --platform linux --out "build/SculptForge-{version}-linux-${{ matrix.arch }}.mcpb"
- uses: actions/upload-artifact@v7
with:
name: linux-${{ matrix.arch }}
path: |
+ build/*.mcpb
build/*.deb
build/*.tar.gz
build/*.AppImage
@@ -343,10 +346,14 @@ jobs:
echo "hdiutil: Resource busy (try $attempt of 3)"; sleep 15
done
exit 1
+ - name: Claude Desktop bundle (.mcpb; build_mcpb.py also runs its server)
+ run: python3 tools/release/build_mcpb.py --cli build/sculptforge-cli --version auto --platform darwin --out "build/SculptForge-{version}-darwin-universal.mcpb"
- uses: actions/upload-artifact@v7
with:
name: macos
- path: build/*.dmg
+ path: |
+ build/*.dmg
+ build/*.mcpb
windows:
name: Windows x64 (installer, .zip)
@@ -402,9 +409,12 @@ jobs:
run: ctest --test-dir build -C Release --output-on-failure -LE ui -j 4
- name: Package
run: cd build && cpack -C Release -G "NSIS;ZIP"
+ - name: Claude Desktop bundle (.mcpb; build_mcpb.py also runs its server)
+ run: python tools/release/build_mcpb.py --cli build/Release/sculptforge-cli.exe --version auto --platform win32 --out "build/SculptForge-{version}-windows-x86_64.mcpb"
- uses: actions/upload-artifact@v7
with:
name: windows
path: |
build/*.exe
build/*.zip
+ build/*.mcpb
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e740f6b8..f58258f2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -9,7 +9,8 @@ name: Release
# promoted unchanged. Otherwise:
# build the Packages workflow runs here, from the tag (compiler cache restored from main, never saved).
# smoke every package installed or unpacked on a fresh runner: the app opens a model and sculpts
-# (tests/ui/release_smoke.sfui), sculptforge-cli opens, sculpts, saves and reopens (tests/release_smoke.py).
+# (tests/ui/release_smoke.sfui), sculptforge-cli opens, sculpts, saves and reopens and its MCP server answers
+# (tests/release_smoke.py), also through the AppImage (AppRun --cli) and each unpacked .mcpb bundle.
# publish only after every smoke test passed: checksums, notes from CHANGELOG.md, the GitHub release. A tag with
# a '-' (a beta) is a member perk, published by publish-members instead: a pre-release in the private
# repository islandmed/sculptforge-insiders (INSIDERS_REPO_TOKEN, held only by the environment
@@ -189,6 +190,10 @@ jobs:
python tests/release_smoke.py --cli "$bin\sculptforge-cli.exe" --out "smoke-$(Split-Path $bin -Leaf)"
if ($LASTEXITCODE -ne 0) { throw "the CLI smoke test failed in $bin" }
}
+ Copy-Item (Get-ChildItem pkg/SculptForge-*-windows-x86_64.mcpb | Select-Object -First 1).FullName mcpb.zip # (Expand-Archive wants .zip)
+ Expand-Archive mcpb.zip -DestinationPath mcpb
+ python tests/release_smoke.py --mcp-only --cli "$PWD\mcpb\server\sculptforge-cli.exe"
+ if ($LASTEXITCODE -ne 0) { throw "the .mcpb bundle's server failed" }
- name: macOS .dmg
if: matrix.kind == 'macos'
run: |
@@ -199,6 +204,7 @@ jobs:
app="$RUNNER_TEMP/SculptForge.app/Contents/MacOS"
codesign --verify --deep "$RUNNER_TEMP/SculptForge.app"
python3 tests/release_smoke.py --cli "$app/sculptforge-cli" --out smoke
+ unzip -q pkg/*.mcpb -d mcpb && python3 tests/release_smoke.py --mcp-only --cli mcpb/server/sculptforge-cli
"$app/sculptforge" --ui-test "$PWD/tests/ui/release_smoke.sfui" --ui-out "$PWD/shots"
- name: Linux .deb and AppImage
if: matrix.kind == 'linux'
@@ -215,6 +221,10 @@ jobs:
(cd "$RUNNER_TEMP" && "$GITHUB_WORKSPACE"/pkg/*.AppImage --appimage-extract >/dev/null)
ui "$RUNNER_TEMP/squashfs-root/AppRun" --ui-out "$PWD/shots/appimage"
python3 tests/release_smoke.py --cli "$RUNNER_TEMP/squashfs-root/usr/bin/sculptforge-cli" --out smoke-appimage
+ echo "== AppRun --cli --mcp (what Help > Connect an AI tool gives AppImage users)"
+ python3 tests/release_smoke.py --mcp-only --cli "$RUNNER_TEMP/squashfs-root/AppRun --cli"
+ echo "== .mcpb"
+ unzip -q pkg/*.mcpb -d mcpb && python3 tests/release_smoke.py --mcp-only --cli mcpb/server/sculptforge-cli
- name: .rpm
if: matrix.kind == 'rpm'
run: |
@@ -264,6 +274,12 @@ jobs:
cp "sculptforge-$V-1.aarch64.rpm" sculptforge.aarch64.rpm
cp "SculptForge-$V-x86_64.flatpak" SculptForge-linux-x86_64.flatpak
cp "SculptForge-$V-aarch64.flatpak" SculptForge-linux-arm64.flatpak
+ cp "SculptForge-$V-windows-x86_64.mcpb" SculptForge-windows-x86_64.mcpb
+ cp "SculptForge-$V-darwin-universal.mcpb" SculptForge-macos.mcpb
+ cp "SculptForge-$V-linux-x86_64.mcpb" SculptForge-linux-x86_64.mcpb
+ cp "SculptForge-$V-linux-arm64.mcpb" SculptForge-linux-arm64.mcpb
+ - name: MCP registry entry (server.json for the .mcpb bundles; publishing it is the maintainer's, docs/releasing.md)
+ run: python3 tools/release/mcp_server_json.py --version "${TAG#v}" --dist dist
- name: Blender add-on (extension and legacy zips, plus a version-less copy for the website's link)
run: |
V=${TAG#v}
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0608ce66..10b573d2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -312,7 +312,7 @@ set_source_files_properties(third_party/qrcodegen/qrcodegen.cpp ${CMAKE_CURRENT_
# --- Headless command-line tool (pipelines, build farms, AI agents) ---
# The MCP server (src/cli/McpServer.cpp) is a library of its own: the tool and the tests link it, nobody compiles it twice.
-add_library(sculptforge_mcp STATIC src/cli/McpServer.cpp)
+add_library(sculptforge_mcp STATIC src/cli/McpServer.cpp src/cli/McpTools.cpp)
target_compile_definitions(sculptforge_mcp PRIVATE SCULPTFORGE_VERSION="${PROJECT_VERSION}")
target_link_libraries(sculptforge_mcp PUBLIC sculptforge_core sculptforge_ai)
add_executable(sculptforge-cli src/cli/main.cpp)
@@ -324,7 +324,7 @@ target_link_libraries(sculptforge-cli PRIVATE sculptforge_core sculptforge_ai sc
if(SCULPTFORGE_BUILD_APP OR SCULPTFORGE_BUILD_TESTS)
add_library(sculptforge_appshared STATIC src/app/AssetLibrary.cpp src/app/BrushPreview.cpp src/app/UiLayout.cpp
src/app/ShellGeometry.cpp src/app/LookSchemes.cpp src/app/I18n.cpp src/app/I18nSpanish.cpp
- src/app/I18nTraditionalChinese.cpp src/render/Camera.cpp src/render/Clusters.cpp src/render/Ghost.cpp)
+ src/app/I18nTraditionalChinese.cpp src/app/ConnectAi.cpp src/render/Camera.cpp src/render/Clusters.cpp src/render/Ghost.cpp)
target_link_libraries(sculptforge_appshared PUBLIC sculptforge_core)
if(MSVC)
target_compile_options(sculptforge_appshared PRIVATE /W4 /utf-8 /permissive-)
@@ -427,6 +427,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/PanelSupport.cpp
src/app/QuickTour.cpp
src/app/PanelAi.cpp
+ src/app/PanelConnectAi.cpp
src/app/PanelSupportCard.cpp
src/app/PanelIntegrations.cpp
src/app/WhatsNewPopup.cpp
@@ -755,6 +756,22 @@ if(SCULPTFORGE_BUILD_TESTS)
add_test(NAME media_takedown_self_test COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/media_takedown.py --self-test)
# The public gallery repository matches tools/brush-gallery/repo (the live compare is in release.sh: network).
add_test(NAME gallery_published_self_test COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/brush-gallery/check_published.py --self-test)
+ # The Claude Desktop bundle and its MCP registry entry (tools/release/build_mcpb.py, mcp_server_json.py): packed
+ # from the built CLI and its server run from the unpacked bundle, as packages.yml does on every OS.
+ add_test(NAME mcpb_self_test COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/build_mcpb.py --self-test)
+ add_test(NAME mcp_server_json_self_test COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/mcp_server_json.py --self-test)
+ if(NOT CMAKE_CROSSCOMPILING)
+ if(WIN32)
+ set(SF_MCPB_PLATFORM win32)
+ elseif(APPLE)
+ set(SF_MCPB_PLATFORM darwin)
+ else()
+ set(SF_MCPB_PLATFORM linux)
+ endif()
+ add_test(NAME mcpb_bundle COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/build_mcpb.py
+ --cli $<TARGET_FILE:sculptforge-cli> --version auto --platform ${SF_MCPB_PLATFORM}
+ --out ${CMAKE_CURRENT_BINARY_DIR}/mcpb-test/SculptForge-test.mcpb)
+ endif()
add_test(NAME release_notes COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/assemble_notes.py --self-test)
add_test(NAME release_notes_fragments COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/assemble_notes.py --check)
# The members' publishing path stays locked down: release.yml's actions pinned to commit SHAs, INSIDERS_REPO_TOKEN only
diff --git a/README.md b/README.md
index 56df8406..365a1c66 100644
--- a/README.md
+++ b/README.md
@@ -228,14 +228,22 @@ sculptforge model.glb --render review/model.png --turntable 8 --size 1024x1024
Run `sculptforge-cli --list` for every command.
-### Let an AI agent sculpt (MCP)
+### Use with AI tools
+
+SculptForge's tools work from Claude, ChatGPT (Codex CLI), Gemini (Antigravity CLI), Grok (Grok Build), Cursor,
+VS Code, JetBrains, Zed and other MCP clients: the AI tool starts `sculptforge-cli --mcp` on your computer (stdio;
+nothing listens on the network). In the app, **Help > Connect an AI tool...** shows the exact command or settings for
+your install, with Copy buttons. Claude Desktop also installs it from a bundle (`SculptForge-*.mcpb` on each
+[release](https://github.com/islandmed/SculptForge/releases/latest)).
```sh
-claude mcp add sculptforge -- /path/to/sculptforge-cli --mcp # Claude Code
+claude mcp add --scope user sculptforge -- /path/to/sculptforge-cli --mcp # Claude Code
+codex mcp add sculptforge -- /path/to/sculptforge-cli --mcp # Codex CLI (sign in with ChatGPT)
```
-For Claude Desktop or other MCP clients, add a stdio server whose command is `sculptforge-cli` with the
-argument `--mcp`. The agent gets every command as a tool and works on one live scene per session.
+Every command is a tool, plus `viewport_image` (a picture of the scene) and ready-made recipes (MCP prompts). Every
+client, your own agent and plain function calling (`sculptforge-cli --schema`):
+[the guide](docs/guide/scripting.md#ai-agents-mcp).
## Controls
diff --git a/assets/fonts/NotoSansTC-UI.otf b/assets/fonts/NotoSansTC-UI.otf
index 76014714..8b703fc3 100644
Binary files a/assets/fonts/NotoSansTC-UI.otf and b/assets/fonts/NotoSansTC-UI.otf differ
diff --git a/changes/feat-mcp-easy.md b/changes/feat-mcp-easy.md
new file mode 100644
index 00000000..fa1cfc33
--- /dev/null
+++ b/changes/feat-mcp-easy.md
@@ -0,0 +1,31 @@
+---
+whats_new: **Help > Connect an AI tool**: use SculptForge from Claude, ChatGPT (Codex CLI), Gemini (Antigravity CLI),
+ Grok (Grok Build), Cursor, VS Code and more. Pick your subscription; the window shows the exact command or settings
+ for your install, with Copy buttons. Claude Desktop installs it from a bundle on each release.
+highlight: Connect your AI tool in one window
+added: **Help > Connect an AI tool** (while AI features are on): an "I have a subscription" picker (Claude, ChatGPT,
+ Gemini, Grok, other tools) and, for this install, the exact command or configuration for Claude Desktop, Claude Code,
+ Codex CLI, Antigravity CLI, Gemini CLI, Grok Build, Cursor, VS Code, Visual Studio, JetBrains AI Assistant, Zed,
+ Windsurf (Devin Local), GitHub Copilot CLI, Cline, Continue, Kiro, Amazon Q Developer CLI, Warp, Goose, opencode,
+ Rovo Dev CLI, LM Studio, Jan and the OpenAI Agents SDK, each checked against the vendor's documentation, with Copy
+ buttons. Remote-only apps (the ChatGPT and Grok apps, Rovo on the web) are named as such: SculptForge runs no network
+ server.
+added: A Claude Desktop bundle (`SculptForge-*.mcpb`) for Windows, macOS and Linux on every release, and `server.json`
+ for the official MCP registry.
+added: The MCP server (`sculptforge-cli --mcp`) gains `viewport_image` (a clay-shaded picture of the scene from any
+ angle, to check each step) and recipes as MCP prompts: a creature head, a stylised bust from a reference image, a
+ game-ready asset (retopology, UVs, bake, LODs), rock variations and a step-by-step lesson. Its server info carries a
+ title and clearer instructions.
+added: AppImage: `SculptForge.AppImage --cli ...` runs the command-line tool inside it (so MCP clients can start it).
+added: Guide (Scripting > AI agents): every client's setup, your own agent, and plain function calling with
+ `sculptforge-cli --schema` for the OpenAI, Gemini and xAI APIs.
+testers:
+ - Any OS: Help > Connect an AI tool. Each subscription shows its tools; the path under "This install" is your
+ sculptforge-cli. Copy the Claude Code (or Codex) line, run it, ask the agent for "a sphere remeshed at 128,
+ exported to ~/ball.glb", open ball.glb in SculptForge.
+ - Windows: copy the Cursor or Claude Desktop JSON; the path has doubled backslashes and the client starts SculptForge.
+ - Preferences > AI off: Help no longer lists Connect an AI tool.
+ - Claude Desktop: install SculptForge-*.mcpb from the release (Settings > Extensions > Advanced settings); its tools
+ and the recipes appear.
+---
+Reviewers: stdio only, no new listener. The window only reads SDL_GetBasePath / FLATPAK_ID / APPIMAGE to build paths.
diff --git a/docs/guide/scripting.md b/docs/guide/scripting.md
index 8d94d33d..efa12dc4 100644
--- a/docs/guide/scripting.md
+++ b/docs/guide/scripting.md
@@ -3,7 +3,7 @@
Every operation in SculptForge is a named command with parameters. The same commands run from the console
inside the app, from script files, from the `sculptforge-cli` tool on a build farm, from Python, and from AI
agents through the Model Context Protocol (MCP). This chapter explains the script language, the console, both
-command-line programs, the Python module and MCP setup.
+command-line programs, the Python module and connecting AI tools.
## The script language
@@ -244,18 +244,57 @@ threads.
## AI agents (MCP)
-`sculptforge-cli --mcp` runs SculptForge as an MCP server. An AI agent (Claude Code, Claude Desktop or any MCP
-client) gets every command as a tool and works on one scene for the session: it can open files, generate
-models, sculpt strokes, remesh, paint and export.
+`sculptforge-cli --mcp` runs SculptForge as an MCP server. An AI tool (Claude, Codex, Gemini, Grok, Cursor, VS Code
+and others) gets every command as a tool and works on one scene for the session: it can open files, generate
+models, sculpt strokes, remesh, paint and export. The AI tool starts `sculptforge-cli` on your computer and talks to
+it over standard input and output. Nothing listens on the network, and nothing is installed into the AI tool.
-Claude Code:
+The easy way: **Help > Connect an AI tool...** shows, for your install, the exact command or settings for each tool
+below, with Copy buttons. It is there while AI features are on (**Preferences > AI**).
-```sh
-claude mcp add sculptforge -- /path/to/sculptforge-cli --mcp
-```
+### I have a subscription
-Claude Desktop or another client: add a stdio server whose command is the full path to `sculptforge-cli` and
-whose argument is `--mcp`. For Claude Desktop that is an entry in its configuration file like this:
+| Subscription | Use | Set up |
+|---|---|---|
+| Claude (Pro, Max, Ultra) | Claude Desktop or Claude Code | Claude Desktop: install the bundle (below). Claude Code: `claude mcp add --scope user sculptforge -- /path/to/sculptforge-cli --mcp` |
+| ChatGPT (Plus, Pro, Business, Edu, Enterprise) | Codex CLI | `codex mcp add sculptforge -- /path/to/sculptforge-cli --mcp`, then **Sign in with ChatGPT** |
+| Google (free, Google AI Pro, Google AI Ultra) | Antigravity CLI | add SculptForge to `~/.gemini/config/mcp_config.json` (below), then sign in with Google |
+| Grok / xAI | Grok Build | `grok mcp add sculptforge -- /path/to/sculptforge-cli --mcp` |
+
+- **Claude**: Claude Code uses your plan when you sign in with your Claude account; if `ANTHROPIC_API_KEY` is set
+ it uses that key and API billing instead. Claude on the web and on phones can't start programs on your computer.
+- **ChatGPT**: the ChatGPT app only connects to remote (HTTPS) MCP servers. SculptForge doesn't run one, on purpose:
+ nothing of yours listens on the network. Use Codex CLI, or the OpenAI Agents SDK or API below.
+- **Gemini**: since June 2026 personal Google accounts use Antigravity CLI; Gemini CLI is for Gemini Code Assist
+ Standard and Enterprise and for API keys.
+- **Grok**: the Grok app (web, phone, X) can't reach programs on your computer, only public HTTPS servers. Grok Build
+ signs in with your xAI account in the browser (xAI's documentation doesn't say which plans that includes) or takes
+ an xAI API key. The xAI API's own MCP tool is remote-only too; your own code can use the function calling example
+ below (API usage is billed by xAI).
+
+### Where sculptforge-cli is
+
+| Install | Command |
+|---|---|
+| Windows | `C:\Program Files\SculptForge\bin\sculptforge-cli.exe --mcp` |
+| macOS | `/Applications/SculptForge.app/Contents/MacOS/sculptforge-cli --mcp` |
+| Linux .deb, .rpm, AUR | `/usr/bin/sculptforge-cli --mcp` |
+| AppImage | `/path/to/SculptForge.AppImage --cli --mcp` (`--cli` runs the CLI inside the AppImage) |
+| Flatpak | `flatpak run --command=sculptforge-cli org.sculptforge.SculptForge --mcp` |
+
+In JSON and TOML files a Windows path is written with doubled backslashes
+(`"C:\\Program Files\\SculptForge\\bin\\sculptforge-cli.exe"`). The window does that for you.
+
+### Claude Desktop bundle
+
+Download the bundle for your system, then install it in Claude Desktop under **Settings > Extensions > Advanced
+settings** ([Anthropic's guide](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)):
+[Windows](https://github.com/islandmed/SculptForge/releases/latest/download/SculptForge-windows-x86_64.mcpb),
+[macOS](https://github.com/islandmed/SculptForge/releases/latest/download/SculptForge-macos.mcpb),
+[Linux x86_64](https://github.com/islandmed/SculptForge/releases/latest/download/SculptForge-linux-x86_64.mcpb),
+[Linux ARM64](https://github.com/islandmed/SculptForge/releases/latest/download/SculptForge-linux-arm64.mcpb).
+It carries its own copy of `sculptforge-cli`. Or add SculptForge to `claude_desktop_config.json`
+(Windows `%APPDATA%\Claude\`, macOS `~/Library/Application Support/Claude/`, Linux `~/.config/Claude/`) and restart:
```text
{
@@ -265,11 +304,125 @@ whose argument is `--mcp`. For Claude Desktop that is an entry in its configurat
}
```
-Then ask for something like "make a sphere, remesh it at 128 and export it to ~/Desktop/ball.glb". File paths
-are on your machine. The agent works headless; to see the result, open the exported file in SculptForge.
+### Every other tool
+
+Most tools take the same `mcpServers` entry as Claude Desktop above. Each row links the vendor's page the format is
+from.
+
+| Tool | Set up |
+|---|---|
+| [Cursor](https://cursor.com/docs/context/mcp) | the `mcpServers` entry in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project) |
+| [VS Code (Copilot agent mode)](https://code.visualstudio.com/docs/agent-customization/mcp-servers) | `code --add-mcp '{"name":"sculptforge","type":"stdio","command":"/path/to/sculptforge-cli","args":["--mcp"]}'`, or **MCP: Open User Configuration** and add `"servers": {"sculptforge": {"type": "stdio", "command": "...", "args": ["--mcp"]}}` |
+| [Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers) | the same `servers` entry in `%USERPROFILE%\.mcp.json`; Copilot Chat in Agent mode |
+| [JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/mcp.html) | **Settings > Tools > AI Assistant > Model Context Protocol (MCP)**: Add, STDIO, paste the `mcpServers` entry |
+| [Zed](https://zed.dev/docs/ai/mcp) | in its settings file (`zed: open settings file`): `"context_servers": {"sculptforge": {"command": "...", "args": ["--mcp"]}}` |
+| [Windsurf (Devin Local)](https://docs.devin.ai/cli/extensibility/mcp/configuration) | `devin mcp add -s user sculptforge -- /path/to/sculptforge-cli --mcp`, or the `mcpServers` entry in `~/.config/devin/mcp_config.json` (Windows `%APPDATA%\devin\`) |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) | `gemini mcp add --scope user sculptforge /path/to/sculptforge-cli --mcp` |
+| [Antigravity CLI](https://antigravity.google/docs/mcp/) | the `mcpServers` entry in `~/.gemini/config/mcp_config.json` |
+| [Codex CLI](https://learn.chatgpt.com/docs/extend/mcp) | `codex mcp add ...` as above, or in `~/.codex/config.toml`: `[mcp_servers.sculptforge]`, `command = "/path/to/sculptforge-cli"`, `args = ["--mcp"]` |
+| [Grok Build](https://docs.x.ai/build/features/mcp-servers) | `grok mcp add ...` as above, or the same TOML table in `~/.grok/config.toml` |
+| [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) | `copilot mcp add sculptforge -- /path/to/sculptforge-cli --mcp` |
+| [Cline](https://docs.cline.bot/mcp/configuring-mcp-servers) | `cline mcp add sculptforge --yes -- /path/to/sculptforge-cli --mcp`, or the `mcpServers` entry under **MCP Servers > Configure** |
+| [Continue](https://docs.continue.dev/customize/deep-dives/mcp) | a file in `.continue/mcpServers/` with `mcpServers:` `- name: SculptForge`, `type: stdio`, `command: ...`, `args: ["--mcp"]` (agent mode) |
+| [Kiro](https://kiro.dev/docs/mcp/configuration/) | the `mcpServers` entry in `~/.kiro/settings/mcp.json` |
+| [Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-config-CLI.html) | `q mcp add --name sculptforge --command /path/to/sculptforge-cli --args '["--mcp"]'` |
+| [Warp](https://docs.warp.dev/knowledge-and-collaboration/mcp) | **Settings > Agents > MCP servers > Add**, paste the `mcpServers` entry |
+| [Goose](https://goose-docs.ai/docs/getting-started/using-extensions) | `goose configure` > Add Extension > Command-Line Extension, or in `~/.config/goose/config.yaml` under `extensions:` an entry with `type: stdio`, `cmd: ...`, `args: ["--mcp"]` |
+| [opencode](https://opencode.ai/docs/mcp-servers/) | in `opencode.json`: `"mcp": {"sculptforge": {"type": "local", "command": ["/path/to/sculptforge-cli", "--mcp"]}}` |
+| [Rovo Dev CLI](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/) | the `mcpServers` entry plus `"transport": "stdio"` in `~/.rovodev/mcp.json` (`acli rovodev mcp` opens it) |
+| [LM Studio](https://lmstudio.ai/docs/app/mcp) | **Program** tab > **Install > Edit mcp.json**, paste the `mcpServers` entry |
+| [Jan](https://docs.jan.ai/desktop/mcp) | **Settings > MCP Servers > +**: command `/path/to/sculptforge-cli`, arguments `--mcp` |
+
+Remote only, so not for SculptForge: the ChatGPT app, the Grok app, and Rovo in Atlassian's web apps (public HTTPS
+servers added by an admin; use Rovo Dev CLI). The OpenAI and xAI APIs' built-in MCP tools also reach only remote
+servers: use the Agents SDK or plain function calling below.
+
+### Using it
+
+Ask for something like "make a sphere, remesh it at 128 and export it to ~/Desktop/ball.glb". File paths are on your
+machine. The agent works headless on its own scene; to see the result, open the exported file in SculptForge.
+
+- **viewport_image** gives the agent a picture of the scene (a clay-shaded view of the visible Parts, any angle) to
+ check each step by eye. Every tool call is one undo step, so the agent can take back what went wrong.
+- **Recipes**: the server offers ready-made prompts that walk an agent through a whole job. In Claude Desktop and
+ other tools that show MCP prompts, pick one from the prompt menu: a creature head from a description, a stylised
+ bust from a reference image, a game-ready asset (retopology, UVs, baked maps and LODs for Unreal or Godot),
+ rock variations, and a step-by-step lesson.
+
+### Your own agent
+
+The [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/mcp/) starts the server itself:
+
+```python
+import asyncio
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio
+
+async def main():
+ async with MCPServerStdio(name="SculptForge", client_session_timeout_seconds=60,
+ params={"command": "/path/to/sculptforge-cli", "args": ["--mcp"]}) as sf:
+ agent = Agent(name="Sculptor", instructions="Use SculptForge's tools.", mcp_servers=[sf])
+ print((await Runner.run(agent, "Make a sphere, remesh it at 128 and export ball.glb")).final_output)
+
+asyncio.run(main())
+```
+
+For plain function calling with any model API, `sculptforge-cli --schema` prints every tool as JSON
+(`name`, `description`, `input_schema`: the Claude API takes it as it is). APIs limit how many tools one request
+may carry, so pick the ones the job needs. This helper turns them into function definitions and runs each call in
+one SculptForge session (through `--mcp`, so the scene is kept between calls):
+
+```python
+# sf_tools.py
+import json, subprocess
+CLI = "/path/to/sculptforge-cli"
+WANTED = {"new_sphere", "remesh", "subdivide", "stroke", "decimate", "mesh_info", "export_glb", "undo"}
+TOOLS = [{"type": "function", "name": t["name"], "description": t["description"], "parameters": t["input_schema"]}
+ for t in json.loads(subprocess.run([CLI, "--schema"], capture_output=True, text=True).stdout)
+ if t["name"] in WANTED]
+_sf = subprocess.Popen([CLI, "--mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+def call(name, arguments):
+ _sf.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+ "params": {"name": name, "arguments": arguments}}) + "\n")
+ _sf.stdin.flush()
+ return json.loads(_sf.stdout.readline())["result"]["content"][0]["text"]
+```
+
+[OpenAI API](https://developers.openai.com/api/docs/guides/function-calling) (Responses API). For the
+[xAI API](https://docs.x.ai/docs/guides/function-calling) use the same code with
+`OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")` and a Grok model:
+
+```python
+import json
+from openai import OpenAI
+from sf_tools import TOOLS, call
+client = OpenAI()
+items = [{"role": "user", "content": "Make a sphere, remesh it at 128 and export it to ball.glb"}]
+while True:
+ r = client.responses.create(model="gpt-6-astra", tools=TOOLS, input=items)
+ items += r.output
+ calls = [i for i in r.output if i.type == "function_call"]
+ if not calls: break
+ items += [{"type": "function_call_output", "call_id": c.call_id,
+ "output": call(c.name, json.loads(c.arguments))} for c in calls]
+print(r.output_text)
+```
+
+[Gemini API](https://aistudio.google.com/docs/function-calling) (the `google-genai` package):
+
+```python
+from google import genai
+from sf_tools import TOOLS, call
+client = genai.Client()
+interaction = client.interactions.create(model="gemini-3.8-flash", tools=TOOLS,
+ input="Make a sphere, remesh it at 128 and export it to ball.glb")
+for step in interaction.steps:
+ if step.type == "function_call":
+ print(step.name, call(step.name, step.arguments))
+# Send each result back as Google's guide shows to let the model continue.
+```
-`sculptforge-cli --schema` prints the same tool definitions as JSON, for wiring SculptForge into your own
-agent.
+Never point a tool at a web app's session or cookies: use each vendor's own app, CLI or API as above.
## See also
diff --git a/docs/releasing.md b/docs/releasing.md
index abfa0011..12fc66fa 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -162,6 +162,14 @@ What keeps the insiders token from leaking; `tools/release/check_workflows.py` (
- islandmed/sculptforge-insiders: private, members invited with `permission=pull` only, ruleset on `main`: no force
push, no deletion.
+## MCP registry (by hand, the maintainer's account)
+
+Each release carries the Claude Desktop bundles (`SculptForge-<version>-<os>.mcpb`, tools/release/build_mcpb.py,
+built and run by packages.yml) and `server.json` describing them (tools/release/mcp_server_json.py). To list the
+version in the official registry (registry.modelcontextprotocol.io): download that `server.json`, then
+`mcp-publisher login github` (as islandmed) and `mcp-publisher publish server.json`. Nothing is submitted
+automatically.
+
## Membership upkeep (by hand)
- **Founding Members:** `website/founding.json` (`limit` 100, `taken`, `names`). On each new member among the first
diff --git a/src/app/App.cpp b/src/app/App.cpp
index f6b8af96..db375f1c 100644
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@ -2934,6 +2934,7 @@ void App::drawUi() {
guide_.draw(*this); // Help > User Guide
drawPacksUi(); // pack review, New Pack, macro confirmation and editor (PanelPacks.cpp)
drawMemoryConfirm(); // "Not enough free memory" before a big mesh (MemoryConfirm.cpp)
+ drawConnectAi(); // Help > Connect an AI tool (PanelConnectAi.cpp)
drawHelpConsoleUi(); // console, command palette, Controls (F1), Ctrl-hover help: last, on top
drawWhatsNew(); // What's New after an update or from the Help menu (WhatsNewPopup.cpp)
drawSupportCard(); // the support card at launch, over everything (PanelSupportCard.cpp)
diff --git a/src/app/App.h b/src/app/App.h
index 68a2010b..10c64f09 100644
--- a/src/app/App.h
+++ b/src/app/App.h
@@ -428,6 +428,9 @@ private:
bool lastCommandOk_ = true; // result of the last runCommand (UI tests check it)
bool showHelp_ = false;
bool showAbout_ = false;
+ bool showConnectAi_ = false; // Help > Connect an AI tool (PanelConnectAi.cpp; only while AI is on)
+ int connectPlan_ = 0; // its "I have a ... subscription" choice (connect::Plan)
+ void drawConnectAi();
// Supporting SculptForge (Support.h): the app only ever opens the membership page or its Stripe checkout links in the
// browser; nothing else changes.
void openSupportPage();
diff --git a/src/app/ConnectAi.cpp b/src/app/ConnectAi.cpp
new file mode 100644
index 00000000..2c9324bb
--- /dev/null
+++ b/src/app/ConnectAi.cpp
@@ -0,0 +1,307 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "app/ConnectAi.h"
+
+#include <cctype>
+#include <cstdio>
+#include <string_view>
+
+namespace sf::connect {
+
+namespace {
+
+using K = Snippet::Kind;
+
+// What each snippet is built from (one per client format).
+enum class Format {
+ ClaudeCode, // claude mcp add --scope user sculptforge -- CMD ARGS
+ McpServers, // {"mcpServers": {"sculptforge": {"command", "args"}}}: Claude Desktop, Cursor and most others
+ VsCode, // {"servers": {"sculptforge": {"type": "stdio", "command", "args"}}}
+ Zed, // {"context_servers": {"sculptforge": {"command", "args"}}}
+ RovoDev, // McpServers plus "transport": "stdio"
+ CodexToml, // [mcp_servers.sculptforge] command / args (Codex, Grok Build)
+ Goose, // config.yaml extensions entry
+ Continue, // .continue/mcpServers/*.yaml block
+ Opencode, // opencode.json "mcp" entry, command as one array
+ Fields, // a form: name, command, arguments (Jan)
+ AgentsSdk, // OpenAI Agents SDK, MCPServerStdio
+};
+
+struct Row {
+ const char* id;
+ const char* name;
+ Plan plan;
+ const char* how; // translated in the window (tools/i18n/coverage.py reads kAiClients' 4th column)
+ const char* docs;
+};
+
+// Display order inside each plan. A client's snippets are built in clients() from its id.
+constexpr Row kAiClients[] = {
+ {"claude_desktop", "Claude Desktop", Plan::Claude,
+ "Download the bundle for your system and install it in Claude Desktop under Settings > Extensions > Advanced settings. Or add SculptForge to its configuration file and restart it.",
+ "https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop"},
+ {"claude_code", "Claude Code", Plan::Claude, "Run once in a terminal; it signs in with your Claude plan.",
+ "https://code.claude.com/docs/en/mcp"},
+ {"codex", "Codex CLI", Plan::ChatGPT, "Run once in a terminal, then choose Sign in with ChatGPT when Codex starts.",
+ "https://learn.chatgpt.com/docs/extend/mcp"},
+ {"antigravity", "Antigravity CLI", Plan::Gemini,
+ "Google's CLI for personal Google accounts (free, Google AI Pro and Ultra). Add this to its MCP file, then sign in with Google.",
+ "https://antigravity.google/docs/mcp/"},
+ {"gemini_cli", "Gemini CLI", Plan::Gemini,
+ "For Gemini Code Assist Standard or Enterprise, or a Gemini API key. Run once in a terminal.",
+ "https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md"},
+ {"grok_build", "Grok Build", Plan::Grok,
+ "xAI's coding agent (the grok command). Run once in a terminal; it signs in with your xAI account in the browser.",
+ "https://docs.x.ai/build/features/mcp-servers"},
+ {"cursor", "Cursor", Plan::Other, "Add to Cursor's global MCP file (or .cursor/mcp.json in a project).",
+ "https://cursor.com/docs/context/mcp"},
+ {"vscode", "VS Code (Copilot agent mode)", Plan::Other,
+ "Run once in a terminal, or open the command MCP: Open User Configuration and add the entry.",
+ "https://code.visualstudio.com/docs/agent-customization/mcp-servers"},
+ {"visual_studio", "Visual Studio", Plan::Other, "Add to the global MCP file, then use it from Copilot Chat in Agent mode.",
+ "https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers"},
+ {"jetbrains", "JetBrains AI Assistant", Plan::Other,
+ "Settings > Tools > AI Assistant > Model Context Protocol (MCP): Add, choose STDIO and paste this.",
+ "https://www.jetbrains.com/help/ai-assistant/mcp.html"},
+ {"zed", "Zed", Plan::Other, "Add to Zed's settings file (command palette: zed: open settings file).",
+ "https://zed.dev/docs/ai/mcp"},
+ {"windsurf", "Windsurf (Devin Local)", Plan::Other, "Run once in a terminal, or add to the user MCP file.",
+ "https://docs.devin.ai/cli/extensibility/mcp/configuration"},
+ {"copilot_cli", "GitHub Copilot CLI", Plan::Other, "Run once in a terminal.",
+ "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers"},
+ {"cline", "Cline", Plan::Other, "Run once in a terminal (Cline CLI), or paste into Cline's MCP settings (MCP Servers > Configure).",
+ "https://docs.cline.bot/mcp/configuring-mcp-servers"},
+ {"continue", "Continue", Plan::Other, "Save as a file in your workspace's .continue/mcpServers folder; tools work in agent mode.",
+ "https://docs.continue.dev/customize/deep-dives/mcp"},
+ {"kiro", "Kiro", Plan::Other, "Add to Kiro's user MCP file.", "https://kiro.dev/docs/mcp/configuration/"},
+ {"amazon_q", "Amazon Q Developer CLI", Plan::Other, "Run once in a terminal.",
+ "https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-config-CLI.html"},
+ {"warp", "Warp", Plan::Other, "Settings > Agents > MCP servers > Add, then paste this.",
+ "https://docs.warp.dev/knowledge-and-collaboration/mcp"},
+ {"goose", "Goose", Plan::Other, "Add under extensions in Goose's configuration file (or goose configure > Add Extension > Command-Line Extension).",
+ "https://goose-docs.ai/docs/getting-started/using-extensions"},
+ {"opencode", "opencode", Plan::Other, "Add to opencode.json.", "https://opencode.ai/docs/mcp-servers/"},
+ {"rovo_dev", "Rovo Dev CLI", Plan::Other, "Add to Rovo Dev's MCP file (acli rovodev mcp opens it).",
+ "https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/"},
+ {"lm_studio", "LM Studio", Plan::Other, "Program tab > Install > Edit mcp.json, then paste this.",
+ "https://lmstudio.ai/docs/app/mcp"},
+ {"jan", "Jan", Plan::Other, "Settings > MCP Servers > +, then fill in these fields.", "https://docs.jan.ai/desktop/mcp"},
+ {"agents_sdk", "OpenAI Agents SDK (Python)", Plan::Other, "Your own agent in Python (uses the OpenAI API with an API key).",
+ "https://openai.github.io/openai-agents-python/mcp/"},
+};
+
+// Under the subscription picker: the vendors' apps that only take remote (HTTPS) servers, sign-in caveats.
+// Translated in the window (tools/i18n/coverage.py reads kPlanNotes' 2nd column).
+struct Note {
+ Plan plan;
+ const char* text;
+};
+constexpr Note kPlanNotes[] = {
+ {Plan::Claude, "Claude Code uses your Pro, Max or Ultra plan when you sign in with your Claude account. If ANTHROPIC_API_KEY is set, it uses that key and API billing instead."},
+ {Plan::Claude, "Claude on the web and on phones can't start programs on your computer: use Claude Desktop or Claude Code."},
+ {Plan::ChatGPT, "The ChatGPT app only connects to remote (HTTPS) servers, and SculptForge doesn't run one: nothing of yours listens on the network. Codex CLI runs on your computer and signs in with your ChatGPT plan."},
+ {Plan::Gemini, "Since June 2026 personal Google accounts (free, Google AI Pro, Google AI Ultra) use Antigravity CLI; Gemini CLI is for Gemini Code Assist and API keys."},
+ {Plan::Grok, "The Grok app (web, phone, X) can't reach programs on your computer, only public HTTPS servers: use Grok Build. xAI's documentation doesn't say which plans Grok Build's sign-in includes; it also takes an xAI API key."},
+ {Plan::Grok, "Your own code with the xAI API: sculptforge-cli --schema gives the tool definitions (examples in the user guide, Scripting > AI agents). API usage is billed by xAI."},
+ {Plan::Other, "Rovo in Atlassian's web apps only takes public HTTPS servers added by an admin: use Rovo Dev CLI."},
+ {Plan::Other, "Your own code with the OpenAI, Gemini or xAI API: sculptforge-cli --schema prints every tool as JSON (examples in the user guide, Scripting > AI agents)."},
+};
+
+std::string jsonArray(const std::vector<std::string>& items) {
+ std::string out = "[";
+ for (size_t i = 0; i < items.size(); ++i) out += (i ? ", " : "") + jsonString(items[i]);
+ return out + "]";
+}
+
+// "CMD ARG ARG" for a terminal.
+std::string commandLine(const Launch& l, Os os) {
+ std::string out = shellWord(l.command, os);
+ for (const std::string& a : l.args) out += " " + shellWord(a, os);
+ return out;
+}
+
+std::string serverEntry(const Launch& l, const char* extra = nullptr, const char* indent = " ") {
+ return std::string(indent) + "\"sculptforge\": {" + (extra ? extra : "") + "\"command\": " + jsonString(l.command) +
+ ", \"args\": " + jsonArray(l.args) + "}";
+}
+
+std::string wrapped(const char* key, const std::string& entry) {
+ return std::string("{\n \"") + key + "\": {\n" + entry + "\n }\n}";
+}
+
+std::string home(Os os, const char* posix, const char* windows) { return os == Os::Windows ? windows : posix; }
+
+Snippet terminal(std::string text) { return {K::Terminal, {}, std::move(text)}; }
+Snippet file(std::string where, std::string text) { return {K::File, std::move(where), std::move(text)}; }
+
+std::vector<Snippet> snippetsFor(const std::string& id, const Launch& l, Os os) {
+ const std::string cmd = commandLine(l, os);
+ const std::string mcpServers = wrapped("mcpServers", serverEntry(l, nullptr, " "));
+ if (id == "claude_desktop") {
+ const std::string where = os == Os::Windows ? "%APPDATA%\\Claude\\claude_desktop_config.json"
+ : os == Os::Mac ? "~/Library/Application Support/Claude/claude_desktop_config.json"
+ : "~/.config/Claude/claude_desktop_config.json";
+ return {file(where, mcpServers)};
+ }
+ if (id == "claude_code") return {terminal("claude mcp add --scope user sculptforge -- " + cmd)};
+ if (id == "codex")
+ return {terminal("codex mcp add sculptforge -- " + cmd),
+ file(home(os, "~/.codex/config.toml", "%USERPROFILE%\\.codex\\config.toml"),
+ "[mcp_servers.sculptforge]\ncommand = " + jsonString(l.command) + "\nargs = " + jsonArray(l.args))};
+ if (id == "antigravity")
+ return {file(home(os, "~/.gemini/config/mcp_config.json", "%USERPROFILE%\\.gemini\\config\\mcp_config.json"), mcpServers)};
+ if (id == "gemini_cli") {
+ std::string args;
+ for (const std::string& a : l.args) args += " " + shellWord(a, os);
+ return {terminal("gemini mcp add --scope user sculptforge " + shellWord(l.command, os) + args)};
+ }
+ if (id == "grok_build")
+ return {terminal("grok mcp add sculptforge -- " + cmd),
+ file(home(os, "~/.grok/config.toml", "%USERPROFILE%\\.grok\\config.toml"),
+ "[mcp_servers.sculptforge]\ncommand = " + jsonString(l.command) + "\nargs = " + jsonArray(l.args))};
+ if (id == "cursor") return {file(home(os, "~/.cursor/mcp.json", "%USERPROFILE%\\.cursor\\mcp.json"), mcpServers)};
+ if (id == "vscode") {
+ const std::string entry = "{\"name\": \"sculptforge\", \"type\": \"stdio\", \"command\": " + jsonString(l.command) +
+ ", \"args\": " + jsonArray(l.args) + "}";
+ std::vector<Snippet> out;
+ if (os != Os::Windows) out.push_back(terminal("code --add-mcp " + shellWord(entry, os))); // (cmd.exe quoting of JSON is not worth it)
+ out.push_back(file("MCP: Open User Configuration", wrapped("servers", serverEntry(l, "\"type\": \"stdio\", "))));
+ return out;
+ }
+ if (id == "visual_studio") return {file("%USERPROFILE%\\.mcp.json", wrapped("servers", serverEntry(l, "\"type\": \"stdio\", ")))};
+ if (id == "jetbrains") return {file("Model Context Protocol (MCP) > Add > STDIO", mcpServers)};
+ if (id == "zed")
+ return {file(home(os, "~/.config/zed/settings.json", "zed: open settings file"),
+ wrapped("context_servers", serverEntry(l)))};
+ if (id == "windsurf")
+ return {terminal("devin mcp add -s user sculptforge -- " + cmd),
+ file(home(os, "~/.config/devin/mcp_config.json", "%APPDATA%\\devin\\mcp_config.json"), mcpServers)};
+ if (id == "copilot_cli") return {terminal("copilot mcp add sculptforge -- " + cmd)};
+ if (id == "cline")
+ return {terminal("cline mcp add sculptforge --yes -- " + cmd), file("MCP Servers > Configure", mcpServers)};
+ if (id == "continue") {
+ std::string yaml = "name: SculptForge\nversion: 0.0.1\nschema: v1\nmcpServers:\n - name: SculptForge\n type: stdio\n"
+ " command: " + jsonString(l.command) + "\n args:\n";
+ for (const std::string& a : l.args) yaml += " - " + jsonString(a) + "\n";
+ yaml.pop_back();
+ return {file(".continue/mcpServers/sculptforge.yaml", yaml)};
+ }
+ if (id == "kiro") return {file(home(os, "~/.kiro/settings/mcp.json", "%USERPROFILE%\\.kiro\\settings\\mcp.json"), mcpServers)};
+ if (id == "amazon_q")
+ return {terminal("q mcp add --name sculptforge --command " + shellWord(l.command, os) + " --args " +
+ shellWord(jsonArray(l.args), os))};
+ if (id == "warp") return {file("Settings > Agents > MCP servers > Add", mcpServers)};
+ if (id == "goose") {
+ std::string yaml = "extensions:\n sculptforge:\n name: SculptForge\n type: stdio\n cmd: " +
+ jsonString(l.command) + "\n args: " + jsonArray(l.args) + "\n enabled: true\n timeout: 300";
+ return {file(home(os, "~/.config/goose/config.yaml", "Goose's config.yaml (goose configure)"), yaml)};
+ }
+ if (id == "opencode") {
+ std::vector<std::string> all{l.command};
+ all.insert(all.end(), l.args.begin(), l.args.end());
+ return {file("opencode.json", "{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"sculptforge\": "
+ "{\"type\": \"local\", \"command\": " + jsonArray(all) + ", \"enabled\": true}\n }\n}")};
+ }
+ if (id == "rovo_dev")
+ return {file(home(os, "~/.rovodev/mcp.json", "%USERPROFILE%\\.rovodev\\mcp.json"),
+ wrapped("mcpServers", " \"sculptforge\": {\"command\": " + jsonString(l.command) + ", \"args\": " +
+ jsonArray(l.args) + ", \"transport\": \"stdio\"}"))};
+ if (id == "lm_studio") return {file("mcp.json", mcpServers)};
+ if (id == "jan") {
+ std::string args;
+ for (const std::string& a : l.args) args += (args.empty() ? "" : " ") + a;
+ return {{K::Fields, {}, "Server Name: sculptforge\nCommand: " + l.command + "\nArguments: " + args}};
+ }
+ if (id == "agents_sdk")
+ return {file("agent.py",
+ "import asyncio\n"
+ "from agents import Agent, Runner\n"
+ "from agents.mcp import MCPServerStdio\n\n"
+ "async def main():\n"
+ " async with MCPServerStdio(name=\"SculptForge\", client_session_timeout_seconds=60,\n"
+ " params={\"command\": " + jsonString(l.command) + ", \"args\": " +
+ jsonArray(l.args) + "}) as sf:\n"
+ " agent = Agent(name=\"Sculptor\", instructions=\"Use SculptForge's tools.\", mcp_servers=[sf])\n"
+ " result = await Runner.run(agent, \"Make a sphere, remesh it at 128 and export ball.glb\")\n"
+ " print(result.final_output)\n\n"
+ "asyncio.run(main())")};
+ return {};
+}
+
+} // namespace
+
+std::string jsonString(const std::string& s) {
+ std::string out = "\"";
+ for (const char ch : s) {
+ const unsigned char c = static_cast<unsigned char>(ch);
+ if (c == '"') out += "\\\"";
+ else if (c == '\\') out += "\\\\";
+ else if (c == '\n') out += "\\n";
+ else if (c == '\t') out += "\\t";
+ else if (c < 0x20) {
+ char buf[8];
+ std::snprintf(buf, sizeof buf, "\\u%04x", c);
+ out += buf;
+ } else out += ch;
+ }
+ return out + "\"";
+}
+
+std::string shellWord(const std::string& s, Os os) {
+ bool plain = !s.empty();
+ for (const char c : s)
+ if (!(std::isalnum(static_cast<unsigned char>(c)) || std::string_view("_-./:=@%+,").find(c) != std::string_view::npos ||
+ (os == Os::Windows && c == '\\')))
+ plain = false;
+ if (plain) return s;
+ if (os == Os::Windows) { // Command Prompt and PowerShell both take "..." (paths never hold a double quote)
+ std::string out = "\"";
+ for (const char c : s) out += c == '"' ? std::string("\\\"") : std::string(1, c);
+ return out + "\"";
+ }
+ std::string out = "'";
+ for (const char c : s) out += c == '\'' ? std::string("'\\''") : std::string(1, c);
+ return out + "'";
+}
+
+std::vector<Client> clients(const Launch& launch, Os os) {
+ std::vector<Client> out;
+ for (const Row& r : kAiClients) {
+ if (std::string_view(r.id) == "visual_studio" && os != Os::Windows) continue; // Windows only
+ // (its --args takes JSON, which Command Prompt and PowerShell quote differently: macOS and Linux only here)
+ if (std::string_view(r.id) == "amazon_q" && os == Os::Windows) continue;
+ out.push_back({r.id, r.name, r.plan, r.how, r.docs, snippetsFor(r.id, launch, os)});
+ }
+ return out;
+}
+
+std::vector<const char*> planNotes(Plan plan) {
+ std::vector<const char*> out;
+ for (const Note& n : kPlanNotes)
+ if (n.plan == plan) out.push_back(n.text);
+ return out;
+}
+
+const char* planName(Plan plan) {
+ switch (plan) {
+ case Plan::Claude: return "Claude";
+ case Plan::ChatGPT: return "ChatGPT";
+ case Plan::Gemini: return "Gemini";
+ case Plan::Grok: return "Grok";
+ case Plan::Other: return "Other tools";
+ }
+ return "";
+}
+
+std::string bundleUrl(Os os) {
+ const char* name = os == Os::Windows ? "SculptForge-windows-x86_64.mcpb"
+ : os == Os::Mac ? "SculptForge-macos.mcpb"
+#if defined(__aarch64__)
+ : "SculptForge-linux-arm64.mcpb";
+#else
+ : "SculptForge-linux-x86_64.mcpb";
+#endif
+ return std::string("https://github.com/islandmed/SculptForge/releases/latest/download/") + name;
+}
+
+} // namespace sf::connect
diff --git a/src/app/ConnectAi.h b/src/app/ConnectAi.h
new file mode 100644
index 00000000..503477de
--- /dev/null
+++ b/src/app/ConnectAi.h
@@ -0,0 +1,56 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Help > Connect an AI tool: for this install, the exact command or configuration each MCP client needs to start
+// `sculptforge-cli --mcp` (stdio only: the client starts SculptForge as a child process and talks over its standard
+// input and output; nothing listens on the network). Each client's format comes from its own documentation
+// (docs/guide/scripting.md "AI agents (MCP)" cites them); the window is PanelConnectAi.cpp.
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace sf::connect {
+
+// How a client starts the server: command plus arguments, the last one "--mcp".
+struct Launch {
+ std::string command;
+ std::vector<std::string> args;
+};
+
+enum class Os { Windows, Mac, Linux };
+// The "I have a ... subscription" picker: which clients sign in with that plan. Other = editors, local apps, SDKs.
+enum class Plan { Claude, ChatGPT, Gemini, Grok, Other };
+inline constexpr int kPlanCount = 5;
+
+// One way to set a client up: a line to paste into a terminal, a file to edit, or fields to fill in.
+struct Snippet {
+ enum class Kind { Terminal, File, Fields };
+ Kind kind = Kind::Terminal;
+ std::string file; // Kind::File: where (a path or a menu), shown above the text
+ std::string text; // exactly what to paste
+};
+
+struct Client {
+ const char* id;
+ const char* name; // product names stay English
+ Plan plan;
+ const char* how; // one line, English (translated with tr() in the window)
+ const char* docs; // the vendor's page this format was taken from
+ std::vector<Snippet> snippets;
+};
+
+// Every client for this launch and OS, in display order (clients that don't run on `os` are left out).
+std::vector<Client> clients(const Launch& launch, Os os);
+// Notes for a plan: the vendor's apps that only take remote (HTTPS) servers, sign-in caveats. English, for tr().
+std::vector<const char*> planNotes(Plan plan);
+const char* planName(Plan plan); // "Claude", "ChatGPT", "Gemini", "Grok", "Other tools"
+
+// Where the Claude Desktop bundle for `os` is downloaded (the newest release's .mcpb).
+std::string bundleUrl(Os os);
+
+// Quoting, exposed for tests: a JSON string literal (also valid TOML, YAML and Python), and one shell word.
+std::string jsonString(const std::string& s);
+std::string shellWord(const std::string& s, Os os);
+
+} // namespace sf::connect
diff --git a/src/app/I18nSpanish.cpp b/src/app/I18nSpanish.cpp
index b0b7913f..c308513c 100644
--- a/src/app/I18nSpanish.cpp
+++ b/src/app/I18nSpanish.cpp
@@ -3518,6 +3518,100 @@ constexpr Entry kSpanish[] = {
{"Stamp rotation", "Rotación del sello"},
{"Vector displacement", "Desplazamiento vectorial"},
{"World Size", "Tamaño en el mundo"},
+
+ // --- Help > Connect an AI tool (PanelConnectAi.cpp, ConnectAi.cpp) ---
+ {"Add to Cursor's global MCP file (or .cursor/mcp.json in a project).",
+ "Añádelo al archivo MCP global de Cursor (o a .cursor/mcp.json en un proyecto)."},
+ {"Add to Kiro's user MCP file.",
+ "Añádelo al archivo MCP de usuario de Kiro."},
+ {"Add to Rovo Dev's MCP file (acli rovodev mcp opens it).",
+ "Añádelo al archivo MCP de Rovo Dev (acli rovodev mcp lo abre)."},
+ {"Add to Zed's settings file (command palette: zed: open settings file).",
+ "Añádelo al archivo de ajustes de Zed (paleta de comandos: zed: open settings file)."},
+ {"Add to opencode.json.",
+ "Añádelo a opencode.json."},
+ {"Add to the global MCP file, then use it from Copilot Chat in Agent mode.",
+ "Añádelo al archivo MCP global y úsalo desde Copilot Chat en modo Agent."},
+ {"Add to:",
+ "Añadir a:"},
+ {"Add under extensions in Goose's configuration file (or goose configure > Add Extension > Command-Line Extension).",
+ "Añádelo en extensions del archivo de configuración de Goose (o goose configure > Add Extension > Command-Line Extension)."},
+ {"Claude Code uses your Pro, Max or Ultra plan when you sign in with your Claude account. If ANTHROPIC_API_KEY is set, it uses that key and API billing instead.",
+ "Claude Code usa tu plan Pro, Max o Ultra cuando inicias sesión con tu cuenta de Claude. Si ANTHROPIC_API_KEY está definida, usa esa clave y se factura como API."},
+ {"Claude on the web and on phones can't start programs on your computer: use Claude Desktop or Claude Code.",
+ "Claude en la web y en el móvil no puede iniciar programas en tu ordenador: usa Claude Desktop o Claude Code."},
+ {"Connect an AI tool",
+ "Conectar una herramienta de IA"},
+ {"Connect an AI tool...",
+ "Conectar una herramienta de IA..."},
+ {"Copied to the clipboard",
+ "Copiado al portapapeles"},
+ {"Download the Claude Desktop bundle",
+ "Descargar el paquete para Claude Desktop"},
+ {"Fields:",
+ "Campos:"},
+ {"For Gemini Code Assist Standard or Enterprise, or a Gemini API key. Run once in a terminal.",
+ "Para Gemini Code Assist Standard o Enterprise, o una clave de la API de Gemini. Ejecútalo una vez en una terminal."},
+ {"Google's CLI for personal Google accounts (free, Google AI Pro and Ultra). Add this to its MCP file, then sign in with Google.",
+ "La CLI de Google para cuentas personales de Google (gratis, Google AI Pro y Ultra). Añade esto a su archivo MCP e inicia sesión con Google."},
+ {"I have a subscription to",
+ "Tengo una suscripción a"},
+ {"In a terminal:",
+ "En una terminal:"},
+ {"Let an AI assistant use SculptForge's tools: it starts sculptforge-cli on this computer and talks to it directly. Nothing listens on the network. The assistant works on its own scene and saves files where you ask; open them here to see the result.",
+ "Deja que un asistente de IA use las herramientas de SculptForge: inicia sculptforge-cli en este ordenador y habla con él directamente. Nada escucha en la red. El asistente trabaja en su propia escena y guarda los archivos donde le pidas; ábrelos aquí para ver el resultado."},
+ {"Download the bundle for your system and install it in Claude Desktop under Settings > Extensions > Advanced settings. Or add SculptForge to its configuration file and restart it.",
+ "Descarga el paquete para tu sistema e instálalo en Claude Desktop en Settings > Extensions > Advanced settings. O añade SculptForge a su archivo de configuración y reinícialo."},
+ {"Other tools",
+ "Otras herramientas"},
+ {"Program tab > Install > Edit mcp.json, then paste this.",
+ "Pestaña Program > Install > Edit mcp.json, y pega esto."},
+ {"Rovo in Atlassian's web apps only takes public HTTPS servers added by an admin: use Rovo Dev CLI.",
+ "Rovo en las aplicaciones web de Atlassian solo acepta servidores HTTPS públicos añadidos por un administrador: usa Rovo Dev CLI."},
+ {"Run once in a terminal (Cline CLI), or paste into Cline's MCP settings (MCP Servers > Configure).",
+ "Ejecútalo una vez en una terminal (Cline CLI), o pégalo en los ajustes MCP de Cline (MCP Servers > Configure)."},
+ {"Run once in a terminal, or add to the user MCP file.",
+ "Ejecútalo una vez en una terminal, o añádelo al archivo MCP de usuario."},
+ {"Run once in a terminal, or open the command MCP: Open User Configuration and add the entry.",
+ "Ejecútalo una vez en una terminal, o abre el comando MCP: Open User Configuration y añade la entrada."},
+ {"Run once in a terminal, then choose Sign in with ChatGPT when Codex starts.",
+ "Ejecútalo una vez en una terminal y elige Sign in with ChatGPT cuando Codex se inicie."},
+ {"Run once in a terminal.",
+ "Ejecútalo una vez en una terminal."},
+ {"Run once in a terminal; it signs in with your Claude plan.",
+ "Ejecútalo una vez en una terminal; inicia sesión con tu plan de Claude."},
+ {"Save as a file in your workspace's .continue/mcpServers folder; tools work in agent mode.",
+ "Guárdalo como archivo en la carpeta .continue/mcpServers de tu espacio de trabajo; las herramientas funcionan en modo agent."},
+ {"Settings > Agents > MCP servers > Add, then paste this.",
+ "Settings > Agents > MCP servers > Add, y pega esto."},
+ {"Settings > MCP Servers > +, then fill in these fields.",
+ "Settings > MCP Servers > +, y rellena estos campos."},
+ {"Settings > Tools > AI Assistant > Model Context Protocol (MCP): Add, choose STDIO and paste this.",
+ "Settings > Tools > AI Assistant > Model Context Protocol (MCP): Add, elige STDIO y pega esto."},
+ {"Since June 2026 personal Google accounts (free, Google AI Pro, Google AI Ultra) use Antigravity CLI; Gemini CLI is for Gemini Code Assist and API keys.",
+ "Desde junio de 2026 las cuentas personales de Google (gratis, Google AI Pro, Google AI Ultra) usan Antigravity CLI; Gemini CLI es para Gemini Code Assist y claves de API."},
+ {"The ChatGPT app only connects to remote (HTTPS) servers, and SculptForge doesn't run one: nothing of yours listens on the network. Codex CLI runs on your computer and signs in with your ChatGPT plan.",
+ "La aplicación de ChatGPT solo se conecta a servidores remotos (HTTPS), y SculptForge no ejecuta ninguno: nada tuyo escucha en la red. Codex CLI se ejecuta en tu ordenador e inicia sesión con tu plan de ChatGPT."},
+ {"The Grok app (web, phone, X) can't reach programs on your computer, only public HTTPS servers: use Grok Build. xAI's documentation doesn't say which plans Grok Build's sign-in includes; it also takes an xAI API key.",
+ "La aplicación de Grok (web, móvil, X) no llega a los programas de tu ordenador, solo a servidores HTTPS públicos: usa Grok Build. La documentación de xAI no dice qué planes incluye el inicio de sesión de Grok Build; también acepta una clave de la API de xAI."},
+ {"Their documentation",
+ "Su documentación"},
+ {"This install:",
+ "Esta instalación:"},
+ {"Turn this off in Preferences > AI.",
+ "Desactívalo en Preferencias > IA."},
+ {"Use SculptForge from Claude, ChatGPT (Codex), Gemini, Grok, Cursor, VS Code and other AI tools: the exact command or settings for this install, with Copy buttons. The tool starts SculptForge on this computer; nothing listens on the network.",
+ "Usa SculptForge desde Claude, ChatGPT (Codex), Gemini, Grok, Cursor, VS Code y otras herramientas de IA: el comando o los ajustes exactos para esta instalación, con botones Copiar. La herramienta inicia SculptForge en este ordenador; nada escucha en la red."},
+ {"User guide: AI agents",
+ "Guía del usuario: agentes de IA"},
+ {"Your own agent in Python (uses the OpenAI API with an API key).",
+ "Tu propio agente en Python (usa la API de OpenAI con una clave de API)."},
+ {"Your own code with the OpenAI, Gemini or xAI API: sculptforge-cli --schema prints every tool as JSON (examples in the user guide, Scripting > AI agents).",
+ "Tu propio código con la API de OpenAI, Gemini o xAI: sculptforge-cli --schema imprime cada herramienta como JSON (ejemplos en la guía del usuario, Scripting > AI agents)."},
+ {"Your own code with the xAI API: sculptforge-cli --schema gives the tool definitions (examples in the user guide, Scripting > AI agents). API usage is billed by xAI.",
+ "Tu propio código con la API de xAI: sculptforge-cli --schema da las definiciones de las herramientas (ejemplos en la guía del usuario, Scripting > AI agents). xAI factura el uso de la API."},
+ {"xAI's coding agent (the grok command). Run once in a terminal; it signs in with your xAI account in the browser.",
+ "El agente de programación de xAI (el comando grok). Ejecútalo una vez en una terminal; inicia sesión con tu cuenta de xAI en el navegador."},
};
} // namespace
diff --git a/src/app/I18nTraditionalChinese.cpp b/src/app/I18nTraditionalChinese.cpp
index d84fcc38..adb733ce 100644
--- a/src/app/I18nTraditionalChinese.cpp
+++ b/src/app/I18nTraditionalChinese.cpp
@@ -3050,6 +3050,100 @@ constexpr Entry kTraditionalChinese[] = {
{"Stamp rotation", "印章旋轉"},
{"Vector displacement", "向量位移"},
{"World Size", "世界尺寸"},
+
+ // --- Help > Connect an AI tool (PanelConnectAi.cpp, ConnectAi.cpp) ---
+ {"Add to Cursor's global MCP file (or .cursor/mcp.json in a project).",
+ "加入 Cursor 的全域 MCP 檔案(或專案中的 .cursor/mcp.json)。"},
+ {"Add to Kiro's user MCP file.",
+ "加入 Kiro 的使用者 MCP 檔案。"},
+ {"Add to Rovo Dev's MCP file (acli rovodev mcp opens it).",
+ "加入 Rovo Dev 的 MCP 檔案(acli rovodev mcp 會開啟它)。"},
+ {"Add to Zed's settings file (command palette: zed: open settings file).",
+ "加入 Zed 的設定檔(命令面板:zed: open settings file)。"},
+ {"Add to opencode.json.",
+ "加入 opencode.json。"},
+ {"Add to the global MCP file, then use it from Copilot Chat in Agent mode.",
+ "加入全域 MCP 檔案,然後在 Copilot Chat 的 Agent 模式中使用。"},
+ {"Add to:",
+ "加入:"},
+ {"Add under extensions in Goose's configuration file (or goose configure > Add Extension > Command-Line Extension).",
+ "加入 Goose 設定檔的 extensions 下(或 goose configure > Add Extension > Command-Line Extension)。"},
+ {"Claude Code uses your Pro, Max or Ultra plan when you sign in with your Claude account. If ANTHROPIC_API_KEY is set, it uses that key and API billing instead.",
+ "以 Claude 帳號登入時,Claude Code 會使用你的 Pro、Max 或 Ultra 方案。若設定了 ANTHROPIC_API_KEY,則改用該金鑰並按 API 計費。"},
+ {"Claude on the web and on phones can't start programs on your computer: use Claude Desktop or Claude Code.",
+ "網頁版與手機版 Claude 無法啟動你電腦上的程式:請使用 Claude Desktop 或 Claude Code。"},
+ {"Connect an AI tool",
+ "連接 AI 工具"},
+ {"Connect an AI tool...",
+ "連接 AI 工具..."},
+ {"Copied to the clipboard",
+ "已複製到剪貼簿"},
+ {"Download the Claude Desktop bundle",
+ "下載 Claude Desktop 套件"},
+ {"Fields:",
+ "欄位:"},
+ {"For Gemini Code Assist Standard or Enterprise, or a Gemini API key. Run once in a terminal.",
+ "適用於 Gemini Code Assist Standard 或 Enterprise,或 Gemini API 金鑰。在終端機執行一次。"},
+ {"Google's CLI for personal Google accounts (free, Google AI Pro and Ultra). Add this to its MCP file, then sign in with Google.",
+ "Google 為個人 Google 帳號(免費、Google AI Pro 與 Ultra)提供的 CLI。將此加入其 MCP 檔案,然後以 Google 登入。"},
+ {"I have a subscription to",
+ "我訂閱了"},
+ {"In a terminal:",
+ "在終端機中:"},
+ {"Let an AI assistant use SculptForge's tools: it starts sculptforge-cli on this computer and talks to it directly. Nothing listens on the network. The assistant works on its own scene and saves files where you ask; open them here to see the result.",
+ "讓 AI 助理使用 SculptForge 的工具:它會在這台電腦上啟動 sculptforge-cli 並直接與之溝通。沒有任何東西在網路上監聽。助理在自己的場景中工作,並把檔案存到你指定的位置;在這裡開啟即可查看結果。"},
+ {"Download the bundle for your system and install it in Claude Desktop under Settings > Extensions > Advanced settings. Or add SculptForge to its configuration file and restart it.",
+ "下載適合你系統的套件,並在 Claude Desktop 的 Settings > Extensions > Advanced settings 中安裝。或將 SculptForge 加入其設定檔後重新啟動。"},
+ {"Other tools",
+ "其他工具"},
+ {"Program tab > Install > Edit mcp.json, then paste this.",
+ "Program 分頁 > Install > Edit mcp.json,然後貼上這段。"},
+ {"Rovo in Atlassian's web apps only takes public HTTPS servers added by an admin: use Rovo Dev CLI.",
+ "Atlassian 網頁應用程式中的 Rovo 只接受由管理員加入的公開 HTTPS 伺服器:請使用 Rovo Dev CLI。"},
+ {"Run once in a terminal (Cline CLI), or paste into Cline's MCP settings (MCP Servers > Configure).",
+ "在終端機執行一次(Cline CLI),或貼到 Cline 的 MCP 設定(MCP Servers > Configure)。"},
+ {"Run once in a terminal, or add to the user MCP file.",
+ "在終端機執行一次,或加入使用者 MCP 檔案。"},
+ {"Run once in a terminal, or open the command MCP: Open User Configuration and add the entry.",
+ "在終端機執行一次,或開啟命令 MCP: Open User Configuration 並加入此項目。"},
+ {"Run once in a terminal, then choose Sign in with ChatGPT when Codex starts.",
+ "在終端機執行一次,然後在 Codex 啟動時選擇 Sign in with ChatGPT。"},
+ {"Run once in a terminal.",
+ "在終端機執行一次。"},
+ {"Run once in a terminal; it signs in with your Claude plan.",
+ "在終端機執行一次;它會以你的 Claude 方案登入。"},
+ {"Save as a file in your workspace's .continue/mcpServers folder; tools work in agent mode.",
+ "存成工作區 .continue/mcpServers 資料夾中的檔案;工具在 agent 模式下運作。"},
+ {"Settings > Agents > MCP servers > Add, then paste this.",
+ "Settings > Agents > MCP servers > Add,然後貼上這段。"},
+ {"Settings > MCP Servers > +, then fill in these fields.",
+ "Settings > MCP Servers > +,然後填入這些欄位。"},
+ {"Settings > Tools > AI Assistant > Model Context Protocol (MCP): Add, choose STDIO and paste this.",
+ "Settings > Tools > AI Assistant > Model Context Protocol (MCP):Add,選擇 STDIO 並貼上這段。"},
+ {"Since June 2026 personal Google accounts (free, Google AI Pro, Google AI Ultra) use Antigravity CLI; Gemini CLI is for Gemini Code Assist and API keys.",
+ "自 2026 年 6 月起,個人 Google 帳號(免費、Google AI Pro、Google AI Ultra)使用 Antigravity CLI;Gemini CLI 則用於 Gemini Code Assist 與 API 金鑰。"},
+ {"The ChatGPT app only connects to remote (HTTPS) servers, and SculptForge doesn't run one: nothing of yours listens on the network. Codex CLI runs on your computer and signs in with your ChatGPT plan.",
+ "ChatGPT 應用程式只連接遠端(HTTPS)伺服器,而 SculptForge 不執行這種伺服器:你的電腦上沒有任何東西在網路上監聽。Codex CLI 在你的電腦上執行,並以你的 ChatGPT 方案登入。"},
+ {"The Grok app (web, phone, X) can't reach programs on your computer, only public HTTPS servers: use Grok Build. xAI's documentation doesn't say which plans Grok Build's sign-in includes; it also takes an xAI API key.",
+ "Grok 應用程式(網頁、手機、X)無法連到你電腦上的程式,只能連公開的 HTTPS 伺服器:請使用 Grok Build。xAI 的文件沒有說明 Grok Build 的登入包含哪些方案;它也接受 xAI API 金鑰。"},
+ {"Their documentation",
+ "官方文件"},
+ {"This install:",
+ "此安裝:"},
+ {"Turn this off in Preferences > AI.",
+ "可在偏好設定 > AI 中關閉。"},
+ {"Use SculptForge from Claude, ChatGPT (Codex), Gemini, Grok, Cursor, VS Code and other AI tools: the exact command or settings for this install, with Copy buttons. The tool starts SculptForge on this computer; nothing listens on the network.",
+ "從 Claude、ChatGPT(Codex)、Gemini、Grok、Cursor、VS Code 等 AI 工具使用 SculptForge:此安裝的確切命令或設定,附複製按鈕。該工具會在這台電腦上啟動 SculptForge;沒有任何東西在網路上監聽。"},
+ {"User guide: AI agents",
+ "使用者指南:AI 代理"},
+ {"Your own agent in Python (uses the OpenAI API with an API key).",
+ "你自己的 Python 代理(以 API 金鑰使用 OpenAI API)。"},
+ {"Your own code with the OpenAI, Gemini or xAI API: sculptforge-cli --schema prints every tool as JSON (examples in the user guide, Scripting > AI agents).",
+ "以 OpenAI、Gemini 或 xAI API 撰寫你自己的程式:sculptforge-cli --schema 會把每個工具輸出為 JSON(範例見使用者指南,Scripting > AI agents)。"},
+ {"Your own code with the xAI API: sculptforge-cli --schema gives the tool definitions (examples in the user guide, Scripting > AI agents). API usage is billed by xAI.",
+ "以 xAI API 撰寫你自己的程式:sculptforge-cli --schema 提供工具定義(範例見使用者指南,Scripting > AI agents)。API 用量由 xAI 計費。"},
+ {"xAI's coding agent (the grok command). Run once in a terminal; it signs in with your xAI account in the browser.",
+ "xAI 的程式設計代理(grok 命令)。在終端機執行一次;它會在瀏覽器中以你的 xAI 帳號登入。"},
};
} // namespace
diff --git a/src/app/Palettes.cpp b/src/app/Palettes.cpp
index a167e38f..6db519a1 100644
--- a/src/app/Palettes.cpp
+++ b/src/app/Palettes.cpp
@@ -593,6 +593,7 @@ void App::drawPalette_Help() {
menuAction(*this, "help.whats_new");
menuAction(*this, "help.check_updates");
menuAction(*this, "ui.command_palette");
+ menuAction(*this, "help.connect_ai"); // only while AI is on (PanelAi.cpp registers it)
menuAction(*this, "help.website");
menuAction(*this, "help.discord");
menuAction(*this, "help.report");
diff --git a/src/app/PanelAi.cpp b/src/app/PanelAi.cpp
index 38ac5487..7f39f3c7 100644
--- a/src/app/PanelAi.cpp
+++ b/src/app/PanelAi.cpp
@@ -55,6 +55,18 @@ void App::registerAiActions() {
"Brush Lab: describe a brush in words and AI builds it; tweak the recipe with sliders.");
flag("ui.generate3d", "Generate 3D", ICON_LC_WAND_SPARKLES, "Generate", &showImageTo3D_,
"Turn an image or a description into a sculptable model (Hugging Face, fal.ai, Meshy, ComfyUI or offline).");
+ // Help > Connect an AI tool (PanelConnectAi.cpp). (Managed policy, feat/studio-ready: register it only when MCP is
+ // allowed, sf::policy::mcpAllowed().)
+ Action connect;
+ connect.id = "help.connect_ai";
+ connect.label = "Connect an AI tool...";
+ connect.icon = ICON_LC_PLUG;
+ connect.palette = "Help";
+ connect.description = "Use SculptForge from Claude, ChatGPT (Codex), Gemini, Grok, Cursor, VS Code and other AI "
+ "tools: the exact command or settings for this install, with Copy buttons. The tool starts "
+ "SculptForge on this computer; nothing listens on the network.";
+ connect.run = [this] { showConnectAi_ = true; };
+ actions_.add(std::move(connect));
}
void App::setAiFeatures(bool on) {
@@ -76,6 +88,8 @@ void App::setAiFeatures(bool on) {
for (const std::string& name : ai::aiCommandNames()) actions_.removePrefix("cmd." + name);
actions_.removePrefix("ui.brush_lab");
actions_.removePrefix("ui.generate3d");
+ actions_.removePrefix("help.connect_ai");
+ showConnectAi_ = false;
showBrushLab_ = false;
showImageTo3D_ = false;
}
diff --git a/src/app/PanelConnectAi.cpp b/src/app/PanelConnectAi.cpp
new file mode 100644
index 00000000..56561c2f
--- /dev/null
+++ b/src/app/PanelConnectAi.cpp
@@ -0,0 +1,146 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Help > Connect an AI tool (app/ConnectAi.h): lead with "I have a ... subscription", then for each client that plan
+// signs in to, the exact command or configuration for this install with Copy buttons. Only while AI features are on
+// (Preferences > AI): the action is registered in registerAiActions() and removed with the others.
+#include "app/App.h"
+#include "app/ConnectAi.h"
+#include "app/I18n.h"
+
+#include <IconsLucide.h>
+#include <imgui.h>
+
+#include <filesystem>
+#include <string>
+
+namespace sf {
+
+namespace {
+
+connect::Os thisOs() {
+#if defined(_WIN32)
+ return connect::Os::Windows;
+#elif defined(__APPLE__)
+ return connect::Os::Mac;
+#else
+ return connect::Os::Linux;
+#endif
+}
+
+// How a client starts this install's server: Flatpak and AppImage through their own entry points, otherwise the
+// sculptforge-cli beside the app (macOS: in the bundle's Contents/MacOS).
+connect::Launch thisInstall() {
+ if (const char* flatpak = SDL_getenv("FLATPAK_ID"); flatpak && *flatpak)
+ return {"flatpak", {"run", "--command=sculptforge-cli", flatpak, "--mcp"}};
+ if (const char* appimage = SDL_getenv("APPIMAGE"); appimage && *appimage) return {appimage, {"--cli", "--mcp"}};
+#ifdef _WIN32
+ const char* exe = "sculptforge-cli.exe";
+#else
+ const char* exe = "sculptforge-cli";
+#endif
+ namespace fs = std::filesystem;
+ if (const char* base = SDL_GetBasePath()) {
+ std::error_code ec;
+ for (const fs::path& p : {fs::path(base) / exe, fs::path(base) / ".." / "MacOS" / exe})
+ if (fs::exists(p, ec)) return {fs::weakly_canonical(p, ec).make_preferred().string(), {"--mcp"}};
+ }
+ return {exe, {"--mcp"}}; // not found beside the app (a build tree): on PATH, hopefully
+}
+
+void copyButton(std::string& status, const std::string& text, const std::string& id) {
+ if (ImGui::SmallButton((std::string(tr("Copy")) + "##" + id).c_str())) {
+ SDL_SetClipboardText(text.c_str());
+ status = tr("Copied to the clipboard");
+ }
+}
+
+// The text exactly as it is pasted: monospace, read-only, selectable.
+void codeBox(const std::string& text, const std::string& id, ImFont* mono) {
+ int lines = 1;
+ for (const char c : text) lines += c == '\n';
+ if (mono) ImGui::PushFont(mono);
+ const float h = float(lines) * ImGui::GetTextLineHeight() + 2.0f * ImGui::GetStyle().FramePadding.y + 2.0f;
+ ImGui::InputTextMultiline(("##code" + id).c_str(), const_cast<char*>(text.c_str()), text.size() + 1,
+ ImVec2(-1.0f, h), ImGuiInputTextFlags_ReadOnly);
+ if (mono) ImGui::PopFont();
+}
+
+} // namespace
+
+void App::drawConnectAi() {
+ if (!showConnectAi_) return;
+ const float s = uiScale_;
+ ImGui::SetNextWindowSize(ImVec2(720 * s, 640 * s), ImGuiCond_FirstUseEver);
+ ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(), ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
+ if (!ImGui::Begin((std::string(tr("Connect an AI tool")) + "###connect_ai").c_str(), &showConnectAi_,
+ ImGuiWindowFlags_NoCollapse)) {
+ ImGui::End();
+ return;
+ }
+ const connect::Os os = thisOs();
+ const connect::Launch launch = thisInstall();
+ ImGui::TextWrapped("%s", tr("Let an AI assistant use SculptForge's tools: it starts sculptforge-cli on this computer "
+ "and talks to it directly. Nothing listens on the network. The assistant works on its own "
+ "scene and saves files where you ask; open them here to see the result."));
+ ImGui::Spacing();
+ std::string command = launch.command;
+ for (const std::string& a : launch.args) command += " " + a;
+ ImGui::TextDisabled("%s", tr("This install:"));
+ ImGui::SameLine();
+ ImGui::TextUnformatted(command.c_str());
+ ImGui::SameLine();
+ copyButton(status_, launch.command, "install");
+
+ ImGui::SeparatorText(tr("I have a subscription to"));
+ for (int p = 0; p < connect::kPlanCount; ++p) {
+ if (p) ImGui::SameLine();
+ const char* name = connect::planName(connect::Plan(p));
+ if (ImGui::RadioButton((std::string(p == int(connect::Plan::Other) ? tr("Other tools") : name) + "##plan" +
+ std::to_string(p)).c_str(),
+ connectPlan_ == p))
+ connectPlan_ = p;
+ }
+ const connect::Plan plan = connect::Plan(connectPlan_);
+ ImGui::PushStyleColor(ImGuiCol_Text, ImGui::GetStyleColorVec4(ImGuiCol_TextDisabled));
+ for (const char* note : connect::planNotes(plan)) ImGui::TextWrapped("%s", tr(note));
+ ImGui::PopStyleColor();
+ ImGui::Spacing();
+
+ if (ImGui::BeginChild("##clients", ImVec2(0, -ImGui::GetFrameHeightWithSpacing()), ImGuiChildFlags_None)) {
+ for (const connect::Client& c : connect::clients(launch, os)) {
+ if (c.plan != plan) continue;
+ ImGui::PushID(c.id);
+ ImGui::SeparatorText(c.name);
+ ImGui::TextWrapped("%s", tr(c.how));
+ if (std::string_view(c.id) == "claude_desktop" &&
+ ImGui::Button((std::string(ICON_LC_DOWNLOAD " ") + tr("Download the Claude Desktop bundle")).c_str()))
+ SDL_OpenURL(connect::bundleUrl(os).c_str());
+ for (size_t k = 0; k < c.snippets.size(); ++k) {
+ const connect::Snippet& sn = c.snippets[k];
+ const std::string id = std::to_string(k);
+ ImGui::TextDisabled("%s", sn.kind == connect::Snippet::Kind::Terminal ? tr("In a terminal:")
+ : sn.kind == connect::Snippet::Kind::Fields ? tr("Fields:")
+ : tr("Add to:"));
+ if (!sn.file.empty()) {
+ ImGui::SameLine();
+ ImGui::TextUnformatted(sn.file.c_str());
+ }
+ ImGui::SameLine();
+ copyButton(status_, sn.text, id);
+ codeBox(sn.text, id, fontMono_);
+ }
+ if (ImGui::SmallButton((std::string(ICON_LC_BOOK_OPEN " ") + tr("Their documentation")).c_str()))
+ SDL_OpenURL(c.docs);
+ ImGui::PopID();
+ ImGui::Spacing();
+ }
+ }
+ ImGui::EndChild();
+ if (ImGui::Button(tr("User guide: AI agents"))) guide_.open("scripting.md");
+ ImGui::SameLine();
+ ImGui::TextDisabled("%s", tr("Turn this off in Preferences > AI."));
+ ImGui::End();
+}
+
+} // namespace sf
diff --git a/src/app/UiTest.cpp b/src/app/UiTest.cpp
index 747a2ab3..2d04985d 100644
--- a/src/app/UiTest.cpp
+++ b/src/app/UiTest.cpp
@@ -796,6 +796,7 @@ double Demo::query(const std::string& name, bool& known) const {
if (name == "discord_requests") return double(app_.discordRequests_); // Join the community on Discord clicks
if (name == "support_requests") return double(app_.supportPageRequests_); // Support SculptForge clicks
if (name == "ai_enabled") return ai::aiEnabled() ? 1.0 : 0.0; // Preferences > AI (PanelAi.cpp)
+ if (name == "connect_ai_open") return app_.showConnectAi_ ? 1.0 : 0.0; // Help > Connect an AI tool (PanelConnectAi.cpp)
if (name == "discord_connects") return double(discord::connectAttempts()); // Show SculptForge on Discord: never in tests
if (name == "discord_presence") return app_.discordPrefs_.enabled ? 1.0 : 0.0;
if (name == "http_requests") return double(ai::httpRequestCount()); // every request this process started
diff --git a/src/app/main.cpp b/src/app/main.cpp
index 6e9b244e..f328b977 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -23,6 +23,10 @@
#include <memory>
#include <stdexcept>
#include <string>
+#include <vector>
+#ifndef _WIN32
+#include <unistd.h> // execv (--cli)
+#endif
namespace {
@@ -328,7 +332,25 @@ static int runMain(int argc, char** argv) {
return finishIsolated(code);
}
+#ifndef _WIN32
+// --cli ARGS...: runs sculptforge-cli beside this program with ARGS. An AppImage has one entry point, so this is how an
+// MCP client starts its server ("SculptForge.AppImage --cli --mcp", Help > Connect an AI tool). Only our own program.
+static int execCli(int argc, char** argv) {
+ const char* base = SDL_GetBasePath();
+ const std::string cli = std::string(base ? base : "") + "sculptforge-cli";
+ std::vector<char*> args{const_cast<char*>(cli.c_str())};
+ for (int i = 2; i < argc; ++i) args.push_back(argv[i]);
+ args.push_back(nullptr);
+ execv(cli.c_str(), args.data());
+ std::fprintf(stderr, "sculptforge: couldn't start %s\n", cli.c_str());
+ return 127;
+}
+#endif
+
int main(int argc, char** argv) {
+#ifndef _WIN32
+ if (argc >= 2 && std::string(argv[1]) == "--cli") return execCli(argc, argv);
+#endif
if (argc >= 2 && std::string(argv[1]) == "--ui-serve") return sf::runUiServer(argc - 1, argv + 1, runMain);
return runMain(argc, argv);
}
diff --git a/src/cli/McpServer.cpp b/src/cli/McpServer.cpp
index 4c28b454..1fc7819a 100644
--- a/src/cli/McpServer.cpp
+++ b/src/cli/McpServer.cpp
@@ -2,6 +2,8 @@
// SPDX-License-Identifier: GPL-3.0-or-later
#include "cli/McpServer.h"
+#include "cli/McpTools.h"
+
#include "core/BrushLibrary.h"
#include "core/Json.h"
@@ -45,6 +47,7 @@ Json toolList(const CommandRegistry& registry) {
tool.set("inputSchema", schema);
tools.push(tool);
}
+ tools.push(viewportImageTool()); // drawn here (cli/McpTools.h), not a registry command
Json result = Json::object();
result.set("tools", tools);
return result;
@@ -86,9 +89,13 @@ std::string handleMcpMessage(const CommandRegistry& registry, Document& doc, con
Json caps = Json::object(), tools = Json::object();
tools.set("listChanged", false);
caps.set("tools", tools);
+ Json prompts = Json::object();
+ prompts.set("listChanged", false);
+ caps.set("prompts", prompts); // the recipes (cli/McpTools.h)
result.set("capabilities", caps);
Json info = Json::object();
info.set("name", "sculptforge");
+ info.set("title", "SculptForge");
info.set("version", SCULPTFORGE_VERSION);
result.set("serverInfo", info);
result.set("instructions",
@@ -97,13 +104,40 @@ std::string handleMcpMessage(const CommandRegistry& registry, Document& doc, con
"subdivide/remesh/layers/decimate, then export_glb, export_usd, export_lods or splat_save. "
"A scene can hold several Parts (separate meshes, see part_list): edits apply to the active "
"one, exports write every visible one. "
- "Use mesh_info and splat_info to check results. File paths are on the user's machine.");
+ "Check each step by eye with viewport_image and by numbers with mesh_info (splat_info for "
+ "captures); every tool call is one undo step (undo takes it back). The prompts are ready-made "
+ "recipes (a creature head, a game-ready asset, rock variations, a lesson). File paths are on "
+ "the user's computer.");
return reply(id, result).dump();
}
if (method == "ping") return reply(id, Json::object()).dump();
if (method == "tools/list") return reply(id, toolList(registry)).dump();
+ if (method == "prompts/list") return reply(id, mcpPromptList()).dump();
+ if (method == "prompts/get") {
+ Json result;
+ std::string error;
+ if (!mcpPromptGet(msg["params"]["name"].asString(), msg["params"]["arguments"], result, error))
+ return errorReply(id, -32602, error).dump();
+ return reply(id, result).dump();
+ }
if (method == "tools/call") {
const std::string name = msg["params"]["name"].asString();
+ if (name == "viewport_image") {
+ Json content;
+ std::string error;
+ const bool ok = renderViewportImage(doc, msg["params"]["arguments"], content, error);
+ if (!ok) {
+ Json text = Json::object();
+ text.set("type", "text");
+ text.set("text", error);
+ content = Json::array();
+ content.push(text);
+ }
+ Json result = Json::object();
+ result.set("content", content);
+ result.set("isError", !ok);
+ return reply(id, result).dump();
+ }
if (!registry.find(name) || hiddenFromAgents(name)) return errorReply(id, -32602, "Unknown tool: " + name).dump();
Args args;
for (const auto& [key, value] : msg["params"]["arguments"].members()) {
diff --git a/src/cli/McpTools.cpp b/src/cli/McpTools.cpp
new file mode 100644
index 00000000..9541ce96
--- /dev/null
+++ b/src/cli/McpTools.cpp
@@ -0,0 +1,364 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "cli/McpTools.h"
+
+#include "ai/ImageTo3DService.h"
+#include "core/Document.h"
+#include "core/Image.h"
+
+#include <glm/glm.hpp>
+
+#include <algorithm>
+#include <cmath>
+#include <limits>
+#include <vector>
+
+namespace sf {
+
+namespace {
+
+// --- Recipes (MCP prompts) ---
+
+struct RecipeArg {
+ const char* name;
+ const char* description;
+ bool required;
+};
+
+struct Recipe {
+ const char* name;
+ const char* title;
+ const char* description;
+ std::vector<RecipeArg> args;
+ // The message the agent gets; {name} is replaced with that argument (or its default after '|': {count|20}).
+ const char* text;
+};
+
+// Every recipe ends with the same working rules.
+constexpr const char* kRules =
+ "\n\nWorking rules: call viewport_image after each step to check the result before going on. Every tool call is "
+ "one undo step, so if a step looks wrong, call undo and try again with other values. Use mesh_info (and "
+ "scene_overview, measure where available) for numbers. File paths are on the user's computer: ask before "
+ "writing anywhere outside the folder they named.";
+
+const std::vector<Recipe>& recipes() {
+ static const std::vector<Recipe> list = {
+ {"creature_head", "Creature head from a description",
+ "Block out, sculpt and detail a creature head from a short description.",
+ {{"description", "What the creature looks like, e.g. \"an old swamp troll with heavy brows\".", true},
+ {"output", "Where to save the result (a .glb or .sfproj path). Optional.", false}},
+ "Sculpt a creature head: {description}.\n"
+ "1. Block out the big forms with blockout (spheres for skull, jaw, brow, nose, ears; symmetry x) or "
+ "forgesphere_* commands, then make the mesh.\n"
+ "2. Remesh to an even surface (remesh) and subdivide two or three levels.\n"
+ "3. Shape the primary forms with stroke (Move, Clay Block, Smooth), checking front and side views.\n"
+ "4. Add secondary forms (wrinkles, brow folds, lips) at the higher levels, then fine detail (micro_noise or "
+ "small strokes).\n"
+ "5. Optionally paint it (set_color, paint_from_cavity).\n"
+ "6. Save to {output|a file the user names} and say what you made."},
+ {"stylised_bust", "Stylised bust from a reference image",
+ "Turn a reference picture into a stylised bust: generate or block out, then refine by eye.",
+ {{"image", "Path to the reference image on the user's computer.", true},
+ {"style", "The look, e.g. \"chunky game character\" or \"smooth vinyl toy\". Optional.", false}},
+ "Make a stylised bust from the reference image {image} in the style: {style|clean stylised}.\n"
+ "1. If image_to_3d is available (AI features on), generate a starting model from the image; otherwise "
+ "block out head, neck and shoulders with blockout or new_sphere and stroke.\n"
+ "2. Remesh it even (remesh), then compare viewport_image against the reference from the front and the side.\n"
+ "3. Push the proportions toward the style with large Move strokes, then simplify the planes.\n"
+ "4. Subdivide and sharpen the key edges (eyelids, lips, hair clumps).\n"
+ "5. Export a .glb next to the image and report the triangle count."},
+ {"game_ready", "Game-ready asset (retopology, UVs, bake, LODs)",
+ "Take the current high-poly sculpt to a game asset: retopology, UVs, baked maps and LODs.",
+ {{"engine", "unreal, godot or unity. Optional (default: a plain .glb set).", false},
+ {"triangles", "Target triangles for the game mesh, e.g. 8000. Optional.", false},
+ {"folder", "Output folder.", true}},
+ "Make the current sculpt game-ready for {engine|any engine (glTF)}, about {triangles|8000} triangles, into {folder}.\n"
+ "1. part_duplicate the sculpt to keep the high-poly source.\n"
+ "2. On the copy, qremesh to the target count (quads, even flow), then check its silhouette with "
+ "viewport_image against the source.\n"
+ "3. uv_unwrap it, then bake normal, ambient occlusion and colour maps from the high-poly Part (bake).\n"
+ "4. Export: for Unreal use export_unreal; otherwise export_lods (4 levels, ratio 0.5) as .glb.\n"
+ "5. Report every file written with its triangle count."},
+ {"rock_variations", "Rock variations",
+ "A set of different rocks from one base, each exported, for scattering in a game or a scene.",
+ {{"count", "How many rocks (default 20).", false}, {"folder", "Output folder.", true}},
+ "Make {count|20} distinct rocks and export each to {folder} as rock_01.glb, rock_02.glb...\n"
+ "For each rock: new_sphere, transform to a random squash and stretch, remesh, a few large Flatten or Trim "
+ "strokes for planes and broken faces (vary the seed), micro_noise or small strokes for surface grain, "
+ "decimate to a game-friendly size, then export_glb. Keep them different in silhouette: check a few with "
+ "viewport_image. End with a list of the files."},
+ {"teach_me", "Teach me step by step",
+ "A patient lesson: the agent does one small step at a time, shows it, and explains why.",
+ {{"topic", "What to learn, e.g. \"sculpting a nose\" or \"retopology\". Optional.", false}},
+ "Teach me {topic|the basics of digital sculpting} in SculptForge, one small step at a time. For each step: "
+ "say what you are about to do and why, do it with one tool call, call viewport_image so I see it, explain "
+ "what changed, then wait for me before the next step. Mention the matching tool or menu in the app so I can "
+ "try it by hand. Keep it short and friendly; undo anything I don't like."},
+ };
+ return list;
+}
+
+const Recipe* findRecipe(const std::string& name) {
+ for (const Recipe& r : recipes())
+ if (name == r.name) return &r;
+ return nullptr;
+}
+
+std::string argText(const Json& args, const std::string& name) {
+ const Json& v = args[name];
+ if (v.isString()) return v.asString();
+ if (v.isNumber()) {
+ const double d = v.asNumber();
+ return d == std::floor(d) ? std::to_string(static_cast<long long>(d)) : std::to_string(d);
+ }
+ return {};
+}
+
+std::string fillRecipe(const Recipe& r, const Json& args) {
+ std::string out, text = r.text;
+ for (size_t i = 0; i < text.size();) {
+ const size_t open = text.find('{', i);
+ const size_t close = open == std::string::npos ? open : text.find('}', open);
+ if (close == std::string::npos) {
+ out += text.substr(i);
+ break;
+ }
+ out += text.substr(i, open - i);
+ const std::string key = text.substr(open + 1, close - open - 1);
+ const size_t bar = key.find('|');
+ const std::string value = argText(args, key.substr(0, bar));
+ out += !value.empty() ? value : bar == std::string::npos ? std::string() : key.substr(bar + 1);
+ i = close + 1;
+ }
+ return out + kRules;
+}
+
+// --- Headless viewport_image: a small z-buffered rasteriser over the visible Parts ---
+
+constexpr int kDefaultSize = 768, kMinSize = 256, kMaxSize = 1536;
+
+struct View {
+ glm::vec3 center{0.0f}, right{1, 0, 0}, up{0, 1, 0}, forward{0, 0, -1};
+ float halfExtent = 1.0f; // world units from the centre to the image edge
+};
+
+void drawMesh(const Mesh& mesh, const View& view, int size, std::vector<float>& depth, std::vector<glm::vec3>& color) {
+ const glm::vec3 clay(0.78f, 0.74f, 0.70f);
+ const glm::vec3 light = glm::normalize(-view.forward + 0.6f * view.up + 0.5f * view.right); // key light, upper right
+ const bool smooth = mesh.normals.size() == mesh.positions.size();
+ const float toPixels = 0.5f * float(size) / view.halfExtent;
+ std::vector<glm::vec3> screen(mesh.positions.size()); // x, y in pixels (y down), z = depth toward the viewer
+ for (size_t v = 0; v < mesh.positions.size(); ++v) {
+ const glm::vec3 d = mesh.positions[v] - view.center;
+ screen[v] = {0.5f * float(size) + glm::dot(d, view.right) * toPixels,
+ 0.5f * float(size) - glm::dot(d, view.up) * toPixels, -glm::dot(d, view.forward)};
+ }
+ for (const glm::uvec3& t : mesh.triangles) {
+ const glm::vec3 &a = screen[t.x], &b = screen[t.y], &c = screen[t.z];
+ const float area = (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+ if (std::abs(area) < 1e-12f) continue;
+ const glm::vec3 faceN = glm::normalize(glm::cross(mesh.positions[t.y] - mesh.positions[t.x],
+ mesh.positions[t.z] - mesh.positions[t.x]));
+ const int x0 = std::max(0, int(std::floor(std::min({a.x, b.x, c.x}))));
+ const int x1 = std::min(size - 1, int(std::ceil(std::max({a.x, b.x, c.x}))));
+ const int y0 = std::max(0, int(std::floor(std::min({a.y, b.y, c.y}))));
+ const int y1 = std::min(size - 1, int(std::ceil(std::max({a.y, b.y, c.y}))));
+ for (int y = y0; y <= y1; ++y)
+ for (int x = x0; x <= x1; ++x) {
+ const float px = float(x) + 0.5f, py = float(y) + 0.5f;
+ const float w0 = ((b.x - px) * (c.y - py) - (b.y - py) * (c.x - px)) / area;
+ const float w1 = ((c.x - px) * (a.y - py) - (c.y - py) * (a.x - px)) / area;
+ const float w2 = 1.0f - w0 - w1;
+ if (w0 < 0.0f || w1 < 0.0f || w2 < 0.0f) continue;
+ const float z = w0 * a.z + w1 * b.z + w2 * c.z;
+ float& stored = depth[size_t(y) * size_t(size) + size_t(x)];
+ if (z <= stored) continue;
+ stored = z;
+ glm::vec3 n = smooth ? w0 * mesh.normals[t.x] + w1 * mesh.normals[t.y] + w2 * mesh.normals[t.z] : faceN;
+ n = glm::length(n) > 0.0f ? glm::normalize(n) : faceN;
+ if (glm::dot(n, view.forward) > 0.0f) n = -n; // back faces lit like front faces
+ const glm::vec3 base = mesh.hasColors()
+ ? w0 * mesh.colors[t.x] + w1 * mesh.colors[t.y] + w2 * mesh.colors[t.z]
+ : clay;
+ const float diffuse = std::max(0.0f, glm::dot(n, light));
+ const float rim = std::pow(1.0f - std::abs(glm::dot(n, view.forward)), 3.0f);
+ color[size_t(y) * size_t(size) + size_t(x)] = base * (0.25f + 0.75f * diffuse) + glm::vec3(0.15f * rim);
+ }
+ }
+}
+
+} // namespace
+
+Json mcpPromptList() {
+ Json prompts = Json::array();
+ for (const Recipe& r : recipes()) {
+ Json args = Json::array();
+ for (const RecipeArg& a : r.args) {
+ Json arg = Json::object();
+ arg.set("name", a.name);
+ arg.set("description", a.description);
+ arg.set("required", a.required);
+ args.push(arg);
+ }
+ Json p = Json::object();
+ p.set("name", r.name);
+ p.set("title", r.title);
+ p.set("description", r.description);
+ p.set("arguments", args);
+ prompts.push(p);
+ }
+ Json result = Json::object();
+ result.set("prompts", prompts);
+ return result;
+}
+
+bool mcpPromptGet(const std::string& name, const Json& args, Json& result, std::string& error) {
+ const Recipe* r = findRecipe(name);
+ if (!r) {
+ error = "Unknown prompt: " + name;
+ return false;
+ }
+ for (const RecipeArg& a : r->args)
+ if (a.required && argText(args, a.name).empty()) {
+ error = std::string("Missing argument: ") + a.name;
+ return false;
+ }
+ Json text = Json::object();
+ text.set("type", "text");
+ text.set("text", fillRecipe(*r, args));
+ Json message = Json::object();
+ message.set("role", "user");
+ message.set("content", text);
+ Json messages = Json::array();
+ messages.push(message);
+ result = Json::object();
+ result.set("description", r->description);
+ result.set("messages", messages);
+ return true;
+}
+
+Json viewportImageTool() {
+ auto prop = [](const char* type, const char* description) {
+ Json p = Json::object();
+ p.set("type", type);
+ p.set("description", description);
+ return p;
+ };
+ Json props = Json::object();
+ props.set("size", prop("number", "Image width and height in pixels (256 to 1536, default 768)."));
+ props.set("yaw", prop("number", "Degrees around the model: 0 = front, 90 = the model's right side, 180 = back."));
+ props.set("elevation", prop("number", "Degrees above the model, -89 to 89; positive looks down on it."));
+ props.set("frame", prop("string", "What to fit in the picture: \"all\" visible Parts (default), \"active\", or a Part's name."));
+ props.set("preset", prop("string", "A named view instead of yaw/elevation: front, back, left, right, top, bottom or "
+ "three_quarter (the default when no angle is given)."));
+ props.set("zoom", prop("number", "Magnification of the framed Parts (default 1; 2 shows half as much)."));
+ props.set("ortho", prop("boolean", "Orthographic (no perspective). The headless server always draws orthographic."));
+ Json schema = Json::object();
+ schema.set("type", "object");
+ schema.set("properties", props);
+ schema.set("required", Json::array());
+ Json tool = Json::object();
+ tool.set("name", "viewport_image");
+ tool.set("description",
+ "A picture of the scene as a PNG, to check the result of a step by eye. Clay-shaded, vertex colours shown, "
+ "orthographic; call it after each step.");
+ tool.set("inputSchema", schema);
+ return tool;
+}
+
+bool renderViewportImage(const Document& doc, const Json& args, Json& content, std::string& error) {
+ const int size = std::clamp(int(args["size"].asNumber(kDefaultSize)), kMinSize, kMaxSize);
+ // A preset, then explicit angles over it; nothing given: three-quarter.
+ float yawDeg = 35.0f, elevationDeg = 20.0f;
+ if (args["preset"].isString()) {
+ static const struct { const char* name; float yaw, elevation; } kPresets[] = {
+ {"front", 0, 0}, {"back", 180, 0}, {"left", -90, 0}, {"right", 90, 0},
+ {"top", 0, 89}, {"bottom", 0, -89}, {"three_quarter", 35, 20}};
+ bool known = false;
+ for (const auto& p : kPresets)
+ if (args["preset"].asString() == p.name) yawDeg = p.yaw, elevationDeg = p.elevation, known = true;
+ if (!known) {
+ error = "Unknown preset \"" + args["preset"].asString() + "\" (front, back, left, right, top, bottom, three_quarter).";
+ return false;
+ }
+ }
+ yawDeg = float(args["yaw"].asNumber(yawDeg));
+ elevationDeg = std::clamp(float(args["elevation"].asNumber(elevationDeg)), -89.0f, 89.0f);
+ const float yaw = glm::radians(yawDeg), pitch = glm::radians(elevationDeg);
+ const float zoom = std::clamp(float(args["zoom"].asNumber(1.0)), 0.1f, 20.0f);
+ const std::string frame = args["frame"].isString() ? args["frame"].asString() : "all";
+
+ // The Parts drawn (every visible one) and the ones framed.
+ std::vector<int> drawn, framed;
+ for (int i = 0; i < doc.partCount(); ++i) {
+ if (!doc.parts[size_t(i)].visible) continue;
+ drawn.push_back(i);
+ if (frame == "all" || (frame == "active" && i == doc.activePart) || frame == doc.parts[size_t(i)].name)
+ framed.push_back(i);
+ }
+ if (frame != "all" && frame != "active" && framed.empty()) {
+ error = "No visible Part named \"" + frame + "\" (part_list names them).";
+ return false;
+ }
+ glm::vec3 lo(std::numeric_limits<float>::max()), hi(-std::numeric_limits<float>::max());
+ for (const int i : framed)
+ for (const glm::vec3& p : doc.partMesh(i).positions) lo = glm::min(lo, p), hi = glm::max(hi, p);
+ if (lo.x > hi.x) {
+ error = "Nothing to show: the scene has no visible mesh (start with new_sphere or open).";
+ return false;
+ }
+
+ View view;
+ view.center = 0.5f * (lo + hi);
+ view.halfExtent = std::max(1e-6f, 0.55f * glm::length(hi - lo)) / zoom; // the bounding sphere, with a margin
+ // The model faces +Z, so the front view looks down -Z; yaw 90 looks at the model's right side (-X), elevation
+ // raises the camera.
+ const glm::vec3 eyeDir(-std::sin(yaw) * std::cos(pitch), std::sin(pitch), std::cos(yaw) * std::cos(pitch));
+ view.forward = -eyeDir;
+ view.right = glm::normalize(glm::cross(view.forward, glm::vec3(0, 1, 0)));
+ view.up = glm::cross(view.right, view.forward);
+
+ const size_t pixels = size_t(size) * size_t(size);
+ std::vector<float> depth(pixels, -std::numeric_limits<float>::max());
+ std::vector<glm::vec3> color(pixels);
+ for (int y = 0; y < size; ++y) // background: a quiet vertical gradient
+ std::fill_n(color.begin() + std::ptrdiff_t(y) * size, size,
+ glm::mix(glm::vec3(0.20f, 0.21f, 0.23f), glm::vec3(0.11f, 0.11f, 0.12f), float(y) / float(size)));
+ size_t triangles = 0;
+ for (const int i : drawn) {
+ drawMesh(doc.partMesh(i), view, size, depth, color);
+ triangles += doc.partMesh(i).triangles.size();
+ }
+
+ Image img;
+ img.width = img.height = size;
+ img.rgba.resize(pixels * 4);
+ for (size_t p = 0; p < pixels; ++p) {
+ const glm::vec3 c = glm::clamp(color[p], 0.0f, 1.0f);
+ img.rgba[p * 4 + 0] = uint8_t(std::lround(std::pow(c.x, 1.0f / 2.2f) * 255.0f)); // linear-ish to sRGB
+ img.rgba[p * 4 + 1] = uint8_t(std::lround(std::pow(c.y, 1.0f / 2.2f) * 255.0f));
+ img.rgba[p * 4 + 2] = uint8_t(std::lround(std::pow(c.z, 1.0f / 2.2f) * 255.0f));
+ img.rgba[p * 4 + 3] = 255;
+ }
+ std::vector<uint8_t> png;
+ if (!img.encodePng(png)) {
+ error = "Couldn't encode the picture.";
+ return false;
+ }
+ Json image = Json::object();
+ image.set("type", "image");
+ image.set("data", ai::base64Encode(png.data(), png.size()));
+ image.set("mimeType", "image/png");
+ Json note = Json::object();
+ note.set("type", "text");
+ note.set("text", std::to_string(size) + " px, yaw " + std::to_string(int(std::lround(glm::degrees(yaw)))) +
+ ", elevation " + std::to_string(int(std::lround(glm::degrees(pitch)))) + ", " +
+ std::to_string(drawn.size()) + " visible Part(s), " + std::to_string(triangles) +
+ " triangles (headless clay view).");
+ content = Json::array();
+ content.push(image);
+ content.push(note);
+ return true;
+}
+
+} // namespace sf
diff --git a/src/cli/McpTools.h b/src/cli/McpTools.h
new file mode 100644
index 00000000..974bb6d9
--- /dev/null
+++ b/src/cli/McpTools.h
@@ -0,0 +1,30 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// What the headless MCP server (cli/McpServer.h) and live mode (sculptforge-cli --attach) share, so an agent
+// sees one tool set either way:
+// - the recipes: MCP prompts (prompts/list, prompts/get) that walk an agent through a whole job;
+// - viewport_image: a picture of the scene. Live mode shows the open viewport; the headless server draws the
+// visible Parts itself on the CPU (no window, no GPU), same name and schema.
+#pragma once
+
+#include "core/Json.h"
+
+#include <string>
+
+namespace sf {
+
+struct Document;
+
+// prompts/list's result: {"prompts": [{name, title, description, arguments}]}.
+Json mcpPromptList();
+// prompts/get: fills `result` ({description, messages}) or `error` (unknown recipe, a required argument missing).
+bool mcpPromptGet(const std::string& name, const Json& args, Json& result, std::string& error);
+
+// The viewport_image tool definition ({name, description, inputSchema}), for tools/list.
+Json viewportImageTool();
+// Headless viewport_image: draws doc's visible Parts (args: size, yaw, elevation, frame "all" | "active" | a Part's
+// name, preset, zoom; always orthographic) and fills `content` with an MCP content array (the PNG as image content, then a line about the view).
+bool renderViewportImage(const Document& doc, const Json& args, Json& content, std::string& error);
+
+} // namespace sf
diff --git a/tests/release_smoke.py b/tests/release_smoke.py
index 15582216..2138f2f4 100644
--- a/tests/release_smoke.py
+++ b/tests/release_smoke.py
@@ -4,12 +4,17 @@
#
# Release smoke test for a packaged sculptforge-cli (.github/workflows/release.yml runs it on every installed or
# unpacked package before anything is published; ctest runs it on the build tree): open a model, sculpt one stroke,
-# save a project, open that project again and check that it holds the sculpted mesh.
+# save a project, open that project again and check that it holds the sculpted mesh. Then the MCP server (--mcp): the
+# handshake, the tools and recipes, a tool call and a viewport_image picture, as an AI client would.
#
# python3 tests/release_smoke.py --cli path/to/sculptforge-cli [--out DIR]
+# python3 tests/release_smoke.py --mcp-only --cli "SculptForge.AppImage --cli" only the MCP check, through any
+# command that ends up in sculptforge-cli (the AppImage, a .mcpb's server)
import argparse
+import json
import os
import re
+import shlex
import subprocess
import sys
import tempfile
@@ -32,11 +37,57 @@ def vertices(path):
return [line for line in f if line.startswith("v ")]
+def mcp_check(command):
+ """The MCP server as a client sees it: returns a list of failures."""
+ lines = [
+ {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+ "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "smoke", "version": "1"}}},
+ {"jsonrpc": "2.0", "method": "notifications/initialized"},
+ {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+ {"jsonrpc": "2.0", "id": 3, "method": "prompts/list"},
+ {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "new_sphere", "arguments": {"subdivisions": 3}}},
+ {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "viewport_image", "arguments": {"size": 256}}},
+ ]
+ p = subprocess.run(command + ["--mcp"], input="".join(json.dumps(m) + "\n" for m in lines),
+ capture_output=True, text=True, timeout=120)
+ if p.returncode != 0:
+ return [f"--mcp exited with {p.returncode}: {p.stderr.strip()[-500:]}"]
+ replies = {}
+ for line in p.stdout.splitlines(): # stdout is the protocol: every line must be JSON-RPC
+ try:
+ r = json.loads(line)
+ except ValueError:
+ return [f"--mcp wrote a line that isn't JSON: {line[:200]}"]
+ replies[r.get("id")] = r
+ failures = []
+ init = replies.get(1, {}).get("result", {})
+ if init.get("serverInfo", {}).get("name") != "sculptforge" or "prompts" not in init.get("capabilities", {}):
+ failures.append(f"initialize: {replies.get(1)}")
+ tools = {t["name"] for t in replies.get(2, {}).get("result", {}).get("tools", [])}
+ if not {"remesh", "export_glb", "viewport_image"} <= tools:
+ failures.append(f"tools/list lacks remesh, export_glb or viewport_image ({len(tools)} tools)")
+ if len(replies.get(3, {}).get("result", {}).get("prompts", [])) < 5:
+ failures.append(f"prompts/list: {replies.get(3)}")
+ if replies.get(4, {}).get("result", {}).get("isError", True):
+ failures.append(f"new_sphere: {replies.get(4)}")
+ image = (replies.get(5, {}).get("result", {}).get("content") or [{}])[0]
+ if image.get("type") != "image" or len(image.get("data", "")) < 1000:
+ failures.append(f"viewport_image gave no picture: {str(replies.get(5))[:300]}")
+ return failures
+
+
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--cli", required=True)
ap.add_argument("--out")
+ ap.add_argument("--mcp-only", action="store_true")
a = ap.parse_args()
+ if a.mcp_only:
+ failures = mcp_check(shlex.split(a.cli, posix=os.name != "nt"))
+ for f in failures:
+ print("FAILED:", f)
+ print("MCP smoke: " + ("FAILED" if failures else "OK"))
+ return 1 if failures else 0
out = a.out or tempfile.mkdtemp(prefix="sf-release-smoke-")
os.makedirs(out, exist_ok=True)
before, after, again = (os.path.join(out, n) for n in ("before.obj", "after.obj", "reopened.obj"))
@@ -62,11 +113,12 @@ def main():
failures.append("the stroke moved no vertex")
if va != vr:
failures.append("the reopened project's mesh differs from the one saved")
+ failures += mcp_check([a.cli])
for f in failures:
print("FAILED:", f)
if failures:
return 1
- print(f"release smoke: OK ({moved} vertices moved by the stroke, project {os.path.getsize(project)} bytes)")
+ print(f"release smoke: OK ({moved} vertices moved by the stroke, project {os.path.getsize(project)} bytes; MCP server OK)")
return 0
diff --git a/tests/test_connect_ai.cpp b/tests/test_connect_ai.cpp
new file mode 100644
index 00000000..4746ba3c
--- /dev/null
+++ b/tests/test_connect_ai.cpp
@@ -0,0 +1,131 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Help > Connect an AI tool (app/ConnectAi.h): every client's snippet for this install, quoted right for paths with
+// spaces and backslashes; and what the headless MCP server shares with live mode (cli/McpTools.h): the recipes
+// (prompts) and viewport_image.
+#include "TestHarness.h"
+
+#include "app/ConnectAi.h"
+#include "cli/McpServer.h"
+#include "cli/McpTools.h"
+#include "core/Commands.h"
+#include "core/Document.h"
+#include "core/Image.h"
+#include "core/Json.h"
+
+#include <cstdio>
+#include <set>
+#include <string>
+
+using namespace sf;
+
+namespace {
+
+int checkClients(const connect::Launch& launch, connect::Os os) {
+ int problems = 0;
+ std::set<int> plans;
+ for (const connect::Client& c : connect::clients(launch, os)) {
+ plans.insert(int(c.plan));
+ if (c.snippets.empty() || std::string(c.docs).rfind("https://", 0) != 0 || !*c.how) {
+ std::printf(" %s: no snippet, how or docs link\n", c.id);
+ ++problems;
+ }
+ for (const connect::Snippet& s : c.snippets) {
+ // The path must appear exactly as typed in a terminal, or escaped in a file.
+ const bool hasPath = s.text.find(s.kind == connect::Snippet::Kind::Terminal ? connect::shellWord(launch.command, os)
+ : s.kind == connect::Snippet::Kind::Fields ? launch.command
+ : connect::jsonString(launch.command)) !=
+ std::string::npos;
+ if (!hasPath || s.text.find("--mcp") == std::string::npos) {
+ std::printf(" %s: the command or --mcp is missing:\n%s\n", c.id, s.text.c_str());
+ ++problems;
+ }
+ if (s.kind == connect::Snippet::Kind::File && s.text.front() == '{') { // JSON files must parse
+ Json j;
+ std::string err;
+ if (!Json::parseStrict(s.text, j, err)) {
+ std::printf(" %s: invalid JSON (%s):\n%s\n", c.id, err.c_str(), s.text.c_str());
+ ++problems;
+ }
+ }
+ }
+ }
+ if (plans.size() != size_t(connect::kPlanCount)) ++problems; // every subscription has at least one client
+ return problems;
+}
+
+} // namespace
+
+TEST(connect_ai_quoting) {
+ CHECK(connect::jsonString("C:\\Program Files\\SculptForge\\a\"b") == "\"C:\\\\Program Files\\\\SculptForge\\\\a\\\"b\"");
+ CHECK(connect::shellWord("/usr/bin/sculptforge-cli", connect::Os::Linux) == "/usr/bin/sculptforge-cli");
+ CHECK(connect::shellWord("/Applications/Sculpt Forge/it's", connect::Os::Mac) == "'/Applications/Sculpt Forge/it'\\''s'");
+ CHECK(connect::shellWord("C:\\Program Files\\SculptForge\\sculptforge-cli.exe", connect::Os::Windows) ==
+ "\"C:\\Program Files\\SculptForge\\sculptforge-cli.exe\"");
+ CHECK(connect::shellWord("C:\\SF\\sculptforge-cli.exe", connect::Os::Windows) == "C:\\SF\\sculptforge-cli.exe");
+}
+
+TEST(connect_ai_every_client_has_a_working_snippet) {
+ CHECK(checkClients({"C:\\Program Files\\SculptForge\\sculptforge-cli.exe", {"--mcp"}}, connect::Os::Windows) == 0);
+ CHECK(checkClients({"/Applications/SculptForge.app/Contents/MacOS/sculptforge-cli", {"--mcp"}}, connect::Os::Mac) == 0);
+ CHECK(checkClients({"/home/me/Apps/Sculpt Forge.AppImage", {"--cli", "--mcp"}}, connect::Os::Linux) == 0);
+ CHECK(checkClients({"flatpak", {"run", "--command=sculptforge-cli", "org.sculptforge.SculptForge", "--mcp"}},
+ connect::Os::Linux) == 0);
+ // Visual Studio is Windows only; the subscriptions lead to the vendors' own local tools.
+ bool vsOnMac = false, codex = false, antigravity = false, grok = false;
+ for (const connect::Client& c : connect::clients({"/x/sculptforge-cli", {"--mcp"}}, connect::Os::Mac)) {
+ vsOnMac = vsOnMac || std::string(c.id) == "visual_studio";
+ codex = codex || (std::string(c.id) == "codex" && c.plan == connect::Plan::ChatGPT);
+ antigravity = antigravity || (std::string(c.id) == "antigravity" && c.plan == connect::Plan::Gemini);
+ grok = grok || (std::string(c.id) == "grok_build" && c.plan == connect::Plan::Grok);
+ }
+ CHECK(!vsOnMac && codex && antigravity && grok);
+ CHECK(connect::bundleUrl(connect::Os::Mac).find(".mcpb") != std::string::npos);
+}
+
+TEST(mcp_recipes_are_prompts) {
+ CommandRegistry reg;
+ Document d;
+ Json init, j;
+ std::string err;
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":1,"method":"initialize","params":{}})"), init, err);
+ CHECK(init["result"]["capabilities"]["prompts"].isObject());
+ CHECK(init["result"]["serverInfo"]["title"].asString() == "SculptForge");
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":2,"method":"prompts/list"})"), j, err);
+ std::set<std::string> names;
+ for (const Json& p : j["result"]["prompts"].items()) names.insert(p["name"].asString());
+ CHECK(names.count("creature_head") && names.count("game_ready") && names.count("rock_variations") &&
+ names.count("stylised_bust") && names.count("teach_me"));
+ Json got;
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"rock_variations","arguments":{"folder":"/tmp/rocks"}}})"),
+ got, err);
+ const std::string text = got["result"]["messages"][0]["content"]["text"].asString();
+ CHECK(text.find("20 distinct rocks") != std::string::npos && text.find("/tmp/rocks") != std::string::npos &&
+ text.find("viewport_image") != std::string::npos);
+ Json missing;
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":4,"method":"prompts/get","params":{"name":"creature_head"}})"),
+ missing, err);
+ CHECK(missing.has("error")); // its description is required
+}
+
+TEST(mcp_viewport_image_headless) {
+ CommandRegistry reg;
+ Document d;
+ Json j, empty;
+ std::string err;
+ CHECK(!renderViewportImage(d, Json::object(), empty, err) && !err.empty()); // nothing to show yet
+ handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":0,"method":"tools/call","params":{"name":"new_sphere","arguments":{"subdivisions":3}}})");
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"viewport_image","arguments":{"size":256,"preset":"front"}}})"),
+ j, err);
+ const Json& image = j["result"]["content"][0];
+ CHECK(!j["result"]["isError"].asBool(true) && image["type"].asString() == "image" &&
+ image["mimeType"].asString() == "image/png" && image["data"].asString().size() > 1000);
+ Json content; // the defaults: 768 px, three-quarter view
+ CHECK(renderViewportImage(d, Json::object(), content, err));
+ CHECK(content[1]["text"].asString().find("768 px") != std::string::npos);
+ Json bad;
+ Json::parse(handleMcpMessage(reg, d, R"({"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"viewport_image","arguments":{"frame":"Nope"}}})"),
+ bad, err);
+ CHECK(bad["result"]["isError"].asBool(false));
+}
diff --git a/tests/test_core.cpp b/tests/test_core.cpp
index 83b11555..61879fb1 100644
--- a/tests/test_core.cpp
+++ b/tests/test_core.cpp
@@ -1165,8 +1165,9 @@ TEST(mcp_server_protocol) {
schemasOk = schemasOk && t["inputSchema"]["type"].asString() == "object";
packTools = packTools || t["name"].asString() == "pack_install" || t["name"].asString() == "pack_remove";
}
- // Every command but installing, removing and switching packs (the user's decision, never an agent's).
- CHECK(hasRemesh && schemasOk && !packTools && list["result"]["tools"].size() == reg.all().size() - 4);
+ // Every command but installing, removing and switching packs (the user's decision, never an agent's), plus
+ // viewport_image (cli/McpTools.h).
+ CHECK(hasRemesh && schemasOk && !packTools && list["result"]["tools"].size() == reg.all().size() - 4 + 1);
Json refused = call(R"({"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"pack_install","arguments":{"path":"x.sfpack"}}})");
CHECK(refused.has("error"));
Json ok = call(R"({"jsonrpc":"2.0","id":"a","method":"tools/call","params":{"name":"new_sphere","arguments":{"subdivisions":2}}})");
diff --git a/tests/ui/connect_ai.sfui b/tests/ui/connect_ai.sfui
new file mode 100644
index 00000000..1b2b4705
--- /dev/null
+++ b/tests/ui/connect_ai.sfui
@@ -0,0 +1,42 @@
+# Help > Connect an AI tool (PanelConnectAi.cpp): the subscription picker and, for this install, each tool's command or
+# settings. Only while AI features are on (Preferences > AI). UI tests never start a browser: no docs or bundle clicks.
+run ui_look look=classic layout=classic
+run new_sphere subdivisions=3
+run ai_features on=true
+click "Help##palette.help"
+expect "Connect an AI tool...##help.connect_ai"
+click "Connect an AI tool...##help.connect_ai"
+expect_value connect_ai_open == 1
+expect_text "This install:"
+expect_text "sculptforge-cli"
+# Claude first: Claude Desktop and Claude Code.
+expect_text "Claude Desktop"
+expect_text "claude mcp add --scope user sculptforge --"
+shot connect_claude
+click "ChatGPT##plan1"
+expect_text "codex mcp add sculptforge --"
+expect_text "The ChatGPT app only connects to remote (HTTPS) servers"
+shot connect_chatgpt
+click "Gemini##plan2"
+expect_text "Antigravity CLI"
+expect_text "mcp_config.json"
+shot connect_gemini
+click "Grok##plan3"
+expect_text "grok mcp add sculptforge --"
+shot connect_grok
+click "Other tools##plan4"
+expect_text "Cursor"
+expect_text "context_servers"
+expect_text "Rovo Dev CLI"
+shot connect_other
+# Copy puts the exact text on the clipboard.
+click "Copy##install"
+expect_status Copied to the clipboard
+expect_clipboard sculptforge-cli
+# AI off: the window closes and Help no longer offers it.
+run ai_features on=false
+expect_value connect_ai_open == 0
+click "Help##palette.help"
+expect_not "Connect an AI tool...##help.connect_ai"
+key Escape
+run ai_features on=true
diff --git a/tools/i18n/coverage.py b/tools/i18n/coverage.py
index 00031b77..9f7453a4 100644
--- a/tools/i18n/coverage.py
+++ b/tools/i18n/coverage.py
@@ -55,7 +55,7 @@ DYNAMIC = {
"Pen lower button", "Pen upper button", "Pen third button",
"Right mouse button"],
}
-TABLES = {"kPalettes": [1], "kMenus": [1, 3], "kHints": [1]}
+TABLES = {"kPalettes": [1], "kMenus": [1, 3], "kHints": [1], "kAiClients": [3], "kPlanNotes": [1]}
ACTION_FIELDS = ("label", "description", "palette")
# ImGui calls whose text is shown as it is: a literal handed to one of them never reaches tr() (--raw lists them).
RAW_IMGUI = {"Button": [0], "SmallButton": [0], "Text": [0], "TextDisabled": [0], "TextWrapped": [0],
diff --git a/tools/release/build_mcpb.py b/tools/release/build_mcpb.py
new file mode 100644
index 00000000..366662fa
--- /dev/null
+++ b/tools/release/build_mcpb.py
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The one-click Claude Desktop bundle: an MCP Bundle (.mcpb, https://github.com/modelcontextprotocol/mcpb, manifest
+0.3) holding this OS's sculptforge-cli, which Claude Desktop starts as `sculptforge-cli --mcp` (stdio, nothing on the
+network). One bundle per OS, built by packages.yml next to the other packages and attached to every release;
+mcp_server_json.py describes them for the MCP registry.
+
+ build_mcpb.py --cli build/sculptforge-cli --version 0.11.3 --platform linux --out build/SculptForge-0.11.3-linux-x86_64.mcpb
+ build_mcpb.py --cli ... --version auto --out "build/SculptForge-{version}-darwin-universal.mcpb" (CMakeLists.txt's)
+ build_mcpb.py --self-test
+
+A .mcpb is a zip with manifest.json at its root (the format `mcpb pack` writes); this writes it directly so packaging
+needs no Node. On Windows the DLLs beside the CLI come along. After packing, --check (default on) unpacks the bundle
+and runs its server through tests/release_smoke.py's MCP check, the way Claude Desktop would start it.
+"""
+import argparse
+import json
+import os
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+ICON = ROOT / "assets" / "branding" / "sculptforge-256.png"
+PLATFORMS = ("win32", "darwin", "linux")
+
+
+def manifest(version, platform):
+ exe = "server/sculptforge-cli" + (".exe" if platform == "win32" else "")
+ return {
+ "manifest_version": "0.3",
+ "name": "sculptforge",
+ "display_name": "SculptForge",
+ "version": version,
+ "description": "Digital sculpting for AI agents: make, sculpt, remesh, paint and export 3D models on your computer.",
+ "long_description": "SculptForge's tools for Claude: start from a sphere, a model file or a picture; sculpt, "
+ "remesh, retopologise, unwrap, bake and export (glTF, USD, FBX, OBJ, LODs for game engines). "
+ "Runs on your computer; nothing listens on the network. Free and open source (GPL-3.0).",
+ "author": {"name": "The SculptForge contributors", "url": "https://sculptforge.app"},
+ "homepage": "https://sculptforge.app",
+ "documentation": "https://sculptforge.app/guide/scripting.html",
+ "support": "https://github.com/islandmed/SculptForge/issues",
+ "repository": {"type": "git", "url": "https://github.com/islandmed/SculptForge"},
+ "license": "GPL-3.0-or-later",
+ "icon": "icon.png",
+ "keywords": ["3d", "sculpting", "modeling", "mesh", "gltf", "usd", "game assets"],
+ "server": {
+ "type": "binary",
+ "entry_point": exe,
+ "mcp_config": {"command": "${__dirname}/" + exe, "args": ["--mcp"], "env": {}},
+ },
+ "tools_generated": True, # every SculptForge command is a tool (sculptforge-cli --schema lists them)
+ "compatibility": {"platforms": [platform]},
+ }
+
+
+def check_manifest(m):
+ problems = [f"missing {k}" for k in ("manifest_version", "name", "version", "description", "author", "server") if k not in m]
+ if not m.get("author", {}).get("name"):
+ problems.append("author.name is required")
+ if m.get("server", {}).get("type") != "binary" or "${__dirname}" not in m["server"]["mcp_config"]["command"]:
+ problems.append("server must be a binary started from ${__dirname}")
+ if not all(p in PLATFORMS for p in m.get("compatibility", {}).get("platforms", [])):
+ problems.append("unknown platform")
+ return problems
+
+
+def pack(cli, version, platform, out):
+ cli = Path(cli)
+ m = manifest(version, platform)
+ problems = check_manifest(m)
+ if problems:
+ sys.exit("build_mcpb: " + "; ".join(problems))
+ out = Path(out)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
+ z.writestr("manifest.json", json.dumps(m, indent=2) + "\n")
+ z.write(ICON, "icon.png")
+ entries = [(cli, m["server"]["entry_point"])]
+ if platform == "win32": # the runtime DLLs the CLI was built with sit beside it
+ entries += [(d, "server/" + d.name) for d in sorted(cli.parent.glob("*.dll"))]
+ for src, name in entries:
+ info = zipfile.ZipInfo.from_file(src, name)
+ info.external_attr = (stat.S_IFREG | 0o755) << 16 # executable when unpacked (macOS, Linux)
+ info.compress_type = zipfile.ZIP_DEFLATED
+ with open(src, "rb") as f:
+ z.writestr(info, f.read())
+ return out
+
+
+def check_bundle(bundle):
+ """Unpack the bundle and talk to its server as Claude Desktop would."""
+ sys.path.insert(0, str(ROOT / "tests"))
+ import release_smoke # noqa: E402 (the MCP check lives with the other release smoke tests)
+ with tempfile.TemporaryDirectory(prefix="sf-mcpb-") as tmp:
+ with zipfile.ZipFile(bundle) as z:
+ z.extractall(tmp)
+ m = json.loads(z.read("manifest.json"))
+ exe = Path(tmp) / m["server"]["entry_point"]
+ exe.chmod(0o755)
+ failures = release_smoke.mcp_check([str(exe)])
+ for f in failures:
+ print("FAILED:", f)
+ return not failures
+
+
+def self_test():
+ with tempfile.TemporaryDirectory() as tmp:
+ fake = Path(tmp) / "sculptforge-cli.exe"
+ fake.write_bytes(b"MZ")
+ (Path(tmp) / "runtime.dll").write_bytes(b"dll")
+ out = pack(fake, "1.2.3", "win32", Path(tmp) / "x.mcpb")
+ with zipfile.ZipFile(out) as z:
+ names = set(z.namelist())
+ m = json.loads(z.read("manifest.json"))
+ assert names == {"manifest.json", "icon.png", "server/sculptforge-cli.exe", "server/runtime.dll"}, names
+ assert m["version"] == "1.2.3" and m["server"]["mcp_config"]["command"] == "${__dirname}/server/sculptforge-cli.exe"
+ assert not check_manifest(m) and check_manifest({"name": "x"})
+ assert not check_manifest(manifest("1.0.0", "darwin")) and manifest("1.0.0", "linux")["server"]["entry_point"] == "server/sculptforge-cli"
+ print("build_mcpb self-test: OK")
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--cli")
+ ap.add_argument("--version")
+ ap.add_argument("--platform", choices=PLATFORMS)
+ ap.add_argument("--out")
+ ap.add_argument("--no-check", action="store_true", help="skip running the bundled server")
+ ap.add_argument("--self-test", action="store_true")
+ a = ap.parse_args()
+ if a.self_test:
+ self_test()
+ return 0
+ if not (a.cli and a.version and a.platform and a.out):
+ ap.error("--cli, --version, --platform and --out are required")
+ if a.version == "auto": # the project's version (CMakeLists.txt), as CPack names the packages
+ a.version = re.search(r"project\(SculptForge VERSION ([0-9.]+)", (ROOT / "CMakeLists.txt").read_text()).group(1)
+ out = pack(a.cli, a.version, a.platform, a.out.replace("{version}", a.version))
+ print(f"{out} ({os.path.getsize(out) // 1024} KB)")
+ if not a.no_check and not check_bundle(out):
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/release/mcp_server_json.py b/tools/release/mcp_server_json.py
new file mode 100644
index 00000000..3e0e6c5a
--- /dev/null
+++ b/tools/release/mcp_server_json.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""server.json for the official MCP registry (registry.modelcontextprotocol.io): SculptForge as one server whose
+packages are the release's .mcpb bundles (build_mcpb.py), each by its GitHub release URL and SHA-256. release.yml
+writes it into the release; publishing it is the maintainer's (an account step):
+
+ mcp-publisher login github # as islandmed: the name below is io.github.islandmed/...
+ mcp-publisher publish server.json # the file from the release (or: mcp_server_json.py --version X.Y.Z --dist DIR)
+
+Schema and rules: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/
+(description at most 100 characters; mcpb packages only from GitHub or GitLab releases, URL containing "mcp", with
+fileSha256).
+
+ mcp_server_json.py --version 0.11.3 --dist dist [--out dist/server.json]
+ mcp_server_json.py --self-test
+"""
+import argparse
+import hashlib
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+SCHEMA = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"
+NAME = "io.github.islandmed/sculptforge"
+REPO = "https://github.com/islandmed/SculptForge"
+DESCRIPTION = "Digital sculpting for AI agents: make, sculpt, remesh, paint and export 3D models locally."
+
+
+def server_json(version, bundles):
+ packages = []
+ for b in sorted(bundles, key=lambda p: p.name):
+ packages.append({
+ "registryType": "mcpb",
+ "identifier": f"{REPO}/releases/download/v{version}/{b.name}",
+ "fileSha256": hashlib.sha256(b.read_bytes()).hexdigest(),
+ "transport": {"type": "stdio"},
+ })
+ return {
+ "$schema": SCHEMA,
+ "name": NAME,
+ "title": "SculptForge",
+ "description": DESCRIPTION,
+ "repository": {"url": REPO, "source": "github"},
+ "websiteUrl": "https://sculptforge.app",
+ "version": version,
+ "packages": packages,
+ }
+
+
+def check(doc):
+ problems = []
+ if len(doc["description"]) > 100:
+ problems.append("description over 100 characters")
+ if not doc["packages"]:
+ problems.append("no .mcpb bundles")
+ for p in doc["packages"]:
+ if "mcp" not in p["identifier"] or not p["identifier"].startswith("https://github.com/"):
+ problems.append(f"bad identifier {p['identifier']}")
+ return problems
+
+
+def self_test():
+ with tempfile.TemporaryDirectory() as tmp:
+ b = Path(tmp) / "SculptForge-1.2.3-darwin-universal.mcpb"
+ b.write_bytes(b"zip")
+ doc = server_json("1.2.3", [b])
+ assert not check(doc), check(doc)
+ assert doc["packages"][0]["identifier"].endswith("/v1.2.3/SculptForge-1.2.3-darwin-universal.mcpb")
+ assert doc["packages"][0]["fileSha256"] == hashlib.sha256(b"zip").hexdigest()
+ assert check(server_json("1.2.3", []))
+ print("mcp_server_json self-test: OK")
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--version")
+ ap.add_argument("--dist")
+ ap.add_argument("--out")
+ ap.add_argument("--self-test", action="store_true")
+ a = ap.parse_args()
+ if a.self_test:
+ self_test()
+ return 0
+ if not (a.version and a.dist):
+ ap.error("--version and --dist are required")
+ # The versioned bundles only (release.yml also adds version-less copies for fixed links).
+ bundles = [p for p in Path(a.dist).glob("SculptForge-*.mcpb") if f"-{a.version}-" in p.name]
+ doc = server_json(a.version, bundles)
+ problems = check(doc)
+ if problems:
+ sys.exit("mcp_server_json: " + "; ".join(problems))
+ out = Path(a.out or Path(a.dist) / "server.json")
+ out.write_text(json.dumps(doc, indent=2) + "\n", encoding="utf-8")
+ print(f"{out}: {len(bundles)} bundles")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())