Files
VCCPlusOSS/platforms/macos/Tools/MCP/MCPProjectTools.h
T

217 lines
23 KiB
Objective-C

// SPDX-License-Identifier: GPL-3.0-or-later
#import "MCPGuestTools.h"
static NSArray<NSDictionary *> *MCPProjectTools(BOOL assembly, BOOL interactive, BOOL customMake) {
NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@128};
NSDictionary *requestID = @{@"type":@"string", @"minLength":@1, @"maxLength":assembly ? @64 : @128,
@"description":assembly ? @"Unique request ID, up to 64 UTF-8 bytes." : @"Unique request ID, up to 128 UTF-8 bytes."};
NSDictionary *replacement = @{@"type":@"string", @"minLength":assembly ? @0 : @1, @"maxLength":assembly ? @1024 : @512,
@"description":assembly ? @"One assembly line of up to 1024 UTF-8 bytes." : @"One ASCII C source line of up to 512 bytes, with printable characters or tabs."};
NSDictionary *path = @{@"type":@"string", @"minLength":@1, @"maxLength":@512};
NSDictionary *revision = @{@"type":@"integer", @"minimum":@0};
NSDictionary *scope = @{@"project_id":identifier, @"revision":revision};
NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, BOOL) =
^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, BOOL readOnly) {
return @{@"name":name, @"description":description,
@"inputSchema":@{@"type":@"object", @"properties":fields,
@"required":[fields.allKeys sortedArrayUsingSelector:@selector(compare:)], @"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@(readOnly), @"openWorldHint":@NO}};
};
NSDictionary *build = tool(@"build_project", @"Start a build of the selected revision. Reuse the request ID on retry. Poll get_build with the returned build ID.",
@{@"project_id":identifier, @"revision":revision, @"request_id":requestID}, NO);
if (customMake) {
NSMutableDictionary *fields = [build[@"inputSchema"][@"properties"] mutableCopy];
fields[@"action"] = @{@"type":@"string", @"enum":@[@"build", @"disk"],
@"description":@"Optional declared project action. Defaults to build. Arbitrary Make targets are not accepted."};
fields[@"configuration"] = @{@"type":@"string", @"minLength":@1, @"maxLength":@128,
@"description":@"Optional configuration name from get_capabilities. Defaults to the selected workspace configuration."};
NSMutableDictionary *schema = [build[@"inputSchema"] mutableCopy];
schema[@"properties"] = fields; // Preserve the three original required arguments.
NSMutableDictionary *customBuild = [build mutableCopy];
customBuild[@"inputSchema"] = schema;
customBuild[@"description"] = @"Build the selected revision with the explicitly approved project Make recipe. Use only advertised actions and configurations. Reuse request_id only for the identical revision, action and configuration; poll get_build.";
build = customBuild;
}
NSString *capabilities = assembly ? @"Identify the shared assembly project, target processor, files and revision."
: customMake ? @"Identify the shared CMOC project, files, revision, approved Make recipe identity, declared actions, targets and configurations."
: @"Identify the shared CMOC project, files and revision.";
NSArray *tools = @[tool(@"get_capabilities", capabilities, @{}, YES),
tool(@"read_project_file", @"Read one file named in the shared project manifest.", @{@"project_id":identifier, @"path":path}, YES),
build,
tool(@"get_build", @"Read the build state, compiler or assembler diagnostics and linked result.", @{@"build_id":identifier}, YES),
tool(@"propose_fix", @"Submit one full replacement line for native review. Use the current revision and 1-based file line. Reuse the request ID on retry.",
@{@"project_id":identifier, @"revision":revision, @"path":path, @"line_number":@{@"type":@"integer",@"minimum":@1},
@"replacement":replacement, @"request_id":requestID}, NO),
tool(@"get_proposal", @"Read the user's decision on this proposed edit.", @{@"proposal_id":identifier}, YES),
tool(@"get_run", @"Read guest execution or poll an accepted asynchronous playtest startup. A starting/cancelling result includes phase and busy; ready includes its receipt; failed includes phase and error. Use the project_id/revision from start_playtest.", scope, YES)];
if (!interactive) return tools;
NSDictionary *keyRequestID = @{@"type":@"string", @"minLength":@1, @"maxLength":@64};
return [tools arrayByAddingObjectsFromArray:@[
tool(@"read_screen_text", @"Read the hardware text screen of the locally started, active compiled game. Live access ends on return to BASIC.",
@{@"run_id":identifier}, YES),
tool(@"send_keys", @"Send one letter, digit or space to the running game. Reuse request_id on retry. Up to 64 inputs per run.",
@{@"run_id":identifier, @"request_id":keyRequestID, @"keys":MCPGuestKeySchema(NO)}, NO)]];
}
// Added only when the running app explicitly advertises project refresh.
static NSArray<NSDictionary *> *MCPProjectRefreshTools() {
NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@128};
NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, NSArray *, BOOL) =
^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, NSArray *required, BOOL readOnly) {
return @{@"name":name, @"description":description,
@"inputSchema":@{@"type":@"object", @"properties":fields, @"required":required, @"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@(readOnly), @"openWorldHint":@NO}};
};
return @[
tool(@"refresh_project", @"Refresh captured project inputs after external edits. Existing authorized source changes can be accepted automatically; recipe, permissions, support scope or newly shared files require native review. Reuse request_id only for the identical request. Returns refresh_id and pending, approved, rejected or unchanged status; never executes a recipe.",
@{@"project_id":identifier, @"request_id":identifier, @"revision":@{@"type":@"integer", @"minimum":@0}},
@[@"project_id", @"request_id", @"revision"], NO),
tool(@"get_project_refresh", @"Poll a project refresh and its native review decision. Remains available while changed inputs block builds and runs.",
@{@"project_id":identifier, @"refresh_id":identifier}, @[@"project_id", @"refresh_id"], YES),
tool(@"read_project_inputs", @"Read the approved canonical input manifest: relative paths, roles, SHA-256 and permissions, plus current refresh status. This does not expose unapproved file contents or host paths. Page using offset and limit.",
@{@"project_id":identifier, @"offset":@{@"type":@"integer", @"minimum":@0},
@"limit":@{@"type":@"integer", @"minimum":@1, @"maximum":@256}}, @[@"project_id"], YES)
];
}
// Added only by a freshly exported diagnostics-aware C grant.
static NSArray<NSDictionary *> *MCPBuildDiagnosticTools() {
return @[@{@"name":@"get_build_log", @"description":@"Read a retained, redacted build log in bounded UTF-8 byte pages. Use next_offset for the next page; logs disclose original process/retention truncation. This reads only a build belonging to this connection, never a host path.",
@"inputSchema":@{@"type":@"object", @"properties":@{
@"build_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@128},
@"offset":@{@"type":@"integer",@"minimum":@0},
@"limit":@{@"type":@"integer",@"minimum":@1,@"maximum":@32768}},
@"required":@[@"build_id"],@"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@YES,@"openWorldHint":@NO}}];
}
static NSArray<NSDictionary *> *MCPPlaytestAudioTools() {
return @[@{@"name":@"capture_playtest_audio", @"description":@"Advance an owned disposable guest for 1 to 120 emulated fields and return its direct audio as PCM16 stereo WAV. Leaves the guest paused; verified stops can shorten the interval. Uses no microphone or personal emulator audio. Reuse request_id on retry to return the same clip without execution. Maximum 16 clips and 4 MiB retained WAV per run across boots; a maximum-clip allowance must remain before capture. Receipts include actual field interval, boot/run/artifact identity, sample count and SHA-256.",
@"inputSchema":@{@"type":@"object", @"properties":@{
@"run_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64},
@"request_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64},
@"fields":@{@"type":@"integer",@"minimum":@1,@"maximum":@120}},
@"required":@[@"run_id",@"request_id",@"fields"],@"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@NO,@"openWorldHint":@NO}}];
}
// Fresh C owned-playtest grants only; never an arbitrary memory-read interface.
static NSArray<NSDictionary *> *MCPPlaytestCallContextTools() {
NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@64};
return @[@{@"name":@"get_call_context", @"description":@"Read bounded call context for a verified stopped owned disposable C run using its current snapshot. Returns only verified caller evidence; unsupported or ambiguous context is reported unavailable. Does not execute the guest or accept memory addresses.",
@"inputSchema":@{@"type":@"object", @"properties":@{@"run_id":identifier, @"snapshot_id":identifier},
@"required":@[@"run_id", @"snapshot_id"], @"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@YES, @"openWorldHint":@NO}}];
}
// Fresh reviewed media-aware C playtest grants only. The two insertion fields
// are action-specific in discovery as well as helper/host validation.
static NSArray<NSDictionary *> *MCPPlaytestMediaTools() {
NSDictionary *identifier = @{ @"type":@"string", @"minLength":@1, @"maxLength":@64 };
NSDictionary *mediaID = @{ @"type":@"string", @"minLength":@1, @"maxLength":@64,
@"pattern":@"^[A-Za-z0-9_-]{1,64}$", @"description":@"Opaque ID from list_playtest_media; never a host path." };
NSDictionary *sha = @{ @"type":@"string", @"minLength":@64, @"maxLength":@64,
@"pattern":@"^[0-9a-f]{64}$", @"description":@"Exact current lowercase SHA-256 from the selected media listing." };
NSDictionary *listProperties = @{ @"project_id":identifier, @"revision":@{ @"type":@"integer", @"minimum":@0 },
@"artifact_id":identifier, @"run_id":identifier };
NSDictionary *insertProperties = @{ @"run_id":identifier, @"request_id":identifier,
@"action":@{ @"type":@"string", @"enum":@[ @"insert" ] }, @"media_id":mediaID, @"media_sha256":sha };
NSDictionary *ejectProperties = @{ @"run_id":identifier, @"request_id":identifier,
@"action":@{ @"type":@"string", @"enum":@[ @"eject" ] } };
NSMutableDictionary *exchangeProperties = [insertProperties mutableCopy];
exchangeProperties[@"action"] = @{ @"type":@"string", @"enum":@[ @"insert", @"eject" ] };
return @[
@{ @"name":@"list_playtest_media", @"description":@"List reviewed, hash-bound floppy media and compatible retained choices for the exact current project revision and build artifact. Optional run_id selects the current owned run's writable copies and their current hashes, mounted state and retention status. Listing does not advance or modify a guest. IDs are opaque; no host paths are exposed or accepted. Additional disk products must be declared in the reviewed project.",
@"inputSchema":@{ @"type":@"object", @"properties":listProperties,
@"required":@[ @"project_id", @"revision", @"artifact_id" ], @"additionalProperties":@NO },
@"annotations":@{ @"readOnlyHint":@YES, @"openWorldHint":@NO } },
@{ @"name":@"exchange_playtest_media", @"description":@"Insert or eject FD0 in a paused owned disposable run while its floppy controller is idle. Insert requires media_id and exact media_sha256 from that run's listing; eject forbids both. Uses only reviewed artifact-bound private writable disks, preserving every disk across swaps and restart and retaining all disks when the run stops. A successful exchange neither resets nor advances the guest; receipts identify old/new media, hashes, dirty/retained state and clock. Failed exchange preserves the mounted disk and data. Reuse request_id only for the identical action and selection; changed plans conflict. No arbitrary paths, personal media, memory or register writes.",
@"inputSchema":@{ @"type":@"object", @"properties":exchangeProperties,
@"required":@[ @"run_id", @"request_id", @"action" ], @"additionalProperties":@NO,
@"oneOf":@[
@{ @"type":@"object", @"properties":insertProperties,
@"required":@[ @"run_id", @"request_id", @"action", @"media_id", @"media_sha256" ], @"additionalProperties":@NO },
@{ @"type":@"object", @"properties":ejectProperties,
@"required":@[ @"run_id", @"request_id", @"action" ], @"additionalProperties":@NO } ] },
@"annotations":@{ @"readOnlyHint":@NO, @"idempotentHint":@YES, @"openWorldHint":@NO } }
];
}
// Available only through an explicit native owned-playtest connection grant.
static NSArray<NSDictionary *> *MCPPlaytestTools(BOOL processorSelection = NO, BOOL joystickInput = NO, BOOL mediaExchange = NO) {
NSDictionary *id = @{@"type":@"string",@"minLength":@1,@"maxLength":@64};
NSDictionary *functionName = @{@"type":@"string",@"minLength":@1,@"maxLength":@1023};
NSDictionary *sha256 = @{@"type":@"string",@"minLength":@64,@"maxLength":@64,@"pattern":@"^[0-9a-f]{64}$",
@"description":@"Exact lowercase SHA-256 from the retained test-disk receipt."};
NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, NSArray *, BOOL) =
^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, NSArray *required, BOOL readOnly) {
return @{@"name":name,@"description":description,@"inputSchema":@{@"type":@"object",@"properties":fields,
@"required":required,@"additionalProperties":@NO},@"annotations":@{@"readOnlyHint":@(readOnly),@"openWorldHint":@NO}};
};
NSDictionary *stopKind = @{@"type":@"string", @"enum":@[@"c_line", @"function_entry"], @"default":@"c_line",
@"description":@"Optional stop mode. c_line requires a compiler-verified C statement; function_entry uses a verified object/linker function entry and may have no C source line."};
NSDictionary *step = @{@"type":@"object",@"properties":@{
@"keys":@{@"type":@"array",@"items":@{@"type":@"string",@"enum":@[@"a",@"b",@"c",@"d",@"e",@"f",@"g",@"h",@"i",@"j",@"k",@"l",@"m",@"n",@"o",@"p",@"q",@"r",@"s",@"t",@"u",@"v",@"w",@"x",@"y",@"z",@"0",@"1",@"2",@"3",@"4",@"5",@"6",@"7",@"8",@"9",@"up",@"down",@"left",@"backspace",@"right",@"space",@"period",@"enter",@"clear",@"break",@"alt",@"control",@"f1",@"f2",@"shift"]},@"maxItems":@8,@"uniqueItems":@YES},
@"fields":@{@"type":@"integer",@"minimum":@1,@"maximum":@600}},
@"required":@[@"keys",@"fields"],@"additionalProperties":@NO};
if (joystickInput) {
NSMutableDictionary *properties = [step[@"properties"] mutableCopy];
NSDictionary *axis = @{@"type":@"integer",@"minimum":@0,@"maximum":@16383};
NSDictionary *joystick = @{@"type":@"object",@"properties":@{
@"port":@{@"type":@"string",@"enum":@[@"right",@"left"]}, @"x":axis, @"y":axis,
@"buttons":@{@"type":@"array",@"items":@{@"type":@"string",@"enum":@[@"fire1",@"fire2"]},@"maxItems":@2,@"uniqueItems":@YES}},
@"required":@[@"port",@"x",@"y",@"buttons"],@"additionalProperties":@NO};
properties[@"joysticks"] = @{@"type":@"array",@"items":joystick,@"maxItems":@2,@"uniqueItems":@YES,
@"description":@"Complete standard analog port states for this step. At most one entry per named port. Axes 0..16383, center 8191; X increases right, Y down. Missing ports center and release; omitted joysticks is keyboard-only with neutral ports."};
NSMutableDictionary *updatedStep = [step mutableCopy]; updatedStep[@"properties"] = properties; step = updatedStep;
}
NSMutableArray *tools = [@[
tool(@"start_playtest",@"Accept asynchronous startup of a disposable 512 KB MC6809 disk run of the exact current artifact. Returns a reserved run_id and starting status immediately; poll get_run(project_id, revision) until ready or failed, then use capture_playtest for an image. stop_playtest can cancel the reserved run_id during preparation or boot. No transport request waits for full startup. Personal session and media are preserved. Optional stop_function names a verified function. stop_kind defaults to c_line; function_entry stops at its verified object/linker entry without inventing a C line. stop_kind requires stop_function. To resume a retained writable test disk, supply both retained_disk_id and its exact prior receipt retained_disk_sha256; no host paths are accepted. Omit both for a fresh artifact disk. Reuse request_id on retry.",
@{@"project_id":id,@"revision":@{@"type":@"integer",@"minimum":@0},@"artifact_id":id,@"request_id":id,@"stop_function":functionName,@"stop_kind":stopKind,@"retained_disk_id":id,@"retained_disk_sha256":sha256},
@[@"project_id",@"revision",@"artifact_id",@"request_id"],NO),
tool(@"list_playtest_disks",@"List retained writable test disks recorded for the current shared project. Use a returned retained_disk_id and exact SHA-256 receipt with start_playtest. Older unscoped disks are not listed; a legacy resume requires its prior run ID and exact disk hash and reports legacy provenance. No host paths are exposed or accepted.",
@{@"project_id":id},@[@"project_id"],YES),
tool(@"playtest_input",@"Send held physical-key chords for bounded emulated video fields in the owned run (600 per step, 3600 per request, 216000 per run, 16 boots). Empty keys releases all keys. Resumes a verified stop. Reuse request_id only for an identical plan.",
@{@"run_id":id,@"request_id":id,@"steps":@{@"type":@"array",@"items":step,@"minItems":@1,@"maxItems":@64}},@[@"run_id",@"request_id",@"steps"],NO),
tool(@"playtest_debug",@"Pause, continue, instruction-step, or arm a verified named function in the owned run. stop_at requires function; optional stop_kind defaults to c_line, or function_entry uses its verified object/linker entry without claiming a C statement. Other actions do not accept function or stop_kind. No registers or guest memory can be written.",
@{@"run_id":id,@"request_id":id,@"action":@{@"type":@"string",@"enum":@[@"pause",@"continue",@"step",@"stop_at"]},@"function":functionName,@"stop_kind":stopKind},@[@"run_id",@"request_id",@"action"],NO),
tool(@"capture_playtest",@"Capture the owned run's framebuffer, field clock and disk identity without advancing it.",@{@"run_id":id},@[@"run_id"],YES),
tool(@"capture_playtest_graphics",@"Capture a read-only graphics preview at one paused owned-machine state. Returns current display-buffer physical identity and its PNG; optional buffer_id selects one framebuffer declared by this artifact's verified manifest for a second PNG, including a bounded current_gime canvas. Uses current video registers, not a historical presented frame. Accepts no addresses and never advances or edits the guest.",
@{@"run_id":id,@"buffer_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64,@"pattern":@"^[A-Za-z0-9_-]{1,64}$"}},@[@"run_id"],YES),
tool(@"restart_playtest",@"Cold restart only the owned run, retaining its writable test disk and repeating its declared boot commands. Reuse request_id on retry.",@{@"run_id":id,@"request_id":id},@[@"run_id",@"request_id"],NO),
tool(@"stop_playtest",@"Cancel a pending startup by its reserved run_id, or stop the owned worker and retain its test disk in VCC Plus development results. Pending cancellation is polled with get_run until busy is false; a late worker is cleaned up before replacement. Personal media remain untouched.",@{@"run_id":id,@"request_id":id},@[@"run_id",@"request_id"],NO)
] mutableCopy];
if (joystickInput) {
NSMutableDictionary *input = [tools[2] mutableCopy];
input[@"description"] = @"Apply complete keyboard and standard analog joystick states for bounded emulated fields in this owned run. At most two distinct ports, axis range 0..16383, center 8191, fire1/fire2. Missing ports center/release. Inputs release after the plan, interrupted stops or errors. Limits: 64 steps, 600 fields per step, 3600 per request; budgets/ownership remain enforced. Reuse request_id only for an identical plan. Receipts include actual input and bounded per-step input_trace; no guest memory/register writes.";
tools[2] = input;
[tools addObject:tool(@"get_playtest_input", @"Read the owned worker's actual current keyboard-held flag and two standard analog port snapshots without advancing, changing input or consuming execution budget. Completed plans report neutral released input; input_trace in the input receipt describes applied step states.", @{@"run_id":id}, @[@"run_id"], YES)];
}
if (mediaExchange) {
NSMutableDictionary *start = [tools[0] mutableCopy];
NSMutableDictionary *schema = [start[@"inputSchema"] mutableCopy];
NSMutableDictionary *properties = [schema[@"properties"] mutableCopy];
properties[@"retained_media"] = @{ @"type":@"array", @"minItems":@1, @"maxItems":@8, @"uniqueItems":@YES,
@"description":@"Optional retained writable copies for distinct additional media_id values from the current artifact listing. Omit for fresh additional disks; primary disk resumption still uses retained_disk_id and retained_disk_sha256. Exact per-disk provenance and hashes are rechecked before startup.",
@"items":@{ @"type":@"object", @"properties":@{
@"media_id":@{ @"type":@"string", @"minLength":@1, @"maxLength":@64, @"pattern":@"^[A-Za-z0-9_-]{1,64}$" },
@"retained_disk_id":id, @"retained_disk_sha256":sha256 },
@"required":@[ @"media_id", @"retained_disk_id", @"retained_disk_sha256" ], @"additionalProperties":@NO } };
schema[@"properties"] = properties; start[@"inputSchema"] = schema;
start[@"description"] = [start[@"description"] stringByAppendingString:@" Fresh media-aware grants may additionally resume declared disks through retained_media; each run keeps independent writable copies. stop_playtest retains all of those copies, including unmounted media."];
tools[0] = start;
}
if (!processorSelection) return tools;
NSMutableArray *updated = [tools mutableCopy];
NSMutableDictionary *start = [tools[0] mutableCopy];
NSMutableDictionary *schema = [start[@"inputSchema"] mutableCopy];
NSMutableDictionary *properties = [schema[@"properties"] mutableCopy];
properties[@"processor"] = @{@"type":@"string",@"enum":@[@"MC6809",@"HD6309"],@"default":@"MC6809",
@"description":@"Guest CPU, independent of host architecture. Omission selects MC6809. HD6309 starts in reset emulation mode; the guest controls MD/native mode. Restart retains this CPU. A changed CPU requires a new start request_id."};
schema[@"properties"] = properties; start[@"inputSchema"] = schema;
start[@"description"] = [start[@"description"] stringByReplacingOccurrencesOfString:@"512 KB MC6809 disk run"
withString:@"512 KB disk run using processor MC6809 (default) or HD6309"];
updated[0] = start;
return updated;
}