connect DEV to live MCP configuration and verify tool conformance

This commit is contained in:
2026-09-29 10:36:50 +01:00
parent 20bbbd26bd
commit 9592c9b274
16 changed files with 417 additions and 18 deletions
@@ -281,13 +281,13 @@ public class StudioApplicationConfiguration {
TiledAssetService tiledAssetService,
SceneBankWorkflow sceneBankWorkflow,
WindowStateStore windowStateStore,
ProjectActivityHistoryStore activityHistoryStore) {
ProjectActivityHistoryStore activityHistoryStore, p.studio.api.automation.AgentConnectionGuide connectionGuide) {
return new StudioUiFactory(projectCatalog, knownProjects, languageCatalog, projectSessionFactory,
executionControllerFactory, projectWorkspaceInitializer, studioExecutor, i18n, theme, eventBus, shipper,
assetCatalog, assetCommands, assetPacking, assetDetails, assetCreationCatalog, assetMetadataService,
assetWorkspaceStorage, assetCapacityPolicy, bankCompositionSessionFactory, assetColorSchemaFactory,
tiledAssetService, sceneBankWorkflow, windowStateStore,
activityHistoryStore);
activityHistoryStore, connectionGuide);
}
@Bean
@@ -335,6 +335,12 @@ public class StudioApplicationConfiguration {
return new p.studio.app.mcp.LocalMcpServer(mapper, tools);
}
@Bean
p.studio.api.automation.AgentConnectionGuide connectionGuide(p.studio.app.mcp.LocalMcpServer server,
p.studio.core.project.ProjectAccessRegistry projects, ObjectMapper mapper) {
return new p.studio.app.mcp.McpConnectionGuide(server, projects, mapper);
}
private static Path resolveDefaultProjectsRoot() {
Path cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
while (cursor != null) {
@@ -56,6 +56,7 @@ public final class StudioUiFactory {
private final SceneBankWorkflow sceneBankWorkflow;
private final WindowStateStore windowStateStore;
private final ProjectActivityHistoryStore activityHistoryStore;
private final p.studio.api.automation.AgentConnectionGuide connectionGuide;
public StudioUiFactory(
ProjectCatalog projectCatalog,
@@ -82,7 +83,8 @@ public final class StudioUiFactory {
TiledAssetService tiledAssetService,
SceneBankWorkflow sceneBankWorkflow,
WindowStateStore windowStateStore,
ProjectActivityHistoryStore activityHistoryStore) {
ProjectActivityHistoryStore activityHistoryStore, p.studio.api.automation.AgentConnectionGuide connectionGuide) {
this.connectionGuide = Objects.requireNonNull(connectionGuide);
this.projectCatalog = Objects.requireNonNull(projectCatalog, "projectCatalog");
this.knownProjects = Objects.requireNonNull(knownProjects, "knownProjects");
this.languageCatalog = Objects.requireNonNull(languageCatalog, "languageCatalog");
@@ -116,6 +118,6 @@ public final class StudioUiFactory {
assetCatalog, assetCommands, assetPacking, assetDetails, assetCreationCatalog, assetMetadataService,
assetWorkspaceStorage, assetCapacityPolicy, bankCompositionSessionFactory, assetColorSchemaFactory,
tiledAssetService, sceneBankWorkflow, windowStateStore,
activityHistoryStore);
activityHistoryStore, connectionGuide);
}
}
@@ -26,6 +26,15 @@ public final class LocalMcpServer implements AutoCloseable {
private ExecutorService executor;
private ScheduledExecutorService deadlines;
private volatile Connection connection;
private final java.util.List<Runnable> connectionListeners = new CopyOnWriteArrayList<>();
public p.studio.api.operation.OperationSubscription onConnectionChanged(Runnable listener) {
connectionListeners.add(listener); notifyConnectionListener(listener);
return () -> connectionListeners.remove(listener);
}
private static void notifyConnectionListener(Runnable listener) {
try { listener.run(); } catch (RuntimeException ignored) { /* Observation cannot change lifecycle. */ }
}
public LocalMcpServer(ObjectMapper mapper, McpToolRegistry tools) {
this.mapper = mapper.copy().enable(JsonParser.Feature.STRICT_DUPLICATE_DETECTION)
@@ -47,6 +56,7 @@ public final class LocalMcpServer implements AutoCloseable {
next.setExecutor(workers);
next.start();
executor = workers; server = next;
connectionListeners.forEach(LocalMcpServer::notifyConnectionListener);
} catch (RuntimeException failure) {
next.stop(0); workers.shutdownNow(); timers.shutdownNow(); connection = null;
throw failure;
@@ -62,6 +72,7 @@ public final class LocalMcpServer implements AutoCloseable {
if (server == null) return;
connection = null; server.stop(0); server = null;
sessions.clear(); executor.shutdownNow(); deadlines.shutdownNow();
connectionListeners.forEach(LocalMcpServer::notifyConnectionListener);
}
/** Only explicit connection/configuration consumers may obtain the bearer token; never log it. */
@@ -144,7 +155,7 @@ public final class LocalMcpServer implements AutoCloseable {
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.");
result.put("instructions", McpConnectionGuide.INSTRUCTIONS);
send(exchange, 200, response(id, result)); return;
}
if (initialized == null) { empty(exchange, 400); return; }
@@ -0,0 +1,50 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.AgentConnectionGuide;
import p.studio.api.operation.OperationSubscription;
import p.studio.core.project.ProjectAccessRegistry;
import java.nio.file.Path;
import java.util.Optional;
/** Builds a provider-neutral connection descriptor from the live server, only on explicit export. */
public final class McpConnectionGuide implements AgentConnectionGuide {
public static final String INSTRUCTIONS = """
Configure your external coding client's MCP connection using the url and Authorization header below.
This is a provider-neutral descriptor, not a provider-specific configuration file.
Keep the token private; do not commit this descriptor, write it into project files or include it in logs.
Connect and list available tools. Read studio_project_context for the explicit projectRoot and consult
studio_reference_read for the declared languages, SDK and libraries before editing as needed.
Do not assume PBS or another language when support/documentation is missing; report the limitation.
Wait for the developer to grant control in DEV, then call studio_control_acquire. Copying or connecting
does not grant permission. Use the returned taskId for all work and operate only on this project.
Edit saved project files with your native tools; SDK and external libraries are read-only.
Validate saved changes with studio_language_query and studio_build_start. Poll studio_operation_get.
Supply a unique clientRequestId per intended build/advance. Recover lost responses by lookup using
clientRequestId; do not blindly repeat frame advancement with a new ID. Cancellation acknowledgement
is not worker termination. Use only tools/capabilities actually advertised by this running Studio.
Observe headless images/state when those tools are available, and explicitly studio_control_release
when finished. On revocation stop external edits too: Studio cannot stop your native file writes.
Existing edits are preserved. Git/review/recovery remain the developer's responsibility.
Recopy and update your client's connection after Studio restart: endpoint and token are ephemeral.
""";
private final LocalMcpServer server;
private final ProjectAccessRegistry projects;
private final ObjectMapper mapper;
public McpConnectionGuide(LocalMcpServer server, ProjectAccessRegistry projects, ObjectMapper mapper) {
this.server = server; this.projects = projects; this.mapper = mapper;
}
@Override public Optional<String> endpoint() {
try { return Optional.of(server.connection().endpoint().toString()); }
catch (IllegalStateException unavailable) { return Optional.empty(); }
}
@Override public String configuration(Path root) {
Path canonical = projects.requireOpenRoot(root);
var live = server.connection();
var value = mapper.createObjectNode().put("transport", "streamable-http").put("url", live.endpoint().toString());
value.putObject("headers").put("Authorization", live.authorizationHeader());
value.put("projectRoot", canonical.toString()).put("instructions", INSTRUCTIONS);
return value.toPrettyString();
}
@Override public OperationSubscription subscribe(Runnable changed) { return server.onConnectionChanged(changed); }
}
@@ -120,6 +120,61 @@ class DevDesktopTest {
});
}
@Test void copiesLiveConnectionWithoutGrantOrCredentialDisplayAndRefreshesAvailability() throws Exception {
var mapper = new com.fasterxml.jackson.databind.ObjectMapper();
var projects = new p.studio.core.project.ProjectAccessRegistry();
var savedClipboard = new java.util.HashMap<javafx.scene.input.DataFormat, Object>();
var copied = new java.util.concurrent.atomic.AtomicReference<String>();
var view = new DevWorkspace[1]; var stage = new Stage[1];
try (var pool = Executors.newSingleThreadExecutor();
var server = new p.studio.app.mcp.LocalMcpServer(mapper, new p.studio.app.mcp.McpToolRegistry(
new p.studio.app.mcp.McpToolCatalog(mapper), mapper, java.util.Map.of()))) {
var authority = new DefaultAutomationSession(root, new ExecutorOperationExecutor(pool));
var registration = projects.register(root, authority::enterManual, () -> !authority.snapshot().closed(), authority);
var guide = new p.studio.app.mcp.McpConnectionGuide(server, projects, mapper);
server.start();
try {
fx(() -> {
var clipboard = javafx.scene.input.Clipboard.getSystemClipboard();
clipboard.getContentTypes().forEach(type -> savedClipboard.put(type, clipboard.getContent(type)));
var project = new ProjectReference("Connection smoke", "1", "pbs", 1, ProjectTarget.Game, root);
view[0] = new DevWorkspace(project, authority, new I18nService(), new StudioEventBus(), guide);
stage[0] = new Stage(); stage[0].setScene(new Scene(new VBox(view[0].rootNode()), 1050, 800)); stage[0].show();
view[0].load();
var button = (Button) view[0].rootNode().lookup("#dev-mcp-config"); assertFalse(button.isDisabled());
button.fire(); copied.set(clipboard.getString());
assertEquals(ControlState.MANUAL, authority.snapshot().state());
assertEquals(server.connection().endpoint().toString(), ((Label) view[0].rootNode().lookup("#dev-mcp-endpoint")).getText());
assertTrue(view[0].rootNode().lookupAll(".label").stream().filter(n -> n instanceof Label)
.noneMatch(n -> ((Label) n).getText().contains(server.connection().authorizationHeader())));
});
var first = mapper.readTree(copied.get());
assertTrue(server.connection().authorizationHeader().equals(first.path("headers").path("Authorization").asText()));
assertEquals(root.toRealPath().toString(), first.path("projectRoot").asText());
server.close();
fx(() -> assertTrue(((Button) view[0].rootNode().lookup("#dev-mcp-config")).isDisabled()));
server.start(); authority.grant(false).toCompletableFuture().join();
fx(() -> {
var button = (Button) view[0].rootNode().lookup("#dev-mcp-config"); assertFalse(button.isDisabled());
button.fire(); copied.set(javafx.scene.input.Clipboard.getSystemClipboard().getString());
assertEquals(ControlState.WAITING_FOR_AGENT, authority.snapshot().state());
});
var next = mapper.readTree(copied.get());
assertFalse(first.path("headers").equals(next.path("headers")));
assertTrue(server.connection().authorizationHeader().equals(next.path("headers").path("Authorization").asText()));
authority.closeAsync().toCompletableFuture().get(5, TimeUnit.SECONDS);
fx(() -> assertTrue(((Button) view[0].rootNode().lookup("#dev-mcp-config")).isDisabled()));
} finally {
fx(() -> {
if (view[0] != null) view[0].unLoad();
if (stage[0] != null) stage[0].close();
javafx.scene.input.Clipboard.getSystemClipboard().setContent(savedClipboard);
});
authority.closeAsync().toCompletableFuture().get(5, TimeUnit.SECONDS); registration.close();
}
}
}
@Test void lockedUiBlocksMutationActionsButNotReadOnlyActions() throws Exception {
fx(() -> {
var root = new VBox(); var mutate = new Button("write"); var inspect = new Button("inspect");
@@ -0,0 +1,52 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.core.project.ProjectAccessRegistry;
import p.studio.core.session.DefaultAutomationSession;
import p.studio.app.operation.ExecutorOperationExecutor;
import p.studio.api.automation.*;
import java.nio.file.Path;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.*;
class McpConnectionGuideTest {
@TempDir Path root;
@Test void exportsLiveProjectDescriptorWithoutGrantAndTracksRestartWithoutRetainingSecrets() throws Exception {
var mapper = new ObjectMapper(); var projects = new ProjectAccessRegistry();
try (var workers = Executors.newSingleThreadExecutor();
var server = new LocalMcpServer(mapper, new McpToolRegistry(new McpToolCatalog(mapper), mapper, Map.of()))) {
var authority = new DefaultAutomationSession(root, new ExecutorOperationExecutor(workers));
var registration = projects.register(root, authority::enterManual, () -> !authority.snapshot().closed(), authority);
var guide = new McpConnectionGuide(server, projects, mapper);
assertTrue(guide.endpoint().isEmpty());
assertThrows(IllegalStateException.class, () -> guide.configuration(root));
var notifications = new AtomicInteger();
var subscription = guide.subscribe(notifications::incrementAndGet);
server.start(); assertEquals(2, notifications.get());
var descriptor = mapper.readTree(guide.configuration(root));
assertEquals(server.connection().endpoint().toString(), descriptor.path("url").asText());
assertEquals(root.toRealPath().toString(), descriptor.path("projectRoot").asText());
// Do not put bearer credentials into assertion diagnostics.
assertTrue(server.connection().authorizationHeader().equals(descriptor.path("headers").path("Authorization").asText()));
assertFalse(guide.toString().contains(descriptor.path("headers").path("Authorization").asText()));
assertEquals(ControlState.MANUAL, authority.snapshot().state());
assertNull(authority.snapshot().task());
for (var instruction : List.of("studio_project_context", "studio_reference_read", "studio_control_acquire", "studio_control_release",
"studio_language_query", "studio_build_start", "clientRequestId", "read-only", "restart", "native file writes"))
assertTrue(descriptor.path("instructions").asText().contains(instruction));
var old = server.connection(); server.close(); assertEquals(3, notifications.get()); assertTrue(guide.endpoint().isEmpty());
server.start(); assertEquals(4, notifications.get());
var fresh = mapper.readTree(guide.configuration(root));
assertTrue(fresh.path("headers").path("Authorization").asText().equals(server.connection().authorizationHeader()));
assertFalse(fresh.path("headers").path("Authorization").asText().equals(old.authorizationHeader()));
assertThrows(AutomationException.class, () -> guide.configuration(root.resolve("unopened")));
authority.closeAsync().toCompletableFuture().join();
assertThrows(AutomationException.class, () -> guide.configuration(root));
registration.close(); subscription.close(); server.close(); assertEquals(4, notifications.get());
}
}
}
@@ -238,6 +238,97 @@ class McpTaskToolsTest {
}
}
}
@Test void allToolGroupsConformOverHttpWithRealLspAndTestOnlyRuntime() throws Exception {
Path source = Files.createDirectories(root.resolve("src")).resolve("main.pbs");
Files.writeString(source, "fn main() -> int { return 1; }\n");
var lifecycle = new p.studio.lsp.services.LspServerLifecycleImpl();
var lsp = new p.studio.app.lsp.LspLifecycleAdapter(lifecycle);
var project = catalog.openProject(root); lsp.boot(project);
var knowledge = new p.studio.app.compiler.CompilerProjectKnowledge(access, catalog, mapper);
var language = new p.studio.core.language.TaskLanguageQueries(access,
new p.studio.app.lsp.AutomationLspQueries(lifecycle, catalog, knowledge, mapper));
var handlers = new LinkedHashMap<>(McpTaskTools.handlers(service, mapper, true));
handlers.putAll(McpProjectKnowledgeTools.handlers(knowledge, mapper));
handlers.putAll(McpLanguageTools.handlers(language, mapper));
try (var server = new LocalMcpServer(mapper, new McpToolRegistry(new McpToolCatalog(mapper), mapper, handlers));
var client = java.net.http.HttpClient.newHttpClient()) {
server.start();
var unauthorized = java.net.http.HttpRequest.newBuilder(server.connection().endpoint()).POST(java.net.http.HttpRequest.BodyPublishers.ofString("{}"))
.timeout(java.time.Duration.ofSeconds(5)).build();
assertEquals(401, client.send(unauthorized, java.net.http.HttpResponse.BodyHandlers.discarding()).statusCode());
String first = connect(client, server), second = connect(client, server);
var list = mapper.createObjectNode().put("jsonrpc", "2.0").put("id", 1).put("method", "tools/list");
assertEquals(17, mapper.readTree(post(client, server, first, list).body()).path("result").path("tools").size());
var context = value(httpCall(client, server, first, "studio_project_context", rootOnly()));
assertTrue(context.path("languages").toString().contains("pbs"));
value(httpCall(client, server, first, "studio_reference_read", rootOnly().put("referenceId", "pbs:quickstart").put("limit", 100)));
error("NOT_GRANTED", httpCall(client, server, first, "studio_control_acquire", rootOnly()));
error("INVALID_TASK", httpCall(client, server, first, "studio_build_start", args().put("taskId", "missing").put("clientRequestId", "denied")));
session.grant(false).toCompletableFuture().join();
var a = workers.submit(() -> httpCall(client, server, first, "studio_control_acquire", rootOnly()));
var b = workers.submit(() -> httpCall(client, server, second, "studio_control_acquire", rootOnly()));
var results = List.of(a.get(5, TimeUnit.SECONDS), b.get(5, TimeUnit.SECONDS));
assertEquals(1, results.stream().filter(r -> !r.path("isError").asBoolean()).count());
task = value(results.stream().filter(r -> !r.path("isError").asBoolean()).findFirst().orElseThrow()).path("taskId").asText();
var query = args().put("operation", "diagnostics"); query.putObject("parameters").put("uri", source.toUri().toString());
value(httpCall(client, server, first, "studio_language_query", query));
Files.writeString(source, "fn main( {");
assertFalse(value(httpCall(client, server, first, "studio_language_query", query)).path("result").isEmpty());
Files.writeString(source, "fn main() -> int { return 2; }\n");
value(httpCall(client, server, first, "studio_language_query", query));
httpCall(client, server, first, "studio_build_start", args().put("clientRequestId", "conformance-build"));
var build = httpCompleted(client, server, first, "conformance-build");
value(httpCall(client, server, first, "studio_headless_boot", args().put("buildId", build.path("result").path("buildId").asText())));
for (var op : List.of("reset", "clear_input", "state", "fault")) value(httpCall(client, server, first, "studio_headless_" + op, args()));
value(httpCall(client, server, first, "studio_headless_set_input", args().set("input", mapper.createObjectNode().put("a", true))));
value(httpCall(client, server, first, "studio_headless_advance", args().put("clientRequestId", "conformance-advance").put("frames", 5)));
var advanced = httpCompleted(client, server, first, "conformance-advance");
assertEquals("SUCCEEDED", advanced.path("result").path("status").asText());
var captured = httpCall(client, server, first, "studio_headless_capture", args()); value(captured);
assertArrayEquals(session.snapshot().capture().png(), Base64.getDecoder().decode(captured.path("content").get(1).path("data").asText()));
var deleted = java.net.http.HttpRequest.newBuilder(server.connection().endpoint()).DELETE()
.header("Authorization", server.connection().authorizationHeader()).header("Mcp-Session-Id", first).build();
assertEquals(200, client.send(deleted, java.net.http.HttpResponse.BodyHandlers.discarding()).statusCode());
assertEquals(ControlState.AGENT_WORKING, session.snapshot().state());
String reconnected = connect(client, server);
assertEquals(advanced.path("operationId"), value(httpCall(client, server, reconnected, "studio_operation_get", args().put("clientRequestId", "conformance-advance"))).path("operationId"));
runtime.kind = AutomationOutcome.Kind.GUEST_FAULT;
value(httpCall(client, server, reconnected, "studio_headless_advance", args().put("clientRequestId", "guest").put("frames", 2)));
assertEquals("GUEST_FAULT", httpCompleted(client, server, reconnected, "guest").path("result").path("status").asText());
value(httpCall(client, server, reconnected, "studio_operation_cancel", args().put("operationId", advanced.path("operationId").asText())));
runtime.hold = true;
String pending = value(httpCall(client, server, reconnected, "studio_headless_advance",
args().put("clientRequestId", "cancel-over-http").put("frames", 50))).path("operationId").asText();
assertTrue(value(httpCall(client, server, reconnected, "studio_operation_cancel", args().put("operationId", pending)))
.path("cancellationRequested").asBoolean());
runtime.gate.countDown();
assertEquals("CANCELLED", httpCompleted(client, server, reconnected, "cancel-over-http").path("state").asText());
value(httpCall(client, server, reconnected, "studio_headless_shutdown", args()));
value(httpCall(client, server, reconnected, "studio_control_release", args()));
error("INVALID_TASK", httpCall(client, server, reconnected, "studio_operation_get", args().put("clientRequestId", "conformance-advance")));
session.grant(false).toCompletableFuture().join();
task = value(httpCall(client, server, reconnected, "studio_control_acquire", rootOnly())).path("taskId").asText();
session.reclaim().toCompletableFuture().join();
error("INVALID_TASK", httpCall(client, server, reconnected, "studio_build_start", args().put("clientRequestId", "late")));
} finally { lsp.shutdown(project); }
}
String connect(java.net.http.HttpClient client, LocalMcpServer server) throws Exception {
var initialize = mapper.createObjectNode().put("jsonrpc", "2.0").put("id", 1).put("method", "initialize");
var params = initialize.putObject("params").put("protocolVersion", "2025-06-18");
params.putObject("capabilities"); params.putObject("clientInfo").put("name", "conformance-test").put("version", "1");
String connection = post(client, server, null, initialize).headers().firstValue("Mcp-Session-Id").orElseThrow();
assertEquals(202, post(client, server, connection, mapper.createObjectNode().put("jsonrpc", "2.0").put("method", "notifications/initialized")).statusCode());
return connection;
}
JsonNode httpCompleted(java.net.http.HttpClient client, LocalMcpServer server, String connection, String request) throws Exception {
long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5);
do {
var result = value(httpCall(client, server, connection, "studio_operation_get", args().put("clientRequestId", request)));
if (result.path("workerTerminated").asBoolean()) return result;
Thread.sleep(5);
} while (System.nanoTime() < deadline);
throw new AssertionError("Operation did not terminate");
}
JsonNode httpCall(java.net.http.HttpClient client, LocalMcpServer server, String connection, String name, ObjectNode arguments) throws Exception {
var request = mapper.createObjectNode().put("jsonrpc", "2.0").put("id", UUID.randomUUID().toString()).put("method", "tools/call");
request.putObject("params").put("name", name).set("arguments", arguments);