feat(studio): integrate project MCP setup and lifecycle
This commit is contained in:
@@ -142,3 +142,23 @@ This specification is complete enough when:
|
||||
- workspace and shell responsibilities are clearly separated;
|
||||
- the shell-level expectations for workspace architecture are explicit;
|
||||
- the baseline Studio frame is stable enough for implementation planning.
|
||||
|
||||
## Project Assistant Preparation (DEC-0061)
|
||||
|
||||
Project creation MUST scaffold neutral agent-integration intent in
|
||||
`.studio/setup.json` and invoke the same preparation port used by existing
|
||||
projects in DEV. Application infrastructure resolves installed Studio and client
|
||||
configuration; the wizard/Core MUST NOT serialize provider TOML or launch an
|
||||
agent. Failed preparation leaves a usable project with actionable incomplete
|
||||
readiness in DEV, never a false ready claim. Runtime/editor settings and unrelated
|
||||
client configuration MUST survive. Preparation grants no project control.
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -164,7 +164,7 @@ DEV MUST expose:
|
||||
- the four control states, project identity, current managed operation and diagnostics;
|
||||
- a canonical-image canvas with session/build/logical-frame/render-frame identity and stale status;
|
||||
- a short history of Studio calls, not an independent code history;
|
||||
- **Copy MCP configuration**, plus short connection/use instructions when the real MCP composition is available.
|
||||
- **Prepare assistant**, plus short connection/use instructions when the real MCP composition is available.
|
||||
|
||||
Actions MUST reflect shared service authority. DEV MUST NOT own a duplicate
|
||||
lock or release authority when disposing visual subscriptions. Presentation
|
||||
@@ -177,8 +177,7 @@ in Debug with its existing host/protocol/lifecycle, subject to symmetric guards.
|
||||
“Agent working” means the task has been acquired; it is not a claim to observe
|
||||
all external edits, reasoning or conversation.
|
||||
|
||||
Without a real composed MCP endpoint, configuration copy MUST be unavailable
|
||||
rather than produce a fabricated endpoint or token. Test doubles MAY supply
|
||||
Preparation MUST report missing installation or configuration conflicts explicitly; it does not depend on a live grant or fabricate endpoint credentials. Test doubles MAY supply
|
||||
operations/captures to isolated tests, never masquerade as product execution.
|
||||
|
||||
## 6. Operations and Lost Responses
|
||||
@@ -274,19 +273,18 @@ that it uses. Capture/build correlation MUST NOT introduce code snapshots.
|
||||
Concrete tool names, input schemas, response envelopes and HTTP lifecycle are
|
||||
specified in [MCP Tools and Project Knowledge Contract](11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
||||
|
||||
The app MUST host Streamable HTTP at `127.0.0.1:<OS-assigned-port>/mcp` while
|
||||
Studio is open. It MUST generate a random token per Studio start, require it
|
||||
on connections, validate Origin and reject unexpected origins. No remote
|
||||
binding, accounts, OAuth or stdio MCP bridge is part of this baseline.
|
||||
|
||||
Copied configuration MUST contain the actual endpoint/token and MUST NOT be
|
||||
written to versioned files. Instructions MUST explain that restart requires
|
||||
refreshing client configuration. Copying configuration and authenticating
|
||||
MUST NOT grant control.
|
||||
The desktop MUST host Streamable HTTP at `127.0.0.1:<OS-assigned-port>/mcp`.
|
||||
DEC-0061 adds Studio-owned stdio discovery and one-time preparation as specified
|
||||
in spec 11. Each human grant publishes a fresh project-scoped credential through
|
||||
the required lifecycle participant in spec 8. Authentication, project scope and
|
||||
task identity remain separate checks. There is no global credential bypass.
|
||||
Restart invalidates old access and requires a fresh human grant, while the native
|
||||
client's command/configuration remains unchanged. No remote binding, accounts or
|
||||
OAuth are introduced. Preparation never grants editing authority.
|
||||
|
||||
| Tool group | Required capabilities | Required authority |
|
||||
| --- | --- | --- |
|
||||
| Context/references | Project identity, languages, versions, capabilities and paginated references | Authenticated connection; no grant required |
|
||||
| Context/references | Project identity, languages, versions, capabilities and paginated references | Project credential; no acquired task required |
|
||||
| Control | Acquire task and release control | Prior human grant for acquisition; valid task identity for release |
|
||||
| Language | Existing LSP diagnostics/navigation and supported capabilities | Valid project/task identity |
|
||||
| Build | Compile and pack | Valid project/task identity |
|
||||
@@ -373,7 +371,7 @@ mature gameplay library is not a prerequisite.
|
||||
- Pixel-art generation, full-game libraries, audio capture or deep guest introspection.
|
||||
- Shared editing, isolated worktrees, code snapshots/journals/checkpoints, merge/apply, divergence recovery, undo/rollback or automatic commits/clean-tree gates.
|
||||
- Replacing compiler, Packer, LSP, VM or human Debug semantics; a new general-purpose Studio source editor.
|
||||
- Remote MCP, accounts/OAuth, stdio MCP bridge, network runtime discovery or provider-specific connection wizard.
|
||||
- Remote MCP, accounts/OAuth and network runtime discovery. Studio-owned stdio and local Codex preparation are the explicit DEC-0061 additions.
|
||||
- Additional language implementation, persistent operation recovery or automatic task resumption.
|
||||
- Integrated discussion-framework agendas/decisions/plans in the product; those are future work, not this runtime/DEV/MCP contract.
|
||||
|
||||
@@ -390,3 +388,14 @@ Implementation is conformant only when all phase gates hold and:
|
||||
7. Lost operation responses cannot duplicate execution; runtime crash cannot trigger replay or implicit authority release.
|
||||
8. Language context and indexed local references reflect real installed support and work without source checkouts.
|
||||
9. Manual Debug, architecture boundaries, packaging and real-client integration pass their regression gates.
|
||||
|
||||
## Integrated Connection Revision (DEC-0061)
|
||||
|
||||
Connection and authority MUST be displayed separately. Initialization/ping
|
||||
liveness determines connection, while Core determines waiting/working/manual
|
||||
control. A missing descriptor means waiting for access, not proof that Studio is
|
||||
closed. Preparation reports initial client trust/reload requirements without
|
||||
modifying approval policy. Revocation removes published access even before
|
||||
asynchronous worker/runtime cleanup finishes. New grants never restore old task
|
||||
IDs or receipts. Full integrated native-client acceptance belongs to PLN-0140;
|
||||
the prior HTTP acceptance alone is insufficient.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -79,7 +79,7 @@ The main session-restoration store MUST NOT include:
|
||||
- heavy operational output;
|
||||
- recomputable results that do not represent session restoration state.
|
||||
|
||||
Under DEC-0060, automation grants, task/control identities, active runtime sessions and the task-local operation/deduplication registry MUST NOT be persisted or restored through `.studio/state.json` or `.studio/setup.json`. Reopening a project MUST start under manual control. Restoring DEV as the selected workspace is presentation restoration, not permission to resume work. MCP connection credentials MUST NOT be stored in versioned files; they are regenerated on Studio restart. See the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
|
||||
Under DEC-0060, automation grants, task/control identities, active runtime sessions and the task-local operation/deduplication registry MUST NOT be persisted or restored through `.studio/state.json` or `.studio/setup.json`. Reopening a project MUST start under manual control. Restoring DEV as the selected workspace is presentation restoration, not permission to resume work. MCP connection credentials MUST NOT be stored in versioned files; they are regenerated for every project grant and never restored on restart. See the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
|
||||
|
||||
`Project-local activity` and project-local setup may still live under `.studio/`, but they are separate persistence concerns and not part of the main session-restoration store defined here.
|
||||
|
||||
@@ -105,3 +105,36 @@ This specification is complete enough when:
|
||||
- accepted and excluded categories are explicit;
|
||||
- load, restore, save, and fallback timing are explicit;
|
||||
- and the ownership boundary with `StudioProjectSession` is normatively locked.
|
||||
|
||||
## Integrated MCP Discovery (DEC-0061)
|
||||
|
||||
`.studio/setup.json` MUST carry neutral `agentIntegration` intent with
|
||||
`schemaVersion:1`, `enabled` and `clientProfile`. Preserve runtime and editor
|
||||
fields. This intent is configuration, not readiness or authorization. Machine-local
|
||||
resolved client configuration is a separate preparation output.
|
||||
|
||||
The transient descriptor is `.studio/mcp/connection.json`, limited to 16 KiB.
|
||||
Schema v1 requires integral `schemaVersion:1` and nonempty string `instanceId`,
|
||||
`projectRoot`, `endpoint`, `credential`, `catalogFingerprint`. Root MUST match the
|
||||
connector's canonical root. Endpoint MUST be `http://127.0.0.1:<port>/mcp`, with
|
||||
no userinfo, query, fragment or redirect. Grant/task IDs and receipts are forbidden.
|
||||
|
||||
On macOS `.studio/mcp` MUST be owned by the current user with mode 0700;
|
||||
descriptor, lock and temporary files MUST be 0600 before secrets are written.
|
||||
Reject symlinked/unsafe paths and tracked descriptor targets. Add precise ignore
|
||||
rules idempotently without changing unrelated project permissions or files.
|
||||
|
||||
Ownership MUST use an OS-held lock on the stable `publication.lock` inode; do
|
||||
not delete the lock file on ordinary cleanup. A second live publisher fails. A
|
||||
crashed process releases its lock through the OS; a new owner may atomically
|
||||
replace stale content. Write a protected same-directory temporary file and
|
||||
atomically rename it. Cleanup checks both instance and publication generation
|
||||
so an old callback cannot remove newer discovery data.
|
||||
|
||||
Publication is a required grant lifecycle participant, not a swallowed observer.
|
||||
Prepare/publish occur outside the Core monitor; authority activation uses a
|
||||
generation fence. Acquisition cannot succeed until publication and grant both
|
||||
commit. Failure aborts credentials/files and reports a failed grant. Revoke/close
|
||||
invalidate credentials before asynchronous work cleanup, then remove owned
|
||||
publication and release ownership. File cleanup failure MUST NOT prevent runtime
|
||||
cancellation. An already-admitted release response MUST remain deliverable.
|
||||
|
||||
@@ -114,9 +114,9 @@ The JavaFX module MUST NOT directly invoke compiler implementations, `p.packer`,
|
||||
|
||||
Spring Boot MUST be used only by `prometeu-app` for desktop composition and lifecycle. `WebApplicationType.NONE` remains a valid composition mode with an explicitly managed local HTTP adapter. Conformance MUST NOT impose an unconditional absence of a web server that would forbid the DEC-0060 MCP exception.
|
||||
|
||||
The sole accepted HTTP-server use is an in-process MCP Streamable HTTP endpoint at `127.0.0.1:<OS-assigned-port>/mcp`. The application/infrastructure adapter MUST own its transport dependencies and lifecycle. It MUST require a random per-Studio-start token, validate Origin and reject unexpected origins, and stop with Studio. Connection authentication MUST NOT grant project/task authority. The token MUST NOT be stored in versioned files, and restart requires refreshed client configuration.
|
||||
The sole accepted HTTP-server use is an in-process MCP Streamable HTTP endpoint at `127.0.0.1:<OS-assigned-port>/mcp`. The application/infrastructure adapter MUST own its transport dependencies and lifecycle. It MUST require a fresh grant-published project credential, validate project/session scope and Origin, and stop with Studio. Connection authentication MUST NOT grant project/task authority. Credentials MUST NOT be stored in versioned files. Restart requires a fresh human grant, while the stable client configuration remains unchanged.
|
||||
|
||||
This exception does not authorize a web UI, remote binding, general-purpose web application, accounts, OAuth, or a stdio MCP bridge. HTTP/MCP dependencies MUST NOT enter API/Core or the JavaFX adapter. Spring Data, Spring AI and durable event infrastructure remain outside the accepted architecture.
|
||||
This exception does not authorize a web UI, remote binding, general-purpose web application, accounts or OAuth. DEC-0061 explicitly adds the Studio-owned stdio mode and local client preparation. HTTP/MCP dependencies MUST NOT enter API/Core or the JavaFX adapter. Spring Data, Spring AI and durable event infrastructure remain outside the accepted architecture.
|
||||
|
||||
Spring configuration MAY create core services, infrastructure adapters, and a JavaFX composition factory. It MUST NOT use field injection, context lookup, broad service bags, or a replacement static container.
|
||||
|
||||
@@ -178,3 +178,17 @@ The architecture is conformant only when all of the following hold together:
|
||||
- migrating the Studio to Rust, Electron, Tauri, or a parallel rewrite;
|
||||
- redesigning compiler, Packer, LSP, or runtime semantics;
|
||||
- introducing microservices or durable event infrastructure.
|
||||
|
||||
## Integrated MCP Connection Boundary (DEC-0061)
|
||||
|
||||
The same Studio application artifact MUST support `mcp --project` over stdio
|
||||
before desktop composition. It connects to the existing loopback HTTP adapter;
|
||||
it MUST NOT implement separate authority, operations, language services or runtime
|
||||
semantics. Offline catalog loading does not initialize the desktop graph.
|
||||
|
||||
API exposes neutral preparation/readiness and connection-publication lifecycle
|
||||
ports. Core orchestrates save, publication commit/abort, grant, revocation and
|
||||
shutdown through those ports. Application infrastructure owns credentials, file
|
||||
locks/atomic discovery, HTTP identity checks, TOML preparation and managed
|
||||
installation/runtime packaging. JavaFX consumes neutral status and actions only.
|
||||
Filesystem publication MUST NOT run under a long-held authority monitor.
|
||||
|
||||
@@ -84,3 +84,14 @@ Normative reminders:
|
||||
- the Studio backend is exposed through neutral API contracts shared by JavaFX and the local MCP adapter, without duplicated authority or orchestration;
|
||||
- Spring Boot remains the desktop composition root with the narrow DEC-0060 local MCP HTTP exception; Spring Modulith still verifies the JavaFX-free `p.studio.core` boundary;
|
||||
- `p.studio.Container`, `AppContainer`, and the mixed `prometeu-studio` module are not valid final architecture.
|
||||
|
||||
## Integrated MCP connection
|
||||
|
||||
DEC-0061 revises the baseline with Studio-owned `mcp --project` mode, grant-time
|
||||
project discovery, scoped HTTP credentials, one-time scaffold/preparation and a
|
||||
stable installation with bundled Java. Specs 8–11 define the lifecycle and
|
||||
transport boundaries; spec 1 defines project creation. PLN-0140 is complete;
|
||||
automated results and user-confirmed manual acceptance are consolidated in
|
||||
[LSN-0077](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md).
|
||||
The earlier HTTP evidence was not substituted for these gates. The embedded
|
||||
terminal remains separate.
|
||||
|
||||
Reference in New Issue
Block a user