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