add MCP tool contracts and authenticated local HTTP transport

This commit is contained in:
2026-09-29 07:55:29 +01:00
parent e3c3b2cbb7
commit 9f61f9c07d
18 changed files with 2730 additions and 1 deletions
@@ -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); }
}
@@ -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");
}
}
@@ -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<String> extensions, List<Path> sourceRoots,
List<Capability> capabilities, List<String> 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<Path> roots, boolean editable) {
public Library { Objects.requireNonNull(id); Objects.requireNonNull(version); roots = List.copyOf(roots); }
}
record Context(Path projectRoot, String projectName, List<Language> languages,
List<Library> libraries, List<Path> editableRoots, List<Path> readOnlyRoots,
List<Reference> references, List<String> 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");
}
}
}
@@ -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");
}
}
}