Document why deploy and migrate are not MCP tools
Add a "Not exposed as tools (yet)" section to docs/interfaces.md explaining the deliberate omission of `deploy` and `migrate` from the MCP tool set: both are coupled to the local working directory (`.smb/config.toml`, local build toolchains, on-disk SSH keys, streamed progress) in ways a non-interactive stdio tool call cannot satisfy cleanly. Points automated deploys at the headless `smb --ci deploy` path and notes what a future directory-free tool contract would require. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019fkbx6fUq1uDR5N75Ph5zi
Claude committed
Jul 18, 2026 at 13:04 UTC
ac3adc4fa3f16be241b1bc9a02c0cba15814b0f7
1 file changed
+25
docs/interfaces.md
+25
@@ -71,6 +71,31 @@ Tools run non-interactively, so the write tools apply immediately without a
71
confirmation prompt — the calling client is responsible for confirming intent
72
before invoking `project_delete`.
73
74
+### Not exposed as tools (yet)
75
+
76
+`deploy` and `migrate` are **deliberately not** MCP tools. Both are tightly
77
+coupled to the local working directory in ways a stdio tool call can't satisfy
78
+cleanly:
79
+
80
+- **`deploy`** reads `.smb/config.toml` (running interactive `setup_project`
81
+ when it is missing), builds the app locally, then uploads over rsync and
82
+ restarts over SSH. It depends on the caller's current directory, local build
83
+ toolchains, and on-disk SSH keys, and it streams long-running progress — none
84
+ of which map onto a single non-interactive tool call. For automated deploys,
85
+ use the headless CLI path instead (`smb --ci deploy`, see [ci.md](./ci.md)),
86
+ which is what CI and the deploy action already drive.
87
+- **`migrate`** pushes local `.smb/config.toml` deploy fields up to the server,
88
+ so it is meaningless without a project directory to read from. The current
89
+ tools operate on explicit arguments (a project `id`, a `name`), not on
90
+ whatever directory the server process happens to be running in.
91
+
92
+Exposing either as a tool would mean designing an explicit, directory-free
93
+contract — e.g. accepting the full deploy configuration as arguments and
94
+returning streamed progress as structured events — rather than wrapping the
95
+existing directory-coupled handlers. That is intentionally left for a later
96
+pass; the tools above cover the read and project-management surface that is
97
+well-defined over stdio today.
98
+
99
### Wiring it into an MCP client
100
101
Most MCP clients take a command plus arguments. Point the client at the `smb`