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
@@ -0,0 +1,178 @@
---
id: LSN-0077
ticket: studio-persistent-mcp-connector
title: Integrated Studio MCP Through Stable Setup and Ephemeral Access
created: 2026-09-29
tags: [studio, mcp, connection, lifecycle, installation]
---
# Integrated Studio MCP: Stable Setup, Ephemeral Access
Owner: **studio**, MCP integration, project lifecycle and local installation.
DSC-0070 / DEC-0061 / PLN-0140 delivered this integration, including the user's
accepted revision for automatic preparation on project open. These identifiers
are historical references; maintained contracts are linked below. Automated
validation and the user's confirmation of final manual acceptance are recorded
separately.
## Original Problem
The original integration exposed a new HTTP port and bearer token on each Studio
restart. Developers had to configure their coding client repeatedly. Ad hoc
transport scripts then duplicated initialization, authentication and result
handling, obscuring native MCP tools and images.
The durable solution separates three lifetimes: installation, connection and
project authority. A stable client registration must not imply durable permission
to edit, and a transport interruption must not replay work.
## Consolidated Design
The distributed Studio artifact supports two modes. Normal invocation opens the
desktop. `StudioLauncher mcp --project <absolute-root>` runs a stdio connector
without JavaFX, Spring desktop composition, LSP or a second HTTP server. The coding
client owns that process; developers do not launch it manually for each project.
The desktop starts one shared loopback HTTP server. Opening a project prepares its
enabled integration automatically through the same neutral port used by scaffold
and the explicit DEV retry. An explicitly disabled integration remains disabled.
Preparation failure is visible in DEV and does not make the project unusable.
Opening a project does not publish credentials or grant control.
The macOS installation has a stable `current` reference pointing to a validated,
versioned distribution containing dependency JARs and Java. The native client
invokes the absolute installed Java path with a classpath/main/project argument
array. Updating the installation changes the reference, not every project's client
entry. Old versions remain available for rollback and existing processes.
The tradeoff is an additional lightweight JVM for stdio transport, plus managed
installation lifecycle. In return, there are no per-project launchers or copied
connector binaries, and execution does not depend on an interactive shell PATH.
## Configuration and Authority Have Different Owners
| Surface | Lifetime and responsibility |
| --- | --- |
| `.studio/setup.json` | Neutral integration intent; preserves runtime/editor settings |
| `.codex/config.toml` | Local installed command, arguments and canonical project binding; no transient credentials |
| `.studio/mcp/connection.json` | Protected, temporary discovery data published by human grant |
| Core grant/task/operation records | In-memory authority and receipts; never restored from configuration |
Preparation edits only a managed client entry, validates the result with a TOML
parser and preserves unrelated settings/comments. User-owned, edited or tracked
entries cause explicit conflicts. Initial client trust or reload may still be
required; Studio does not change approval policy.
Human grant publishes a fresh credential scoped to one canonical project root.
HTTP sessions are bound to that credential, and the server enforces scope even
for knowledge reads. Restricting only the connector would leave a direct HTTP
bypass. Acquisition still creates a separate task identity through shared Core
services.
## Publication Is Part of the Grant Transaction
Publication cannot be a best-effort snapshot listener. The neutral lifecycle port
coordinates preparation, publication, activation, invalidation and cleanup:
1. Save and verify documents under the existing handoff rules.
2. Acquire the OS publication lock and write a private temporary descriptor outside
the authority monitor.
3. Atomically publish, then activate under the grant generation fence. Acquisition
remains unavailable until the transition completes.
4. Abort failed or superseded grants and remove their provisional access.
5. Revoke credentials before asynchronous work cleanup; remove only the owned
publication and release its lock.
The lock file's inode is retained. Deleting it could let another process lock a
new inode while the first owner still holds the old one. The OS releases the lock
after a crash, allowing safe replacement of stale discovery data. Directories are
0700 and secret-bearing files 0600; Git exclusion alone is not access control.
Cleanup checks publication ownership so an old callback cannot delete newer data.
File cleanup failure must not prevent runtime cancellation.
## Reconnect Without Replaying Intent
The stdio connector initializes and lists its packaged catalog before Studio or a
grant is available. It verifies live instance, root and catalog identity before
forwarding. Calls preserve structured results and native image blocks; response
limits are separate from the smaller request limit.
Discovery and ping may be retried. Build and frame advancement must not be
resubmitted automatically after a lost response. Within the same authorized task,
recover by operationId/clientRequestId lookup. After restart, old in-memory
receipts are unavailable: report an unknown outcome and require a fresh grant/task
and an explicit next intent. Connection liveness and working/manual authority are
separate DEV states.
## Implementation Findings
- JSON-RPC numeric IDs must be compared by numeric value. Jackson can represent
the same wire number with different integer node types.
- Grant publication is asynchronous. Tests must await the transition without
blocking the JavaFX thread or assuming a button callback completes filesystem IO.
- `jlink` can generate read-only license files. Normalize staged runtime write
permissions so subsequent Gradle installation updates can replace them.
- An IntelliJ desktop can run from classes without a managed installation. A
generic “preparation incomplete” message hid this prerequisite. The specific
diagnostic now points to `:prometeu-app:stageStudioInstallation` and the optional
`studio.installationRoot` VM setting.
- Preparation belongs to project opening, not only creation or a manual DEV
button. Otherwise existing projects retain unnecessary onboarding friction.
- Capture data larger than 1 MiB must not inherit the request-body cap. The
connector bounds response size and body-read time separately.
## Verified Results and Acceptance
The full implementation gate recorded 839 passing tests, 15 existing skips and no
failures, including installation, desktop and real runtime gates. The later
missing-installation diagnostic and automatic-open revision passed their targeted
preparation, Core, app, architecture and runtime suites. Installation staging,
`git diff --check` and `discussion validate` also passed.
Process tests cover cold initialization, later grant and restart in one connector;
large images; root/session scope; stale identity/catalog rejection; lost build
response with execution count remaining one; unknown old-task receipts; concurrent
publisher JVMs and crash recovery; protected files; grant/close races; TOML
preservation; and stable installed Java across updates.
On 2026-09-29, after being asked specifically about the outstanding manual gates,
the user confirmed that all were finished. This closes the native Codex
acquire/build/image/release and reconnect-after-restart cycle, installation update
and graphical-client launch, and IntelliJ debugger attachment. The provenance of
this final evidence is **user-reported acceptance**, not an additional automated
run or an independently observed transcript. The implementation's automated
environment was macOS ARM64 with bundled Corretto 21.0.4 and Codex CLI 0.158.0
installed; that version inspection alone was not treated as native-client proof.
The prior HTTP-only acceptance from DSC-0068 was not substituted for these gates.
The first accepted integration remains Codex on macOS; other clients/platforms
and the embedded terminal are outside this delivery.
## Operational Example
Open the project in Studio. Its enabled client integration is prepared without a
separate per-project Run. Start the coding client in that project and satisfy its
initial trust/reload requirements. Grant access in DEV, acquire the task through
native tools, edit/validate, then release. After Studio restarts, grant again;
keep the client configuration unchanged. An old task is never restored.
For an IntelliJ desktop, run `p.studio.app.StudioLauncher` with the
`prometeu-app` classpath and Java 21. If a managed installation is missing, stage
it once with `./gradlew :prometeu-app:stageStudioInstallation`. An isolated
installation uses the `studio.installationRoot` desktop VM property. The MCP
stdio process remains client-owned; attach Remote JVM Debug to that process using
an explicit development-only loopback JDWP option. Do not configure the desktop
Run itself with `mcp --project` arguments.
## References
- DEC-0061 and PLN-0140: historical source decision and completed implementation
plan for DSC-0070; removed from active workflow during housekeeping.
- [Studio shell and project creation](../../../docs/specs/studio/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md).
- [Project-local state and discovery](../../../docs/specs/studio/8.%20Project-Local%20Studio%20State%20Specification.md).
- [Core and adapter architecture](../../../docs/specs/studio/9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
- [DEV and authority](../../../docs/specs/studio/10.%20DEV%20and%20Automation%20Specification.md).
- [MCP contract and acceptance boundary](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
- [Setup and IntelliJ debugging](../../../README.md).
- [DSC-0068 baseline lesson](../DSC-0068-studio-headless-runtime-ai-first/LSN-0076-ai-first-studio-through-shared-authority-and-headless-evidence.md).
- DSC-0071: the separate embedded-terminal discussion; unchanged by this work.