diff --git a/docs/specs/studio/10. DEV and Automation Specification.md b/docs/specs/studio/10. DEV and Automation Specification.md index a256fdb8..bf1dcfef 100644 --- a/docs/specs/studio/10. DEV and Automation Specification.md +++ b/docs/specs/studio/10. DEV and Automation Specification.md @@ -239,6 +239,9 @@ that it uses. Capture/build correlation MUST NOT introduce code snapshots. ## 8. Local MCP Admission and Functional Surface +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:/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 diff --git a/docs/specs/studio/11. MCP Tools and Project Knowledge Contract.md b/docs/specs/studio/11. MCP Tools and Project Knowledge Contract.md new file mode 100644 index 00000000..ffc75335 --- /dev/null +++ b/docs/specs/studio/11. MCP Tools and Project Knowledge Contract.md @@ -0,0 +1,216 @@ +# MCP Tools and Project Knowledge Contract + +## 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 +[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. + +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. +Steps 17–21 connect the functional providers and DEV configuration assistance; +steps 22–28 provide the real runtime gateway and integrated acceptance. + +## 1. Connection Contract + +The app hosts `/mcp` on **127.0.0.1 with an OS-assigned port**, using the JSON +response form of MCP Streamable HTTP, protocol revision `2025-06-18`. The +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 `. 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. + +Native clients may omit `Origin`. If present, it MUST exactly equal the live +endpoint's origin (`http://127.0.0.1:`); `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. + +Initialization assigns a separate random `Mcp-Session-Id`. Subsequent requests +include this header and the negotiated `MCP-Protocol-Version`. The server can +recover the negotiated version from its connection session if the version header +is absent; an explicitly unsupported header returns 400. Missing required +session returns 400; an unknown/closed session returns 404. The client sends +`notifications/initialized` before tools. `ping` is available after initialization. + +POST requires UTF-8 JSON and Accept support for `application/json` and +`text/event-stream`. Responses use JSON, not SSE. GET returns 405. DELETE closes +only the connection session, not project authority. Accepted notifications and +client responses return 202 without a body. Notification/disconnection alone +MUST NOT revoke a task or cancel an operation already returned by operationId. + +The transport bounds incoming bodies to 1 MiB, sessions to 128 and request +handling to a bounded worker queue. Oversized bodies return 413; exhausted +session capacity returns 503. Stalled exchanges close after 15 seconds. These +are HTTP resource protections, **not** task expiration or guest/runtime timeouts. +Build/advance MUST return operation identities promptly. A lost response is +resolved by authorized lookup, not by assuming cancellation or replay. + +These details follow the official MCP [transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), +[lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle) +and [tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) +contracts. Optional SSE, server-initiated requests, sampling, prompts, resource +subscriptions and list-change notifications are not advertised. + +## 2. Identity and Admission + +All tool inputs require `projectRoot`: an absolute filesystem root resolving to +an open project. UI focus never supplies it. Core services resolve the actual +project, including canonical-path/scope checks; syntactic validation does not +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. +- `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. + Revalidate before admission, lookup and deduplication, including read-only LSP. + +No MCP tool grants human permission or simulates pressing the DEV button. +There are no arbitrary-file read/write, shell, Git or publication tools. Editing +uses the external client's native tools within the context's editable scope. + +## 3. v1 Tool Catalog + +Fields below supplement `projectRoot`, and `taskId` where authority is `task`. +Input objects reject undeclared fields. IDs are nonempty opaque strings. + +| Tool | Authority | Additional input | Successful value | +| --- | --- | --- | --- | +| `studio_project_context` | authenticated | none | Project context in section 5 | +| `studio_reference_read` | authenticated | referenceId; optional offset/limit | Indexed reference page | +| `studio_control_acquire` | granted | none | taskId, state=AGENT_WORKING | +| `studio_control_release` | task | none | state=MANUAL, only after ordered cleanup | +| `studio_language_query` | task | operation, parameters | Supported LSP query/proposal result | +| `studio_build_start` | task | clientRequestId | operationId, clientRequestId, state | +| `studio_headless_boot` | task | buildId | sessionId, buildId; boot uses the task's known build | +| `studio_headless_reset` | task | none | Current session/reset state | +| `studio_headless_set_input` | task | input | Current session acknowledgement | +| `studio_headless_clear_input` | task | none | Current session acknowledgement | +| `studio_headless_advance` | task | clientRequestId, frames | operationId, clientRequestId, state | +| `studio_headless_capture` | task | none | Canonical image and metadata in section 6 | +| `studio_headless_state` | task | none | Current session and runtime state | +| `studio_headless_fault` | task | none | fault object or null, preserving structural fault details | +| `studio_headless_shutdown` | task | none | Session shutdown acknowledgement after managed cleanup | +| `studio_operation_get` | task | exactly one of operationId/clientRequestId | State, known progress, typed result/failure | +| `studio_operation_cancel` | task | operationId | operationId, cancellationRequested | + +Boot MUST NOT accept an arbitrary cartridge path. The shared service resolves +buildId to known project artifacts. Runtime limits/capabilities come from the +actual runtime, not fixed MCP promises. Frames is a nonnegative integer (zero +is valid); values beyond effective limits fail rather than being clamped. + +Input is a replacement snapshot: booleans `up/down/left/right/a/b/x/y/l/r/start/ +select/touch`, signed 32-bit `touchX/touchY`. Omitted fields reset to false/zero. +It preserves the runtime's normal sampling/edge semantics, not UI keyboard events. + +Language queries use the capabilities returned by project context. Parameters +may contain URI, zero-based UTF-16 position/range/positions, workspace query, +newName, includeDeclaration or task-local itemId for multi-stage queries. The +provider MUST validate the parameters needed by the selected operation and reject +unsupported operations explicitly. Diagnostics, definitions, references and +symbols reuse the existing project LSP. Other queries/refactoring proposals are +exposed only when supported; returned edits MUST respect project versus read-only +SDK/library scope. No query applies filesystem edits. + +## 4. Result, Error and Operation Contracts + +Successful tools return `isError:false` with structuredContent +`{"status":"ok","value":{...}}`. Domain/admission failures return +`isError:true` with `{"status":"error","error":{"code":"...","message":"..."}}`. +Both include a text content block serializing the same structured data for clients +that do not render structuredContent. Clients use error codes, not parsed prose. + +`AutomationFailure.Code` defines domain codes, including project-not-open, +not-granted, invalid-task, busy, unsupported language/capability, missing +reference/documentation, out-of-scope/read-only scope, missing operation/build/ +runtime session, duplicate-ID parameter conflict, unavailable/incompatible runtime, +missing frame, exceeded limit, not-cancelable and infrastructure failure. +Unknown methods, malformed JSON-RPC and schema-invalid arguments remain protocol +errors (-32601, -32600/-32700 and -32602); unexpected internals use sanitized +-32603 responses, never request bodies, stack traces or credentials. + +Build failure and guest fault are **operation outcomes**, not implicit release. +`TrackedOperation` carries the existing `OperationSnapshot`, clientRequestId, +known progress and either the existing typed build result or runtime outcome. +Unknown requested/completed frame counts are null. Terminal infrastructure +failure/cancellation MUST preserve only known progress. Cancellation acknowledgement +does not assert worker termination or grant manual control. + +The wire receipt flattens operationId/state from the neutral operation snapshot. +Polling additionally returns progress and typed result/failure; incomplete results +are null. Build results retain diagnostics/artifact correlation. Runtime results +retain requested/completed frames and distinguish success, guest fault, +termination, cancellation and infrastructure failure. Captured results include +the same MCP image block used by direct capture. + +`clientRequestId` deduplication is task-local and in-memory. Same ID plus same +effective parameters returns the same operation; changed parameters fail with +CLIENT_REQUEST_CONFLICT. Operation lookup accepts exactly one key. Revoked, +cross-project or old task identities cannot read/cancel cached work. Neither MCP +JSON-RPC IDs nor runtime requestIds replace this identity. Restart never restores +the registry, replays an advance or recovers authorization. + +## 5. Project Knowledge DTOs + +Neutral `ProjectKnowledge.Context` contains projectRoot/projectName, languages, +libraries, editableRoots/readOnlyRoots, indexed references and explicit limitations. +Its source is the project manifest and installed providers, never an AI-only file. + +Each language includes id/primary, separately identified languageVersion, +compilerVersion and sdkVersion, source extensions/roots, real capabilities and +reference IDs. Version has `value` and `source`; unknown value is null with +source `unknown`. Capability support distinguishes SUPPORTED/UNSUPPORTED/UNKNOWN +and can explain a limitation. Unknown declared language MUST NOT fall back to PBS. + +Libraries include identity, known version, roots and whether they belong to the +editable project. External libraries and SDK remain read-only. Reference entries +identify id/title/owner/kind/version; kinds include QUICKSTART, SYNTAX, SEMANTICS, +EXAMPLE, SDK and LIBRARY. Indexed content belongs to its language/SDK owner. + +Reference reads take an opaque ID from that index, not a path or arbitrary URI. +Offset defaults to 0; limit defaults to 4000 and accepts 1–16000 Unicode code +points. A page returns referenceId, offset, total, text and nextOffset (null at +end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the +index. Installed packaging and real provider resolution are steps 17–18. + +## 6. Image Contract + +MCP image content has `type:image`, `mimeType:image/png`, and base64 `data` of +the unchanged `CanonicalCapture.png` bytes. No screenshot, log scraping, temporary +path or network fetch is required. The structured value includes sessionId, +buildId, logicalFrameIndex, frameId, width, height, stridePixels, pixelFormat +`RGBA8888`, mimeType and stale. Stride describes the original framebuffer, not PNG +compression/padding. Logical and render frame counters are independent. + +The adapter MUST NOT invent a frame when none exists or substitute another +session's image. The same neutral capture feeds DEV and MCP. Real runtime +production/cross-language equality remain phase 4 gates; encoding test pixels in +contract tests does not satisfy that integration requirement. + +## 7. Conformance and Delivery Boundary + +Contract tests validate every tool's example, authority level, required project/ +task IDs, invalid types/unknown fields, exclusive operation lookup, input ranges, +pagination, result envelopes, PNG bytes and independent frame identities. +HTTP tests use a real loopback listener/client and exercise initialization, +authentication, Origin, endpoint/method/version handling, tool dispatch, malformed +or oversized input, closure, restart and old-token rejection. Provider doubles +exist only in tests. Composition starts/closes transport with Studio. + +Step 16's production registry is empty until functional handlers are composed; +DEV configuration-copy stays unavailable until step 21. Passing this transport +gate is not the phase 3 or final external-agent acceptance gate. API/Core and +JavaFX MUST NOT import MCP/HTTP implementations; architecture tests enforce it. diff --git a/docs/specs/studio/README.md b/docs/specs/studio/README.md index 1d8ad82b..f3ae8b27 100644 --- a/docs/specs/studio/README.md +++ b/docs/specs/studio/README.md @@ -57,6 +57,7 @@ The current Studio core corpus is: 5. [`8. Project-Local Studio State Specification.md`](8.%20Project-Local%20Studio%20State%20Specification.md) 6. [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md) 7. [`10. DEV and Automation Specification.md`](10.%20DEV%20and%20Automation%20Specification.md) +8. [`11. MCP Tools and Project Knowledge Contract.md`](11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md) ## Reading Order @@ -68,7 +69,8 @@ Recommended order: 4. assets workspace behavior; 5. project-local Studio state behavior; 6. Studio Core, adapter, composition, and external integration boundaries; -7. DEV authority, document handoff, automation operations/captures and phased integration gates. +7. DEV authority, document handoff, automation operations/captures and phased integration gates; +8. MCP transport/tool schemas and project/language knowledge contracts. ## Current Wave Notes diff --git a/prometeu-app/src/main/java/p/studio/app/StudioApplicationConfiguration.java b/prometeu-app/src/main/java/p/studio/app/StudioApplicationConfiguration.java index 36a39a5a..dbfe0ec8 100644 --- a/prometeu-app/src/main/java/p/studio/app/StudioApplicationConfiguration.java +++ b/prometeu-app/src/main/java/p/studio/app/StudioApplicationConfiguration.java @@ -290,6 +290,22 @@ public class StudioApplicationConfiguration { activityHistoryStore); } + @Bean + p.studio.app.mcp.McpToolCatalog mcpToolCatalog(ObjectMapper mapper) { + return new p.studio.app.mcp.McpToolCatalog(mapper); + } + + @Bean + p.studio.app.mcp.McpToolRegistry mcpToolRegistry(p.studio.app.mcp.McpToolCatalog catalog, ObjectMapper mapper) { + // Providers are connected in PLN-0139 steps 17–20. Never advertise placeholders. + return new p.studio.app.mcp.McpToolRegistry(catalog, mapper, java.util.Map.of()); + } + + @Bean(initMethod = "start", destroyMethod = "close") + p.studio.app.mcp.LocalMcpServer localMcpServer(ObjectMapper mapper, p.studio.app.mcp.McpToolRegistry tools) { + return new p.studio.app.mcp.LocalMcpServer(mapper, tools); + } + private static Path resolveDefaultProjectsRoot() { Path cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize(); while (cursor != null) { diff --git a/prometeu-app/src/main/java/p/studio/app/mcp/ContractSchema.java b/prometeu-app/src/main/java/p/studio/app/mcp/ContractSchema.java new file mode 100644 index 00000000..3f781557 --- /dev/null +++ b/prometeu-app/src/main/java/p/studio/app/mcp/ContractSchema.java @@ -0,0 +1,48 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.JsonNode; +import java.util.HashSet; + +/** Validator for the deliberately small JSON Schema vocabulary in our packaged schemas. + * Not a general-purpose JSON Schema engine; never accepts client-supplied schemas. */ +final class ContractSchema { + private ContractSchema() { } + static void validate(JsonNode schema, JsonNode value) { + if (value == null) fail(); + if (schema.has("oneOf")) { + int matches = 0; + for (var branch : schema.get("oneOf")) if (matches(branch, value)) matches++; + if (matches != 1) fail(); + } + if (schema.has("not") && matches(schema.get("not"), value)) fail(); + if (schema.has("const") && !schema.get("const").equals(value)) fail(); + if (schema.has("type")) { + boolean valid = switch (schema.get("type").asText()) { + case "object" -> value.isObject(); + case "array" -> value.isArray(); + case "string" -> value.isTextual(); + case "integer" -> value.isIntegralNumber() && value.canConvertToLong(); + case "boolean" -> value.isBoolean(); + default -> throw new IllegalStateException("Unsupported packaged schema type"); + }; + if (!valid) fail(); + } + if (schema.has("minLength") && value.textValue().codePointCount(0, value.textValue().length()) < schema.get("minLength").intValue()) fail(); + if (schema.has("minimum") && value.longValue() < schema.get("minimum").longValue()) fail(); + if (schema.has("maximum") && value.longValue() > schema.get("maximum").longValue()) fail(); + if (schema.has("required")) for (var key : schema.get("required")) if (!value.has(key.asText())) fail(); + if (schema.has("properties")) { + var allowed = new HashSet(); + schema.get("properties").fields().forEachRemaining(field -> { + allowed.add(field.getKey()); + if (value.has(field.getKey())) validate(field.getValue(), value.get(field.getKey())); + }); + if (!schema.path("additionalProperties").asBoolean(true)) value.fieldNames().forEachRemaining(key -> { if (!allowed.contains(key)) fail(); }); + } + if (schema.has("items")) for (var item : value) validate(schema.get("items"), item); + } + private static boolean matches(JsonNode schema, JsonNode value) { + try { validate(schema, value); return true; } catch (IllegalArgumentException failure) { return false; } + } + private static void fail() { throw new IllegalArgumentException("Arguments do not match the tool contract"); } +} diff --git a/prometeu-app/src/main/java/p/studio/app/mcp/LocalMcpServer.java b/prometeu-app/src/main/java/p/studio/app/mcp/LocalMcpServer.java new file mode 100644 index 00000000..b1b96e78 --- /dev/null +++ b/prometeu-app/src/main/java/p/studio/app/mcp/LocalMcpServer.java @@ -0,0 +1,203 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.core.JsonParser; +import com.fasterxml.jackson.databind.*; +import com.fasterxml.jackson.databind.node.*; +import com.sun.net.httpserver.*; +import java.io.IOException; +import java.net.*; +import java.nio.ByteBuffer; +import java.nio.charset.*; +import java.security.*; +import java.util.*; +import java.util.concurrent.*; +import java.util.concurrent.atomic.AtomicBoolean; + +/** Local MCP transport only. A connection session never represents a project grant or task. */ +public final class LocalMcpServer implements AutoCloseable { + public static final String PROTOCOL_VERSION = "2025-06-18"; + private static final int MAX_BODY_BYTES = 1024 * 1024; + private static final int MAX_CONNECTION_SESSIONS = 128; + private final ObjectMapper mapper; + private final McpToolRegistry tools; + private final Map sessions = new ConcurrentHashMap<>(); + private final SecureRandom random = new SecureRandom(); + private HttpServer server; + private ExecutorService executor; + private ScheduledExecutorService deadlines; + private volatile Connection connection; + + public LocalMcpServer(ObjectMapper mapper, McpToolRegistry tools) { + this.mapper = mapper.copy().enable(JsonParser.Feature.STRICT_DUPLICATE_DETECTION) + .enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); + this.tools = Objects.requireNonNull(tools); + } + + public synchronized void start() throws IOException { + if (server != null) return; + // No configurable bind address: remote and wildcard exposure cannot be enabled accidentally. + var next = HttpServer.create(new InetSocketAddress(InetAddress.getByName("127.0.0.1"), 0), 32); + var workers = new ThreadPoolExecutor(4, 4, 0, TimeUnit.SECONDS, new ArrayBlockingQueue<>(32), + Thread.ofPlatform().daemon().name("studio-mcp-", 1).factory(), new ThreadPoolExecutor.AbortPolicy()); + var timers = Executors.newSingleThreadScheduledExecutor(Thread.ofPlatform().daemon().name("studio-mcp-deadlines").factory()); + try { + connection = new Connection(URI.create("http://127.0.0.1:" + next.getAddress().getPort() + "/mcp"), secret()); + deadlines = timers; + next.createContext("/mcp", this::handle); + next.setExecutor(workers); + next.start(); + executor = workers; server = next; + } catch (RuntimeException failure) { + next.stop(0); workers.shutdownNow(); timers.shutdownNow(); connection = null; + throw failure; + } + } + public Connection connection() { + var current = connection; + if (current == null) throw new IllegalStateException("MCP is not running"); + return current; + } + public synchronized boolean isRunning() { return server != null; } + @Override public synchronized void close() { + if (server == null) return; + connection = null; server.stop(0); server = null; + sessions.clear(); executor.shutdownNow(); deadlines.shutdownNow(); + } + + /** Only explicit connection/configuration consumers may obtain the bearer token; never log it. */ + public static final class Connection { + private final URI endpoint; + private final String token; + private Connection(URI endpoint, String token) { this.endpoint = endpoint; this.token = token; } + public URI endpoint() { return endpoint; } + public String authorizationHeader() { return "Bearer " + token; } + @Override public String toString() { return "LocalMcpConnection[endpoint=" + endpoint + ", credentials=REDACTED]"; } + } + + private void handle(HttpExchange exchange) throws IOException { + // Bounds stalled body reads and transport responses, not guest simulated time or task lifetime. + var timeout = deadlines.schedule(exchange::close, 15, TimeUnit.SECONDS); + try (exchange) { + exchange.getResponseHeaders().set("Cache-Control", "no-store"); + exchange.getResponseHeaders().set("X-Content-Type-Options", "nosniff"); + var current = connection; + if (current == null) { empty(exchange, 503); return; } + if (!"/mcp".equals(exchange.getRequestURI().getRawPath()) || exchange.getRequestURI().getRawQuery() != null) { empty(exchange, 404); return; } + var headers = exchange.getRequestHeaders(); + String origin = single(headers, "Origin"); + String authority = current.endpoint().getRawAuthority(); + if (!exchange.getRemoteAddress().getAddress().isLoopbackAddress() + || !authority.equals(single(headers, "Host")) + || origin != null && !("http://" + authority).equals(origin)) { empty(exchange, 403); return; } + String authorization = single(headers, "Authorization"); + if (authorization == null || !MessageDigest.isEqual(current.authorizationHeader().getBytes(StandardCharsets.UTF_8), authorization.getBytes(StandardCharsets.UTF_8))) { + empty(exchange, 401); return; + } + String version = single(headers, "MCP-Protocol-Version"); + if (version != null && !PROTOCOL_VERSION.equals(version)) { empty(exchange, 400); return; } + String sessionId = single(headers, "Mcp-Session-Id"); + AtomicBoolean initialized = sessionId == null ? null : sessions.get(sessionId); + if (sessionId != null && initialized == null) { empty(exchange, 404); return; } + String method = exchange.getRequestMethod(); + if (method.equals("GET")) { exchange.getResponseHeaders().set("Allow", "POST, DELETE"); empty(exchange, 405); return; } + if (method.equals("DELETE")) { + if (sessionId == null) { empty(exchange, 400); return; } + sessions.remove(sessionId); empty(exchange, 200); return; // No project/task release. + } + if (!method.equals("POST")) { exchange.getResponseHeaders().set("Allow", "POST, DELETE"); empty(exchange, 405); return; } + if (!accepts(headers, "application/json") || !accepts(headers, "text/event-stream")) { empty(exchange, 406); return; } + String contentType = single(headers, "Content-Type"); + if (contentType == null || !contentType.split(";", 2)[0].trim().equalsIgnoreCase("application/json")) { empty(exchange, 415); return; } + byte[] body = exchange.getRequestBody().readNBytes(MAX_BODY_BYTES + 1); + if (body.length > MAX_BODY_BYTES) { empty(exchange, 413); return; } + JsonNode message; + try { + String json = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT) + .onUnmappableCharacter(CodingErrorAction.REPORT).decode(ByteBuffer.wrap(body)).toString(); + message = mapper.readTree(json); + } catch (IOException invalid) { send(exchange, 400, error(NullNode.instance, -32700, "Invalid JSON")); return; } + if (message == null || !message.isObject() || !message.path("jsonrpc").isTextual() || !message.path("jsonrpc").asText().equals("2.0") + || message.has("id") && !(message.get("id").isTextual() || message.get("id").isNumber())) { + send(exchange, 400, error(NullNode.instance, -32600, "Invalid request")); return; + } + JsonNode id = message.path("id"); + String rpc = message.path("method").asText(); + if (!message.path("method").isTextual() || rpc.isBlank() || message.has("result") || message.has("error")) { + // This server issues no requests, but acknowledge well-formed client responses. + if (initialized != null && message.has("id") && !message.has("method") && message.has("result") != message.has("error")) empty(exchange, 202); + else send(exchange, 400, error(id.isMissingNode() ? NullNode.instance : id, -32600, "Invalid request")); + return; + } + JsonNode params = message.has("params") ? message.get("params") : mapper.createObjectNode(); + if (!params.isObject()) { send(exchange, 400, error(id.isMissingNode() ? NullNode.instance : id, -32602, "Invalid parameters")); return; } + if (rpc.equals("initialize")) { + if (id.isMissingNode() || initialized != null || !params.path("protocolVersion").isTextual() + || !params.path("capabilities").isObject() || !params.path("clientInfo").isObject() + || !params.path("clientInfo").path("name").isTextual() || !params.path("clientInfo").path("version").isTextual()) { + send(exchange, 400, error(id.isMissingNode() ? NullNode.instance : id, -32602, "Invalid initialization")); return; + } + synchronized (sessions) { + if (sessions.size() >= MAX_CONNECTION_SESSIONS) { empty(exchange, 503); return; } + sessionId = secret(); sessions.put(sessionId, new AtomicBoolean()); + } + exchange.getResponseHeaders().set("Mcp-Session-Id", sessionId); + var result = mapper.createObjectNode().put("protocolVersion", PROTOCOL_VERSION); + result.putObject("capabilities").putObject("tools").put("listChanged", false); + result.putObject("serverInfo").put("name", "prometeu-studio-mcp").put("version", "1.0"); + result.put("instructions", "Read project context and indexed references. Human grant in DEV precedes acquisition. Edit saved project files with your native tools, never SDK/external libraries. Validate with LSP/build and explicitly release. Studio revocation does not stop your external file writes. Reconnect with new configuration after Studio restart."); + send(exchange, 200, response(id, result)); return; + } + if (initialized == null) { empty(exchange, 400); return; } + if (id.isMissingNode()) { + if (rpc.equals("notifications/initialized")) initialized.set(true); + // Notifications do not implicitly cancel an already returned operationId or release authority. + empty(exchange, 202); return; + } + if (!initialized.get() && !rpc.equals("ping")) { send(exchange, 200, error(id, -32600, "Initialization required")); return; } + try { + JsonNode result = switch (rpc) { + case "ping" -> mapper.createObjectNode(); + case "tools/list" -> { + if (params.has("cursor")) throw new IllegalArgumentException("No further tool page"); + yield mapper.createObjectNode().set("tools", tools.descriptors()); + } + case "tools/call" -> { + if (!params.path("name").isTextual()) throw new IllegalArgumentException("Missing tool name"); + yield tools.call(params.get("name").asText(), params.get("arguments")).wire(); + } + default -> null; + }; + send(exchange, 200, result == null ? error(id, -32601, "Method not found") : response(id, result)); + } catch (IllegalArgumentException invalid) { send(exchange, 200, error(id, -32602, "Invalid tool or parameters")); } + catch (RuntimeException failure) { send(exchange, 200, error(id, -32603, "Internal error")); } + } finally { timeout.cancel(false); } + } + private String secret() { byte[] bytes = new byte[32]; random.nextBytes(bytes); return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes); } + private static String single(Headers headers, String name) { + var values = headers.get(name); + return values == null ? null : values.size() == 1 ? values.getFirst() : ""; + } + private static boolean accepts(Headers headers, String type) { + return headers.getOrDefault("Accept", List.of()).stream().flatMap(s -> Arrays.stream(s.split(","))) + .anyMatch(range -> { + var parts = range.trim().split(";"); + if (!parts[0].trim().equalsIgnoreCase(type)) return false; + for (int index = 1; index < parts.length; index++) { + var parameter = parts[index].trim(); + if (parameter.startsWith("q=")) { + try { double q = Double.parseDouble(parameter.substring(2)); if (!(q > 0 && q <= 1)) return false; } + catch (NumberFormatException invalid) { return false; } + } + } + return true; + }); + } + private ObjectNode response(JsonNode id, JsonNode result) { var value = mapper.createObjectNode().put("jsonrpc", "2.0"); value.set("id", id); value.set("result", result); return value; } + private ObjectNode error(JsonNode id, int code, String message) { var value = mapper.createObjectNode().put("jsonrpc", "2.0"); value.set("id", id); value.putObject("error").put("code", code).put("message", message); return value; } + private void send(HttpExchange exchange, int status, JsonNode value) throws IOException { + byte[] bytes = mapper.writeValueAsBytes(value); + exchange.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8"); + exchange.sendResponseHeaders(status, bytes.length); exchange.getResponseBody().write(bytes); + } + private static void empty(HttpExchange exchange, int status) throws IOException { exchange.sendResponseHeaders(status, -1); } +} diff --git a/prometeu-app/src/main/java/p/studio/app/mcp/McpToolCatalog.java b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolCatalog.java new file mode 100644 index 00000000..559a9665 --- /dev/null +++ b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolCatalog.java @@ -0,0 +1,39 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import java.io.IOException; +import java.util.*; + +/** Packaged v1 contract, not a claim that every provider has been composed. */ +public final class McpToolCatalog { + private final Map definitions; + public McpToolCatalog(ObjectMapper mapper) { + try (var input = getClass().getResourceAsStream("/mcp/studio-tools-v1.json")) { + var root = mapper.readTree(Objects.requireNonNull(input, "Missing MCP contract")); + var loaded = new LinkedHashMap(); + for (var tool : root.required("tools")) { + if (loaded.put(tool.required("name").asText(), tool) != null) throw new IllegalStateException("Duplicate MCP tool"); + ContractSchema.validate(tool.required("inputSchema"), tool.required("exampleArguments")); + } + definitions = Collections.unmodifiableMap(loaded); + } catch (IOException failure) { throw new IllegalStateException("Cannot read packaged MCP contract", failure); } + } + public Set names() { return definitions.keySet(); } + public JsonNode definition(String name) { + var definition = definitions.get(name); + if (definition == null) throw new IllegalArgumentException("Unknown tool"); + return definition.deepCopy(); + } + public ObjectNode descriptor(String name) { + var result = (ObjectNode) definition(name); + result.remove(List.of("authority", "exampleArguments", "exampleValue")); + return result; + } + public void validateArguments(String name, JsonNode arguments) { + ContractSchema.validate(definition(name).required("inputSchema"), arguments); + var root = arguments.required("projectRoot").asText(); + if (!java.nio.file.Path.of(root).isAbsolute()) throw new IllegalArgumentException("projectRoot must be absolute"); + } +} diff --git a/prometeu-app/src/main/java/p/studio/app/mcp/McpToolRegistry.java b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolRegistry.java new file mode 100644 index 00000000..48ce2b35 --- /dev/null +++ b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolRegistry.java @@ -0,0 +1,40 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ArrayNode; +import p.studio.api.automation.AutomationFailure; +import p.studio.api.automation.ControlDeniedException; +import java.util.Map; +import java.util.function.Function; + +/** Immutable adapter dispatch. Services, not this transport, own authority and operations. */ +public final class McpToolRegistry { + private final McpToolCatalog catalog; + private final ObjectMapper mapper; + private final Map> handlers; + public McpToolRegistry(McpToolCatalog catalog, ObjectMapper mapper, Map> handlers) { + this.catalog = catalog; this.mapper = mapper; this.handlers = Map.copyOf(handlers); + handlers.keySet().forEach(catalog::definition); + } + public ArrayNode descriptors() { + var descriptors = mapper.createArrayNode(); + catalog.names().stream().filter(handlers::containsKey).forEach(name -> descriptors.add(catalog.descriptor(name))); + return descriptors; + } + public McpToolResult call(String name, JsonNode arguments) { + var handler = handlers.get(name); + if (handler == null) throw new IllegalArgumentException("Unknown or unavailable tool"); + catalog.validateArguments(name, arguments); + try { return handler.apply(arguments); } + catch (ControlDeniedException denied) { + var code = switch (denied.status()) { + case INVALID_TASK -> AutomationFailure.Code.INVALID_TASK; + case NOT_GRANTED -> AutomationFailure.Code.NOT_GRANTED; + case CLOSED -> AutomationFailure.Code.CLOSED; + default -> AutomationFailure.Code.BUSY; + }; + return McpToolResult.failure(mapper, new AutomationFailure(code, "Project authority rejected the call")); + } + } +} diff --git a/prometeu-app/src/main/java/p/studio/app/mcp/McpToolResult.java b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolResult.java new file mode 100644 index 00000000..611e7374 --- /dev/null +++ b/prometeu-app/src/main/java/p/studio/app/mcp/McpToolResult.java @@ -0,0 +1,41 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import p.studio.api.automation.AutomationFailure; +import p.studio.api.automation.CanonicalCapture; +import java.util.Base64; +import java.util.Objects; + +/** Wire projection only. Images are the same bytes held by the neutral DEV snapshot. */ +public final class McpToolResult { + private final ObjectNode wire; + private McpToolResult(ObjectNode wire) { this.wire = wire; } + public ObjectNode wire() { return wire.deepCopy(); } + public static McpToolResult success(ObjectMapper mapper, ObjectNode value) { + return envelope(mapper, mapper.createObjectNode().put("status", "ok").set("value", value.deepCopy()), false); + } + public static McpToolResult failure(ObjectMapper mapper, AutomationFailure failure) { + var data = mapper.createObjectNode().put("status", "error"); + data.set("error", mapper.valueToTree(failure)); + return envelope(mapper, data, true); + } + public static McpToolResult capture(ObjectMapper mapper, CanonicalCapture capture, boolean stale) { + Objects.requireNonNull(capture); + var metadata = mapper.createObjectNode().put("sessionId", capture.sessionId()).put("buildId", capture.buildId()) + .put("logicalFrameIndex", capture.logicalFrameIndex()).put("frameId", capture.frameId()) + .put("width", capture.width()).put("height", capture.height()).put("stridePixels", capture.stridePixels()) + .put("pixelFormat", "RGBA8888").put("mimeType", "image/png").put("stale", stale); + var result = success(mapper, metadata); + result.wire.withArray("content").addObject().put("type", "image").put("mimeType", "image/png") + .put("data", Base64.getEncoder().encodeToString(capture.png())); + return result; + } + private static McpToolResult envelope(ObjectMapper mapper, JsonNode data, boolean error) { + var wire = mapper.createObjectNode().put("isError", error); + wire.set("structuredContent", data); + wire.putArray("content").addObject().put("type", "text").put("text", data.toString()); + return new McpToolResult(wire); + } +} diff --git a/prometeu-app/src/main/resources/mcp/studio-tools-v1.json b/prometeu-app/src/main/resources/mcp/studio-tools-v1.json new file mode 100644 index 00000000..70e8ef26 --- /dev/null +++ b/prometeu-app/src/main/resources/mcp/studio-tools-v1.json @@ -0,0 +1,1784 @@ +{ + "contractVersion": "1.0", + "tools": [ + { + "name": "studio_project_context", + "authority": "authenticated", + "description": "Read the open project's manifest-driven language, capability, reference and edit-scope context.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + } + }, + "required": [ + "projectRoot" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game" + }, + "exampleValue": { + "projectRoot": "/projects/game", + "projectName": "game", + "languages": [], + "libraries": [], + "editableRoots": [ + "/projects/game" + ], + "readOnlyRoots": [], + "references": [], + "limitations": [ + "Example context; installed provider supplies real support." + ] + } + }, + { + "name": "studio_reference_read", + "authority": "authenticated", + "description": "Read only an indexed local language/SDK reference, paginated in Unicode code points.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "referenceId": { + "type": "string", + "minLength": 1 + }, + "offset": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 16000, + "default": 4000 + } + }, + "required": [ + "projectRoot", + "referenceId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "referenceId": "pbs.quickstart", + "offset": 0, + "limit": 4000 + }, + "exampleValue": { + "referenceId": "pbs.quickstart", + "offset": 0, + "total": 7, + "nextOffset": null, + "text": "Example" + } + }, + { + "name": "studio_control_acquire", + "authority": "granted", + "description": "Acquire the task after explicit human grant in DEV. Authentication alone is insufficient.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + } + }, + "required": [ + "projectRoot" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game" + }, + "exampleValue": { + "taskId": "task-example", + "state": "AGENT_WORKING" + } + }, + { + "name": "studio_control_release", + "authority": "task", + "description": "Invalidate this task, stop managed work and refresh documents before manual return.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "state": "MANUAL" + } + }, + { + "name": "studio_language_query", + "authority": "task", + "description": "Query supported project LSP capabilities after synchronizing saved files. Returns refactoring proposals, never applies edits.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "operation": { + "type": "string", + "minLength": 1 + }, + "parameters": { + "type": "object", + "properties": { + "uri": { + "type": "string", + "minLength": 1 + }, + "position": { + "type": "object", + "properties": { + "line": { + "type": "integer", + "minimum": 0 + }, + "character": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "line", + "character" + ], + "additionalProperties": false + }, + "range": { + "type": "object", + "properties": { + "start": { + "type": "object", + "properties": { + "line": { + "type": "integer", + "minimum": 0 + }, + "character": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "line", + "character" + ], + "additionalProperties": false + }, + "end": { + "type": "object", + "properties": { + "line": { + "type": "integer", + "minimum": 0 + }, + "character": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "line", + "character" + ], + "additionalProperties": false + } + }, + "required": [ + "start", + "end" + ], + "additionalProperties": false + }, + "positions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "line": { + "type": "integer", + "minimum": 0 + }, + "character": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "line", + "character" + ], + "additionalProperties": false + } + }, + "query": { + "type": "string" + }, + "newName": { + "type": "string", + "minLength": 1 + }, + "includeDeclaration": { + "type": "boolean" + }, + "itemId": { + "type": "string", + "minLength": 1 + } + }, + "required": [], + "additionalProperties": false + } + }, + "required": [ + "projectRoot", + "taskId", + "operation", + "parameters" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "operation": "definition", + "parameters": { + "uri": "file:///projects/game/src/main.pbs", + "position": { + "line": 0, + "character": 0 + } + } + }, + "exampleValue": { + "operation": "definition", + "locations": [], + "limitations": [] + } + }, + { + "name": "studio_build_start", + "authority": "task", + "description": "Start saved-source compile and pack; return operationId promptly. Reuse clientRequestId only for identical parameters.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "clientRequestId": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "projectRoot", + "taskId", + "clientRequestId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "clientRequestId": "build-example" + }, + "exampleValue": { + "operationId": "operation-build", + "clientRequestId": "build-example", + "state": "PENDING" + } + }, + { + "name": "studio_headless_boot", + "authority": "task", + "description": "Boot the project's known build artifact in one managed headless session. Never accepts an arbitrary cartridge path.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "buildId": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "projectRoot", + "taskId", + "buildId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "buildId": "build-example" + }, + "exampleValue": { + "sessionId": "runtime-example", + "buildId": "build-example" + } + }, + { + "name": "studio_headless_reset", + "authority": "task", + "description": "reset the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "sessionId": "runtime-example" + } + }, + { + "name": "studio_headless_clear_input", + "authority": "task", + "description": "clear_input the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "sessionId": "runtime-example" + } + }, + { + "name": "studio_headless_capture", + "authority": "task", + "description": "capture the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "sessionId": "runtime-example", + "buildId": "build-example", + "logicalFrameIndex": 9, + "frameId": 4, + "width": 1, + "height": 1, + "stridePixels": 1, + "pixelFormat": "RGBA8888", + "mimeType": "image/png", + "stale": false + } + }, + { + "name": "studio_headless_state", + "authority": "task", + "description": "state the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "sessionId": "runtime-example" + } + }, + { + "name": "studio_headless_fault", + "authority": "task", + "description": "fault the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "fault": null + } + }, + { + "name": "studio_headless_shutdown", + "authority": "task", + "description": "shutdown the task-owned headless session; preserve runtime semantics and task authority.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example" + }, + "exampleValue": { + "sessionId": "runtime-example" + } + }, + { + "name": "studio_headless_set_input", + "authority": "task", + "description": "Replace normalized input. Omitted controls become false/zero, not a partial patch.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "input": { + "type": "object", + "properties": { + "up": { + "type": "boolean", + "default": false + }, + "down": { + "type": "boolean", + "default": false + }, + "left": { + "type": "boolean", + "default": false + }, + "right": { + "type": "boolean", + "default": false + }, + "a": { + "type": "boolean", + "default": false + }, + "b": { + "type": "boolean", + "default": false + }, + "x": { + "type": "boolean", + "default": false + }, + "y": { + "type": "boolean", + "default": false + }, + "l": { + "type": "boolean", + "default": false + }, + "r": { + "type": "boolean", + "default": false + }, + "start": { + "type": "boolean", + "default": false + }, + "select": { + "type": "boolean", + "default": false + }, + "touch": { + "type": "boolean", + "default": false + }, + "touchX": { + "type": "integer", + "minimum": -2147483648, + "maximum": 2147483647, + "default": 0 + }, + "touchY": { + "type": "integer", + "minimum": -2147483648, + "maximum": 2147483647, + "default": 0 + } + }, + "required": [], + "additionalProperties": false + } + }, + "required": [ + "projectRoot", + "taskId", + "input" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "input": { + "a": true, + "touchX": 0, + "touchY": 0 + } + }, + "exampleValue": { + "sessionId": "runtime-example" + } + }, + { + "name": "studio_headless_advance", + "authority": "task", + "description": "Start bounded frame advancement and return operationId promptly; results include the canonical PNG. Do not blindly retry lost responses.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "clientRequestId": { + "type": "string", + "minLength": 1 + }, + "frames": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "projectRoot", + "taskId", + "clientRequestId", + "frames" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "clientRequestId": "advance-example", + "frames": 60 + }, + "exampleValue": { + "operationId": "operation-advance", + "clientRequestId": "advance-example", + "state": "PENDING" + } + }, + { + "name": "studio_operation_get", + "authority": "task", + "description": "Read a task-local operation by exactly one of operationId or clientRequestId, including known progress, typed result and image.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "operationId": { + "type": "string", + "minLength": 1 + }, + "clientRequestId": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "projectRoot", + "taskId" + ], + "additionalProperties": false, + "oneOf": [ + { + "required": [ + "operationId" + ], + "not": { + "required": [ + "clientRequestId" + ] + } + }, + { + "required": [ + "clientRequestId" + ], + "not": { + "required": [ + "operationId" + ] + } + } + ] + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": true, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "operationId": "operation-advance" + }, + "exampleValue": { + "operationId": "operation-advance", + "clientRequestId": "advance-example", + "state": "RUNNING", + "progress": { + "requestedFrames": 60, + "completedFrames": 12 + }, + "result": null + } + }, + { + "name": "studio_operation_cancel", + "authority": "task", + "description": "Request cancellation of an owned operation. Acknowledgement is not worker termination or task release.", + "inputSchema": { + "type": "object", + "properties": { + "projectRoot": { + "type": "string", + "minLength": 1, + "description": "Absolute root of an open project. Never inferred from UI focus." + }, + "taskId": { + "type": "string", + "minLength": 1, + "description": "Current task identity obtained after human grant." + }, + "operationId": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "projectRoot", + "taskId", + "operationId" + ], + "additionalProperties": false + }, + "outputSchema": { + "type": "object", + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "const": "ok" + }, + "value": { + "type": "object" + } + }, + "required": [ + "status", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "const": "error" + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + } + }, + "required": [ + "status", + "error" + ], + "additionalProperties": false + } + ] + }, + "annotations": { + "readOnlyHint": false, + "openWorldHint": false + }, + "exampleArguments": { + "projectRoot": "/projects/game", + "taskId": "task-example", + "operationId": "operation-advance" + }, + "exampleValue": { + "operationId": "operation-advance", + "cancellationRequested": true + } + } + ] +} diff --git a/prometeu-app/src/test/java/p/studio/app/StudioApplicationConfigurationTest.java b/prometeu-app/src/test/java/p/studio/app/StudioApplicationConfigurationTest.java index 897df9b9..d9063b9e 100644 --- a/prometeu-app/src/test/java/p/studio/app/StudioApplicationConfigurationTest.java +++ b/prometeu-app/src/test/java/p/studio/app/StudioApplicationConfigurationTest.java @@ -21,13 +21,17 @@ class StudioApplicationConfigurationTest { .headless(true) .run(); final ExecutorService executor = context.getBean(ExecutorService.class); + final var mcp = context.getBean(p.studio.app.mcp.LocalMcpServer.class); try (context) { assertNotNull(context.getBean(StudioUiFactory.class)); assertNotNull(context.getBean(PackerWorkspaceService.class)); assertNotNull(context.getBean(OperationExecutor.class)); assertFalse(context.getClass().getName().contains("WebServer")); assertFalse(executor.isShutdown()); + assertTrue(mcp.isRunning()); + assertTrue(context.getBean(p.studio.app.mcp.McpToolRegistry.class).descriptors().isEmpty()); } assertTrue(executor.isShutdown()); + assertFalse(mcp.isRunning()); } } diff --git a/prometeu-app/src/test/java/p/studio/app/mcp/LocalMcpServerTest.java b/prometeu-app/src/test/java/p/studio/app/mcp/LocalMcpServerTest.java new file mode 100644 index 00000000..b2c14105 --- /dev/null +++ b/prometeu-app/src/test/java/p/studio/app/mcp/LocalMcpServerTest.java @@ -0,0 +1,133 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.*; +import java.net.URI; +import java.net.http.*; +import java.time.Duration; +import java.util.*; +import java.util.concurrent.atomic.AtomicInteger; +import p.studio.api.automation.*; +import static org.junit.jupiter.api.Assertions.*; + +class LocalMcpServerTest { + final ObjectMapper mapper = new ObjectMapper(); + final HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(3)).build(); + LocalMcpServer server; + String session; + AtomicInteger calls; + + @BeforeEach void start() throws Exception { + calls = new AtomicInteger(); + server = new LocalMcpServer(mapper, new McpToolRegistry(new McpToolCatalog(mapper), mapper, Map.of( + "studio_project_context", args -> { calls.incrementAndGet(); return McpToolResult.success(mapper, mapper.createObjectNode().put("projectRoot", args.get("projectRoot").asText())); }, + "studio_control_acquire", args -> McpToolResult.failure(mapper, new AutomationFailure(AutomationFailure.Code.NOT_GRANTED, "Human grant required"))))); + server.start(); + } + @AfterEach void close() { server.close(); client.close(); } + HttpResponse request(String method, URI uri, String body, String token, String origin, String protocol, String sessionId) throws Exception { + var request = HttpRequest.newBuilder(uri).timeout(Duration.ofSeconds(5)) + .header("Accept", "application/json, text/event-stream").header("Content-Type", "application/json"); + if (token != null) request.header("Authorization", token); + if (origin != null) request.header("Origin", origin); + if (protocol != null) request.header("MCP-Protocol-Version", protocol); + if (sessionId != null) request.header("Mcp-Session-Id", sessionId); + return client.send(request.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body)).build(), HttpResponse.BodyHandlers.ofString()); + } + HttpResponse post(String body) throws Exception { + return request("POST", server.connection().endpoint(), body, server.connection().authorizationHeader(), null, LocalMcpServer.PROTOCOL_VERSION, session); + } + static String init() { return "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"clientInfo\":{\"name\":\"test-client\",\"version\":\"1\"},\"capabilities\":{}}}"; } + void initialize() throws Exception { + var response = post(init()); assertEquals(200, response.statusCode()); + session = response.headers().firstValue("Mcp-Session-Id").orElseThrow(); + assertEquals(LocalMcpServer.PROTOCOL_VERSION, mapper.readTree(response.body()).path("result").path("protocolVersion").asText()); + assertEquals(202, post("{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}").statusCode()); + } + @Test void lifecycleNegotiatesListsAndCallsOnlyActualHandlers() throws Exception { + initialize(); + var listed = mapper.readTree(post("{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}").body()); + assertEquals(2, listed.path("result").path("tools").size()); + var response = post("{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"studio_project_context\",\"arguments\":{\"projectRoot\":\"/project\"}}}"); + assertEquals(200, response.statusCode()); assertEquals(1, calls.get()); + assertEquals("ok", mapper.readTree(response.body()).path("result").path("structuredContent").path("status").asText()); + assertEquals(200, request("DELETE", server.connection().endpoint(), null, server.connection().authorizationHeader(), null, null, session).statusCode()); + assertEquals(404, post("{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"ping\"}").statusCode()); + } + @Test void authAndOriginAreCheckedBeforeProtocolOrTools() throws Exception { + var endpoint = server.connection().endpoint(); var token = server.connection().authorizationHeader(); + assertEquals("127.0.0.1", endpoint.getHost()); assertTrue(endpoint.getPort() > 0); + assertEquals(401, request("POST", endpoint, init(), null, null, null, null).statusCode()); + assertEquals(401, request("POST", endpoint, init(), "Bearer wrong", null, null, null).statusCode()); + for (var origin : List.of("null", "https://evil.example", "http://127.0.0.1:1", "http://localhost:" + endpoint.getPort())) + assertEquals(403, request("POST", endpoint, init(), token, origin, null, null).statusCode()); + assertEquals(200, request("POST", endpoint, init(), token, "http://" + endpoint.getRawAuthority(), null, null).statusCode()); + assertEquals(0, calls.get()); + assertFalse(server.connection().toString().contains(token.substring(7))); + } + @Test void restartChangesCredentialsInvalidatesConnectionsAndDoesNotPersistThem() throws Exception { + initialize(); var old = server.connection(); server.close(); + assertFalse(server.isRunning()); assertThrows(IllegalStateException.class, server::connection); + server.start(); assertFalse(old.authorizationHeader().equals(server.connection().authorizationHeader())); + assertEquals(401, request("POST", server.connection().endpoint(), init(), old.authorizationHeader(), null, null, null).statusCode()); + assertEquals(404, post(init()).statusCode()); + session = null; initialize(); + } + @Test void malformedBodiesVersionsAndToolsCannotReachProviders() throws Exception { + initialize(); + assertEquals(400, post("{not json}").statusCode()); + assertEquals(400, post("[]").statusCode()); + assertEquals(400, post("{\"jsonrpc\":2.0,\"id\":1,\"method\":\"ping\"}").statusCode()); + assertEquals(400, post("{\"jsonrpc\":\"2.0\",\"method\":123}").statusCode()); + assertEquals(400, post("{\"jsonrpc\":\"2.0\",\"id\":1,\"id\":2,\"method\":\"ping\"}").statusCode()); + assertEquals(400, post("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"} {}").statusCode()); + assertEquals(400, request("POST", server.connection().endpoint(), init(), server.connection().authorizationHeader(), null, "unknown", session).statusCode()); + var bad = post("{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"studio_project_context\",\"arguments\":{\"projectRoot\":\"relative\"}}}"); + assertEquals(-32602, mapper.readTree(bad.body()).path("error").path("code").intValue()); assertEquals(0, calls.get()); + assertEquals(413, post(" ".repeat(1024 * 1024 + 1)).statusCode()); + } + @Test void exactEndpointNoSseAndInitializationAreEnforced() throws Exception { + var endpoint = server.connection().endpoint(); var token = server.connection().authorizationHeader(); + assertEquals(400, post("{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/list\"}").statusCode()); + var initialized = post(init()); session = initialized.headers().firstValue("Mcp-Session-Id").orElseThrow(); + assertEquals(-32600, mapper.readTree(post("{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/list\"}").body()).path("error").path("code").asInt()); + assertEquals(405, request("GET", endpoint, null, token, null, null, session).statusCode()); + assertEquals(404, request("POST", URI.create(endpoint + "/nested"), init(), token, null, null, null).statusCode()); + assertEquals(404, request("POST", URI.create(endpoint + "?token=forbidden"), init(), token, null, null, null).statusCode()); + assertEquals(0, calls.get()); + } + @Test void authenticatedConnectionDoesNotGrantControl() throws Exception { + initialize(); + var denied = post("{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"studio_control_acquire\",\"arguments\":{\"projectRoot\":\"/project\"}}}"); + var result = mapper.readTree(denied.body()).path("result"); + assertTrue(result.path("isError").asBoolean()); assertEquals("NOT_GRANTED", result.path("structuredContent").path("error").path("code").asText()); + } + + @Test void hostileHostAndDuplicateOriginAreRejectedEvenWithValidCredentials() throws Exception { + var connection = server.connection(); + try (var socket = new java.net.Socket("127.0.0.1", connection.endpoint().getPort())) { + socket.setSoTimeout(3000); + String request = "POST /mcp HTTP/1.1\r\nHost: evil.example\r\nAuthorization: " + connection.authorizationHeader() + + "\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"; + socket.getOutputStream().write(request.getBytes(java.nio.charset.StandardCharsets.UTF_8)); + var status = new java.io.BufferedReader(new java.io.InputStreamReader(socket.getInputStream())).readLine(); + assertTrue(status.contains("403")); + } + var request = HttpRequest.newBuilder(connection.endpoint()).header("Authorization", connection.authorizationHeader()) + .header("Origin", "http://" + connection.endpoint().getRawAuthority()).header("Origin", "https://evil.example") + .POST(HttpRequest.BodyPublishers.ofString(init())).build(); + assertEquals(403, client.send(request, HttpResponse.BodyHandlers.discarding()).statusCode()); + } + + @Test void contentNegotiationAcceptsWeightedTypesAndRejectsInvalidUtf8() throws Exception { + var connection = server.connection(); + var request = HttpRequest.newBuilder(connection.endpoint()).header("Authorization", connection.authorizationHeader()) + .header("Accept", "application/json;q=1, text/event-stream;q=0.5").header("Content-Type", "application/json") + .POST(HttpRequest.BodyPublishers.ofString(init())).build(); + assertEquals(200, client.send(request, HttpResponse.BodyHandlers.discarding()).statusCode()); + var invalid = HttpRequest.newBuilder(connection.endpoint()).header("Authorization", connection.authorizationHeader()) + .header("Accept", "application/json, text/event-stream").header("Content-Type", "application/json") + .POST(HttpRequest.BodyPublishers.ofByteArray(new byte[]{(byte) 0xc3, (byte) 0x28})).build(); + assertEquals(400, client.send(invalid, HttpResponse.BodyHandlers.discarding()).statusCode()); + } +} diff --git a/prometeu-app/src/test/java/p/studio/app/mcp/McpContractTest.java b/prometeu-app/src/test/java/p/studio/app/mcp/McpContractTest.java new file mode 100644 index 00000000..02746a40 --- /dev/null +++ b/prometeu-app/src/test/java/p/studio/app/mcp/McpContractTest.java @@ -0,0 +1,81 @@ +package p.studio.app.mcp; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import org.junit.jupiter.api.Test; +import p.studio.api.automation.*; +import java.util.*; +import static org.junit.jupiter.api.Assertions.*; + +class McpContractTest { + final ObjectMapper mapper = new ObjectMapper(); + final McpToolCatalog catalog = new McpToolCatalog(mapper); + + @Test void everyToolHasValidExampleAuthorityAndResultEnvelope() { + assertEquals(17, catalog.names().size()); + for (var name : catalog.names()) { + var definition = catalog.definition(name); + catalog.validateArguments(name, definition.get("exampleArguments")); + var result = McpToolResult.success(mapper, (ObjectNode) definition.get("exampleValue")); + ContractSchema.validate(definition.get("outputSchema"), result.wire().get("structuredContent")); + var failure = McpToolResult.failure(mapper, new AutomationFailure(AutomationFailure.Code.INVALID_TASK, "Revoked")); + ContractSchema.validate(definition.get("outputSchema"), failure.wire().get("structuredContent")); + assertTrue(Set.of("authenticated", "granted", "task").contains(definition.get("authority").asText())); + assertEquals(definition.get("authority").asText().equals("task"), definition.get("inputSchema").get("properties").has("taskId")); + assertFalse(catalog.descriptor(name).has("exampleArguments")); + } + } + @Test void missingRootTaskUnexpectedFieldsAndWrongTypesAreRejected() { + for (var name : catalog.names()) { + ObjectNode sample = catalog.definition(name).get("exampleArguments").deepCopy(); + sample.remove("projectRoot"); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments(name, sample)); + sample.put("projectRoot", "relative/root"); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments(name, sample)); + sample.put("projectRoot", "/project").put("shell", "forbidden"); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments(name, sample)); + sample.remove("shell"); sample.put("projectRoot", 12); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments(name, sample)); + if (sample.has("taskId")) { + sample.put("projectRoot", "/project").remove("taskId"); + assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments(name, sample)); + } + } + } + @Test void lookupIsExclusiveAndFrameInputAndPaginationAreBounded() { + ObjectNode lookup = catalog.definition("studio_operation_get").get("exampleArguments").deepCopy(); + lookup.put("clientRequestId", "request"); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_operation_get", lookup)); + lookup.remove(List.of("clientRequestId", "operationId")); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_operation_get", lookup)); + lookup.put("clientRequestId", "request"); catalog.validateArguments("studio_operation_get", lookup); + ObjectNode advance = catalog.definition("studio_headless_advance").get("exampleArguments").deepCopy(); + advance.put("frames", -1); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_headless_advance", advance)); + advance.put("frames", 1.5); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_headless_advance", advance)); + ObjectNode reference = catalog.definition("studio_reference_read").get("exampleArguments").deepCopy(); + reference.put("limit", 0); assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_reference_read", reference)); + ObjectNode input = catalog.definition("studio_headless_set_input").get("exampleArguments").deepCopy(); + ((ObjectNode) input.get("input")).put("touchX", Long.MAX_VALUE); + assertThrows(IllegalArgumentException.class, () -> catalog.validateArguments("studio_headless_set_input", input)); + } + @Test void imageBytesAndMetadataArePreservedWithoutFileTransport() throws Exception { + byte[] png = Base64.getDecoder().decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a9l0AAAAASUVORK5CYII="); + var capture = new CanonicalCapture("session", "build", 123, 7, 1, 1, 1, png); + var wire = McpToolResult.capture(mapper, capture, true).wire(); + assertArrayEquals(png, Base64.getDecoder().decode(wire.get("content").get(1).get("data").asText())); + assertEquals("image/png", wire.get("content").get(1).get("mimeType").asText()); + assertEquals(wire.get("structuredContent").toString(), wire.get("content").get(0).get("text").asText()); + var value = wire.get("structuredContent").get("value"); + assertEquals(123, value.get("logicalFrameIndex").asLong()); assertEquals(7, value.get("frameId").asLong()); + assertTrue(value.get("stale").asBoolean()); assertEquals("RGBA8888", value.get("pixelFormat").asText()); + } + @Test void unavailableHandlersAreNotAdvertisedOrInvoked() { + var registry = new McpToolRegistry(catalog, mapper, Map.of()); + assertTrue(registry.descriptors().isEmpty()); + assertThrows(IllegalArgumentException.class, () -> registry.call("studio_project_context", catalog.definition("studio_project_context").get("exampleArguments"))); + } + @Test void neutralLookupProgressAndReferencesDoNotInventUnknownValues() { + assertThrows(IllegalArgumentException.class, () -> new OperationLookup(null, null)); + assertThrows(IllegalArgumentException.class, () -> new OperationLookup("id", "request")); + assertThrows(IllegalArgumentException.class, () -> new TrackedOperation.Progress(4L, 5L)); + assertNull(new TrackedOperation.Progress(null, null).completedFrames()); + assertFalse(ProjectKnowledge.Version.unknown().known()); + assertNull(ProjectKnowledge.Version.unknown().value()); + assertEquals(1, new ProjectKnowledge.ReferencePage("unicode", 0, 2, 1, "🎮").nextOffset()); + assertThrows(IllegalArgumentException.class, () -> new ProjectKnowledge.ReferencePage("invalid", 0, 1, 1, "ab")); + } +} diff --git a/prometeu-architecture-tests/src/test/java/p/studio/architecture/StudioBoundaryArchTest.java b/prometeu-architecture-tests/src/test/java/p/studio/architecture/StudioBoundaryArchTest.java index 11c8ea44..fbbaa1b1 100644 --- a/prometeu-architecture-tests/src/test/java/p/studio/architecture/StudioBoundaryArchTest.java +++ b/prometeu-architecture-tests/src/test/java/p/studio/architecture/StudioBoundaryArchTest.java @@ -9,6 +9,13 @@ import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses; @AnalyzeClasses(packages = {"p.studio", "p.packer"}, importOptions = ImportOption.DoNotIncludeTests.class) class StudioBoundaryArchTest { + @ArchTest + static final ArchRule automationTransportStaysInTheApp = noClasses() + .that().resideInAnyPackage("p.studio.api..", "p.studio.core..", "p.studio.ui..") + .should().dependOnClassesThat().resideInAnyPackage( + "p.studio.app.mcp..", "com.sun.net.httpserver..", "io.modelcontextprotocol..") + .because("DEC-0060 confines MCP and HTTP transport to application adapters"); + @ArchTest static final ArchRule staticContainerCannotReturn = noClasses() .that().resideInAnyPackage("p.studio..") diff --git a/prometeu-studio-api/src/main/java/p/studio/api/automation/AutomationFailure.java b/prometeu-studio-api/src/main/java/p/studio/api/automation/AutomationFailure.java new file mode 100644 index 00000000..68388ab5 --- /dev/null +++ b/prometeu-studio-api/src/main/java/p/studio/api/automation/AutomationFailure.java @@ -0,0 +1,15 @@ +package p.studio.api.automation; + +import java.util.Objects; + +/** Stable domain failure codes, independent of HTTP status and JSON-RPC errors. */ +public record AutomationFailure(Code code, String message) { + public enum Code { + PROJECT_NOT_OPEN, NOT_GRANTED, INVALID_TASK, BUSY, CLOSED, CLEANUP_FAILED, + UNSUPPORTED_LANGUAGE, UNSUPPORTED_CAPABILITY, REFERENCE_NOT_FOUND, DOCUMENTATION_UNAVAILABLE, + OUTSIDE_PROJECT_SCOPE, READ_ONLY_SCOPE, OPERATION_NOT_FOUND, CLIENT_REQUEST_CONFLICT, + RUNTIME_UNAVAILABLE, RUNTIME_INCOMPATIBLE, SESSION_NOT_FOUND, BUILD_NOT_FOUND, + NO_FRAME_AVAILABLE, LIMIT_EXCEEDED, NOT_CANCELABLE, INFRASTRUCTURE_FAILURE + } + public AutomationFailure { Objects.requireNonNull(code); Objects.requireNonNull(message); } +} diff --git a/prometeu-studio-api/src/main/java/p/studio/api/automation/OperationLookup.java b/prometeu-studio-api/src/main/java/p/studio/api/automation/OperationLookup.java new file mode 100644 index 00000000..f7ddcf82 --- /dev/null +++ b/prometeu-studio-api/src/main/java/p/studio/api/automation/OperationLookup.java @@ -0,0 +1,11 @@ +package p.studio.api.automation; + +/** Exactly one lookup key, always scoped to a separately validated project/task identity. */ +public record OperationLookup(String operationId, String clientRequestId) { + public OperationLookup { + if ((operationId == null) == (clientRequestId == null) + || (operationId != null && operationId.isBlank()) + || (clientRequestId != null && clientRequestId.isBlank())) + throw new IllegalArgumentException("Supply exactly one nonblank operationId or clientRequestId"); + } +} diff --git a/prometeu-studio-api/src/main/java/p/studio/api/automation/ProjectKnowledge.java b/prometeu-studio-api/src/main/java/p/studio/api/automation/ProjectKnowledge.java new file mode 100644 index 00000000..f998ee84 --- /dev/null +++ b/prometeu-studio-api/src/main/java/p/studio/api/automation/ProjectKnowledge.java @@ -0,0 +1,63 @@ +package p.studio.api.automation; + +import java.nio.file.Path; +import java.util.List; +import java.util.Objects; + +/** Installed, owner-maintained knowledge. Authentication belongs to the calling adapter. */ +public interface ProjectKnowledge { + Context context(Path openProjectRoot); + ReferencePage readReference(Path openProjectRoot, String referenceId, int offset, int limit); + + record Version(String value, String source) { + public Version { + Objects.requireNonNull(source, "source"); + if (source.isBlank() || value != null && value.isBlank()) throw new IllegalArgumentException("Blank version provenance"); + } + public boolean known() { return value != null; } + public static Version unknown() { return new Version(null, "unknown"); } + } + enum Support { SUPPORTED, UNSUPPORTED, UNKNOWN } + record Capability(String name, Support support, String limitation) { + public Capability { Objects.requireNonNull(name); Objects.requireNonNull(support); } + } + record Language(String id, boolean primary, Version languageVersion, Version compilerVersion, + Version sdkVersion, List extensions, List sourceRoots, + List capabilities, List referenceIds) { + public Language { + Objects.requireNonNull(id); Objects.requireNonNull(languageVersion); + Objects.requireNonNull(compilerVersion); Objects.requireNonNull(sdkVersion); + extensions = List.copyOf(extensions); sourceRoots = List.copyOf(sourceRoots); + capabilities = List.copyOf(capabilities); referenceIds = List.copyOf(referenceIds); + } + } + enum ReferenceKind { QUICKSTART, SYNTAX, SEMANTICS, EXAMPLE, SDK, LIBRARY } + record Reference(String id, String title, String owner, ReferenceKind kind, Version version) { + public Reference { Objects.requireNonNull(id); Objects.requireNonNull(title); Objects.requireNonNull(owner); Objects.requireNonNull(kind); Objects.requireNonNull(version); } + } + record Library(String id, Version version, List roots, boolean editable) { + public Library { Objects.requireNonNull(id); Objects.requireNonNull(version); roots = List.copyOf(roots); } + } + record Context(Path projectRoot, String projectName, List languages, + List libraries, List editableRoots, List readOnlyRoots, + List references, List limitations) { + public Context { + projectRoot = Objects.requireNonNull(projectRoot).toAbsolutePath().normalize(); + Objects.requireNonNull(projectName); + languages = List.copyOf(languages); libraries = List.copyOf(libraries); + editableRoots = List.copyOf(editableRoots); readOnlyRoots = List.copyOf(readOnlyRoots); + references = List.copyOf(references); limitations = List.copyOf(limitations); + } + } + /** Offsets and limits count Unicode code points, not bytes or UTF-16 code units. */ + record ReferencePage(String referenceId, int offset, int total, Integer nextOffset, String text) { + public ReferencePage { + Objects.requireNonNull(referenceId); Objects.requireNonNull(text); + int count = text.codePointCount(0, text.length()); + if (offset < 0 || total < offset || count > total - offset + || (nextOffset == null && count != total - offset) + || (nextOffset != null && (nextOffset != offset + count || nextOffset >= total || count == 0))) + throw new IllegalArgumentException("Invalid reference page"); + } + } +} diff --git a/prometeu-studio-api/src/main/java/p/studio/api/automation/TrackedOperation.java b/prometeu-studio-api/src/main/java/p/studio/api/automation/TrackedOperation.java new file mode 100644 index 00000000..6d04e1de --- /dev/null +++ b/prometeu-studio-api/src/main/java/p/studio/api/automation/TrackedOperation.java @@ -0,0 +1,23 @@ +package p.studio.api.automation; + +import p.studio.api.operation.OperationSnapshot; +import p.studio.api.shipper.ShipperPrepareResult; +import java.util.Objects; + +/** An operation outcome is not task authority. Null result means it is not available yet. */ +public record TrackedOperation(OperationSnapshot operation, String clientRequestId, Progress progress, + String buildId, ShipperPrepareResult buildResult, AutomationOutcome runtimeResult, AutomationFailure failure) { + public TrackedOperation { + Objects.requireNonNull(operation); Objects.requireNonNull(clientRequestId); Objects.requireNonNull(progress); + if (clientRequestId.isBlank()) throw new IllegalArgumentException("Empty client request identity"); + if (buildResult != null && runtimeResult != null) throw new IllegalArgumentException("Mixed operation result kinds"); + } + /** Unknown progress stays null. Never infer completion from cancellation acknowledgement. */ + public record Progress(Long requestedFrames, Long completedFrames) { + public Progress { + if (requestedFrames != null && requestedFrames < 0 || completedFrames != null && completedFrames < 0 + || requestedFrames != null && completedFrames != null && completedFrames > requestedFrames) + throw new IllegalArgumentException("Invalid frame progress"); + } + } +}