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