feat(studio): integrate project MCP setup and lifecycle
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user