feat(studio): integrate project MCP setup and lifecycle
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
Test / Build skipped: 15, passed: 926
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

This commit is contained in:
2026-09-29 19:24:28 +01:00
parent 97cf5e1919
commit d0737df0ac
48 changed files with 2048 additions and 225 deletions
+76 -19
View File
@@ -32,25 +32,80 @@ At runtime, the app boots an embedded packer, restores project-local Studio stat
## External Coding Agents (MCP)
Open a project and select **DEV → Copy MCP configuration**. The copied JSON is a
provider-neutral connection descriptor: use its `url` and `headers.Authorization`
in your external client's Streamable HTTP MCP setup, and provide its `projectRoot`
and instructions to the agent. Adapt the configuration syntax to your client;
there is no embedded chat or provider-specific setup wizard.
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
client once; project grants and desktop restarts no longer require copying ports
or tokens. The initial integration targets Codex on macOS.
Keep the descriptor/token private and out of versioned files and logs. The endpoint
is local to this computer. After restarting Studio, copy it again and update the
client: both the port and token are ephemeral. Copying or connecting does not
authorize edits or start a task.
1. Install/stage Studio with its bundled Java runtime (see below). New projects
prepare the local client entry during scaffolding. Opening an existing project
also prepares its enabled integration automatically; Studio starts the shared
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
a reported setup conflict. Opening a project does not grant agent control.
2. Open the coding client in the project directory. Trust the project and reload
MCP once if the client requests it. Studio does not alter client approval policy.
Tools can initialize/list even before the desktop is open or access is granted.
3. Open the project in Studio and grant control in DEV (save first if prompted).
Active Debug prevents granting. The connector discovers access automatically.
4. The agent acquires a task, consults project/language/SDK references, edits saved
project files with its native tools and validates through LSP/build. SDK and
external libraries remain read-only.
5. Recover uncertain operations by operationId/clientRequestId lookup within the
same task; never replay build/advance blindly. Explicitly release control when
done. Human reclaim also revokes access; stop direct external file edits separately.
1. Connect, discover tools, read project context and applicable language/SDK references.
2. In DEV, grant control (save all first if prompted). Active Debug prevents granting.
3. The agent acquires a task, edits saved project files using its own tools, and
validates through LSP/build. SDK and external libraries are consultable, read-only.
4. Poll operations by operationId or clientRequestId. Recover a lost start receipt
by lookup; never retry frame advancement blindly with a new ID.
5. The agent explicitly releases control. To interrupt, use DEV's reclaim button
and stop the external client separately: Studio cannot prevent its direct file writes.
The client invokes the same Studio artifact over stdio. It forwards to Studio's
project-scoped loopback service using protected, transient
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
installed Java/classpath/root arguments, not credentials. Both local outputs are
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
Studio entries require deliberate resolution. `.studio/setup.json` preserves
neutral integration intent and existing runtime/editor settings.
After desktop restart, grant again in DEV. Keep the same client session and
configuration; old task identities and operation receipts are not restored.
DEV displays connection separately from project authority. No project-local
launcher, Python transport script or embedded chat is required.
### Installation and IntelliJ development
Build and stage the complete distribution, including its Java runtime:
```bash
./gradlew :prometeu-app:stageStudioInstallation
```
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
Staging validates a new version before atomically changing `current`, retaining
older versions for rollback and running processes. Native client registration
uses absolute paths and argument arrays, independent of shell PATH:
```text
command: <installation>/current/runtime/bin/java
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
```
For development, use an isolated installation:
```bash
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
```
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
The desktop and client-owned connector are separate JVMs. To debug the latter,
add the development-only VM argument
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
Because manual edits to the managed entry are protected, restore its original
content before using preparation again. Regular registration never enables JDWP.
The packaged automated gate checks bundled Java, upgrade/rollback, project paths
with spaces, minimal environment, scaffold/preparation and JavaFX startup:
```bash
./gradlew :prometeu-app:installedConnectorTest
```
The current production tools cover context, references, task control, LSP,
build/pack, operation lookup/cancellation and headless execution (17 tools).
@@ -67,7 +122,9 @@ for schemas, authorization, limits and delivery boundaries.
| Symptom | Action |
| --- | --- |
| Connection rejected after Studio restarts | Copy DEV's configuration again: the token and OS-assigned endpoint are session-local. Do not publish the token. |
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
@@ -127,7 +184,7 @@ are not considered fixed by the passing integration tests:
regression passes, but the toolchain/target alignment needs separate review.
Cross-platform desktop coverage remains a validation boundary, not a confirmed
product defect. Desktop acceptance so far covers macOS ARM64 and Codex CLI only.
product defect. Baseline HTTP desktop acceptance covers macOS ARM64 and Codex CLI only. The integrated stdio flow completed its separate acceptance gates through automated validation and user-confirmed native-client, graphical-launch and IntelliJ checks; see [LSN-0077](discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md) for evidence provenance.
The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input,
1,110 frames, native MCP images and explicit release. The developer confirmed the