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
@@ -3,7 +3,7 @@
## Status, Scope and Authority
Owner: **studio**, application adapter and neutral automation API. This document
formalizes DEC-0060 B5–B9 and PLN-0139 steps 15–16. It complements
formalizes DEC-0060 B5–B9 and the integrated connection revision in DEC-0061 (PLN-0140). It complements
[DEV and Automation](10.%20DEV%20and%20Automation%20Specification.md), which owns
project authority, lifecycle, captures and phase gates. It does not change those
rules or the runtime-owned headless protocol.
@@ -11,7 +11,7 @@ rules or the runtime-owned headless protocol.
The packaged machine-readable input schemas, authority classification and
examples are in `prometeu-app/src/main/resources/mcp/studio-tools-v1.json`.
Contract version is `1.0`. Catalog membership is not runtime availability:
`tools/list` MUST expose only composed handlers, never placeholder implementations.
HTTP `tools/list` MUST expose only composed handlers, never placeholder implementations. The offline Studio stdio entry MUST advertise the packaged catalog and report unavailable live capabilities explicitly.
Steps 17–21 connect the functional providers and DEV configuration assistance;
steps 22–28 provide the real runtime gateway and integrated acceptance.
@@ -23,18 +23,24 @@ initialization exchange negotiates that supported revision; no compatibility
with other revisions or deprecated HTTP+SSE transport is claimed. An offered
unsupported revision receives the supported revision in `InitializeResult`.
Each start generates a fresh 256-bit random bearer token. Every request MUST
include `Authorization: Bearer <token>`. Missing/wrong credentials return 401.
There is no query-string token, OAuth, cookie authentication, remote bind option,
stdio bridge or wildcard listener. The endpoint has no query parameters.
Each desktop start generates a new instance identity. Each human project grant
publishes a fresh 256-bit bearer credential scoped to that canonical project root.
Every HTTP request MUST include `Authorization: Bearer <credential>`; missing,
wrong or revoked credentials return 401. Initialized HTTP sessions MUST be bound
to that credential/root; mixing another credential with an existing session returns
403. All tools, including knowledge reads, MUST enforce the authenticated root
before dispatch. No instance-wide credential bypass is permitted.
There is no query-string token, OAuth, cookie authentication, remote bind option
or wildcard listener. The endpoint has no query parameters. Studio also provides
its own stdio mode, described below; it is part of the same artifact.
Native clients may omit `Origin`. If present, it MUST exactly equal the live
endpoint's origin (`http://127.0.0.1:<port>`); `null`, other ports/hosts/schemes
and multiple Origin headers fail. Host MUST match the live loopback authority.
Unexpected origins/hosts return 403. No permissive browser CORS policy is emitted.
Credentials MUST NOT appear in diagnostics, exception messages, object string
representations, generated reports or versioned configuration. Explicit copying
for the external client is provided in step 21, not by logging startup secrets.
representations, generated reports or versioned configuration. The project discovery file is the only secret-bearing setup output; persistent client configuration and clipboard assistance MUST NOT export secrets.
Initialization assigns a separate random `Mcp-Session-Id`. Subsequent requests
include this header and the negotiated `MCP-Protocol-Version`. The server can
@@ -62,34 +68,87 @@ and [tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tool
contracts. Optional SSE, server-initiated requests, sampling, prompts, resource
subscriptions and list-change notifications are not advertised.
### 1.1 DEV Connection Assistance
### 1.1 Integrated Studio Entry and Offline Catalog
DEV displays the current endpoint without credentials and provides **Copy MCP
configuration** for an open project. The neutral `AgentConnectionGuide` supplies
availability and a deliberate clipboard export; JavaFX MUST NOT depend on the
HTTP server or keep credentials in labels, diagnostics, project state or history.
Connection lifecycle changes refresh availability. A closed project or stopped
server cannot export a descriptor. Unloading DEV only unsubscribes presentation
listeners; it does not stop the endpoint or revoke project authority.
`StudioLauncher mcp --project <absolute-root>` MUST dispatch before JavaFX or
Spring desktop startup. The root MUST be canonicalized once, contain the project
manifest and remain bound for the process lifetime, independently of client cwd.
The mode MUST NOT open a desktop, LSP, runtime or another HTTP listener. It uses
newline-framed UTF-8 JSON-RPC on stdin/stdout; stdout is protocol-only. Requests
are bounded to 1 MiB. EOF closes transport resources without releasing task control.
The copied text is a provider-neutral JSON descriptor with `transport` set to
`streamable-http`, the live `url`, `headers.Authorization`, canonical `projectRoot`
and `instructions`. It is not a promise of a drop-in configuration format for
every external client. The developer maps URL/header fields to that client's MCP
configuration; a provider-specific wizard remains out of scope. The secret is
materialized only for explicit copying and MUST NOT be written to versioned files
or logs. Clipboard success/failure feedback MUST NOT repeat credential-bearing
content or raw exceptions. The clipboard itself is a deliberate secret export.
Initialize, initialized notification, ping and tools/list MUST work before the
desktop, descriptor or grant exists. Offline descriptors come from the same
packaged catalog as HTTP. A deterministic fingerprint covers protocol and tool
schemas. Before forwarding, the connector MUST validate the descriptor, initialize
HTTP, check instance/root/fingerprint metadata, and compare live descriptors with
the packaged catalog. Missing handlers return unsupported capability; incompatible
protocol/schema fails explicitly rather than silently changing the client's tools.
Copied instructions and MCP initialization guidance direct the client to discover
actual tools, read project context and applicable language/SDK/library references,
wait for human grant before acquisition, edit saved files within project scope,
validate with LSP/build, recover operation receipts by clientRequestId and release
explicitly. Missing language support is a reported limitation, not a PBS fallback.
They also explain that SDK/external libraries are read-only, revocation cannot
stop external file writes, copying grants no authority, and a Studio restart
requires fresh endpoint/token configuration. No provider or model is required
to test this guidance and the MCP service contract.
Tool calls MUST preserve structuredContent, text/error blocks and native image
blocks. Response bounds MUST support images above the 1 MiB request limit; the
current response cap is 32 MiB, including a bounded body-read deadline. Network
redirects MUST NOT be followed. The connector MUST reject another project root.
Discovery runs on calls and bounded background checks. Missing publication means
waiting for access, not proof that the desktop is closed. Distinguish invalid
file/permissions, stale credentials/instance, catalog incompatibility and transport
reconnection. Calls cannot wait indefinitely for a grant. No reconnect path may
resubmit a tool call. An uncertain response MUST retain available clientRequestId
correlation and instruct receipt lookup within the same authorized task. A new
desktop/task has no old receipt registry and requires a fresh human grant.
### 1.2 Stable Installation and Project Preparation
The initial delivery targets Codex on macOS. Studio owns a versioned installation
under `~/Library/Application Support/Prometeu/Studio`, with an atomic `current`
reference. Each version includes `lib` dependencies and a compatible Java runtime
under `runtime`. Validate a staged version before switching `current`; retain
previous versions for rollback and already-running processes. Failed validation
MUST leave the existing reference intact. Registered commands MUST work without
an interactive shell PATH, external JDK or developer checkout.
The client command is the absolute `current/runtime/bin/java`, with argument-array
values `-cp`, `<current>/lib/*`, `p.studio.app.StudioLauncher`, `mcp`, `--project`,
and the canonical root. No project-local executable, generated transport script,
helper binary or separate launcher installation is allowed. The desktop and
connector use the same Studio artifact. JDWP is an explicit development-only JVM
option; IntelliJ attaches to the client-owned connector process separately from
the desktop Debug configuration.
New-project scaffolding and existing-project preparation MUST use the same neutral
preparation port. `.studio/setup.json` stores integration schema/enabled/profile
intent, preserving runtime/editor settings; it contains no endpoint/credential/task.
Application infrastructure owns `.codex/config.toml` serialization. Its managed
`mcp_servers.prometeu_studio` table stores the stable command, arguments, project
cwd and cold-start timeout. Preserve all unrelated tables, comments, approval
policy and server entries byte-for-byte; validate edits with a TOML parser.
Repetition with identical values MUST be a no-op. User-owned or modified managed
entries and tracked client configuration MUST produce an actionable conflict,
never an overwrite. Keep a protected recovery copy of the previous owned block
without copying unrelated secrets. Precise ignore rules protect machine-local
client configuration and transient discovery without deleting existing rules.
Preparation MUST report incomplete writes/installations truthfully. Trust/reload
instructions apply to initial client registration only; no client trust or tool
approval may be bypassed. Grant and desktop restart MUST NOT require changing the
client configuration. A clone is prepared locally to resolve its own installation
and project paths. No global client configuration is rewritten.
### 1.3 DEV Connection Assistance
DEV MUST expose preparation/readiness through neutral API contracts and show
connection status separately from Core authority. Waiting for access, connected
and reconnecting derive from project-scoped initialization/ping activity with a
bounded liveness window; a retained HTTP session ID alone is insufficient. Working
remains an authority/operation state. DEV MUST NOT invent knowledge of a client
before it connects. A transport drop MUST NOT revoke a task or grant new control.
Preparation, labels, clipboard, diagnostics and history MUST NOT expose secrets.
Closing/hiding DEV only unsubscribes visual listeners. Human grant/reclaim and
project/application teardown retain their shared Core semantics. Instructions
cover native file edits, project knowledge, grant/acquire, validation, receipt
lookup, images and explicit release without generated transport clients.
## 2. Identity and Admission
@@ -101,7 +160,7 @@ prove authorization.
The authority levels in the packaged catalog are:
- `authenticated`: connection authentication only; project/context/reference reads
are allowed before grant. No task token is returned by discovery.
need no acquired task. HTTP access still requires the project credential published by human grant. Offline catalog discovery returns no task token.
- `granted`: acquisition validates the prior human grant and atomically creates
the sole task identity. The transport session ID is not that identity.
- `task`: `projectRoot` and `taskId` must identify the current acquired task.
@@ -335,7 +394,7 @@ reference provider, not a Studio-maintained language specification.
`studio_project_context` resolves an exact, canonical root registered by an open
project session. It does not use the focused window, accept a source-directory
path as a project root, acquire a manual lease, or require an AI grant. A session
path as a project root, acquire a manual lease, or acquire task authority. The HTTP boundary separately requires the grant-published project credential. A session
is discoverable only after successful opening and until closure begins.
Unregistered/closed roots return `PROJECT_NOT_OPEN`.
@@ -395,8 +454,7 @@ example references identify their SDK major and target; unsupported selections
MUST NOT silently reuse another SDK/target. Numbered spec/draft revisions and the
reference-index schema revision MUST NOT be reported as language/compiler versions.
`studio_reference_read` is authenticated but does not require a control grant or
task. It resolves the explicit open root and its current saved manifest selection
`studio_reference_read` is authenticated but does not require an acquired task; the transport still requires a grant-published project credential. It resolves the explicit open root and its current saved manifest selection
on every read. Changing SDK/target can invalidate previously advertised IDs.
Only IDs in that project's installed index can be read, including when other
languages/providers are installed globally. SDK and external-library texts remain
@@ -442,7 +500,7 @@ The production registry composes all 17 tools as of step 23, including headless
handlers bound to the actual `HeadlessProcessGateway`. Missing project runtime
configuration fails at boot with `RUNTIME_UNAVAILABLE`; tool discovery does not
grant authority or launch a process. No fake runtime is shipped.
DEV configuration-copy is connected as of step 21. The automated HTTP conformance
The former configuration-copy flow is superseded by DEC-0061 permanent preparation and grant-time discovery. The automated HTTP conformance
gate exercises all 17 tool contracts using real project knowledge/LSP and test-only
build/runtime ports; a separate HTTP test uses the real compiler/packer. This
completes MCP-phase conformance. The packaged-runtime gate additionally exercises
@@ -493,3 +551,26 @@ cycles using the extracted Studio ZIP. The latter verified listener closure and
old-credential rejection after restart. API/Core and JavaFX MUST NOT import
MCP/HTTP implementations; architecture tests enforce it. Consolidated acceptance
evidence and deferred findings live in the DSC-0068 lesson, not in temporary logs.
### Integrated Connection Acceptance (DEC-0061)
Prior DSC-0068 native-client evidence covers the original HTTP flow only. The
integrated flow additionally requires a real native Codex session initialized
before grant, unchanged configuration through desktop restart/new grant, native
images/build/release, scaffold and existing-project preparation, installation
update and graphical launch, plus IntelliJ connector attachment. Automated
fixtures cannot substitute for these gates. PLN-0140 completed automated validation
and the user confirmed all outstanding manual gates on 2026-09-29. The manual
confirmation is user-reported acceptance, not an independently observed test run.
[LSN-0077](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md)
preserves the result and evidence provenance after workflow housekeeping.
### Automatic preparation when opening a project
Opening a project MUST prepare its enabled MCP integration using the same neutral
port as scaffold and DEV retry. Desktop composition MUST start the shared loopback
server before project sessions become available; no external command or separate
per-project desktop Run is required. Explicitly disabled integration MUST remain
disabled. Preparation failure MUST remain visible in DEV readiness without blocking
project use. Opening MUST NOT publish credentials or grant/acquire agent control.
The coding client continues to own its configured stdio process and initial trust.