c64bridge 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/.github/prompts/steer.prompt.md +55 -0
  2. package/AGENTS.md +9 -7
  3. package/README.md +139 -95
  4. package/data/embeddings_asm.json +1 -1
  5. package/data/embeddings_basic.json +1 -1
  6. package/data/embeddings_hardware.json +1 -1
  7. package/data/embeddings_mixed.json +1 -1
  8. package/data/embeddings_other.json +1 -1
  9. package/data/graphics/petscii-style-guide.md +4 -4
  10. package/data/graphics/sprite-charset-best-practices.md +9 -9
  11. package/data/vice/vice-binary-monitor-spec.md +921 -0
  12. package/dist/.tsbuildinfo +1 -1
  13. package/dist/device.js +86 -10
  14. package/dist/mcp-server.js +1 -1
  15. package/dist/prompts/registry.js +27 -25
  16. package/dist/rag/knowledgeIndex.js +112 -79
  17. package/dist/rag/resourceUris.js +93 -0
  18. package/dist/tools/audio.js +11 -11
  19. package/dist/tools/debug.js +1 -1
  20. package/dist/tools/developer.js +13 -13
  21. package/dist/tools/graphics.js +10 -10
  22. package/dist/tools/machineControl.js +5 -5
  23. package/dist/tools/memory.js +19 -11
  24. package/dist/tools/meta/index.js +1 -1
  25. package/dist/tools/printer.js +11 -12
  26. package/dist/tools/programRunners.js +16 -16
  27. package/dist/tools/rag.js +9 -9
  28. package/dist/tools/registry/config.js +1 -1
  29. package/dist/tools/registry/disk.js +1 -1
  30. package/dist/tools/registry/drive.js +1 -1
  31. package/dist/tools/registry/extract.js +1 -1
  32. package/dist/tools/registry/graphics.js +1 -1
  33. package/dist/tools/registry/memory.js +1 -1
  34. package/dist/tools/registry/platform.js +1 -1
  35. package/dist/tools/registry/printer.js +1 -1
  36. package/dist/tools/registry/program.js +1 -1
  37. package/dist/tools/registry/rag.js +1 -1
  38. package/dist/tools/registry/sound.js +1 -1
  39. package/dist/tools/registry/stream.js +1 -1
  40. package/dist/tools/registry/system.js +1 -1
  41. package/dist/tools/storage.js +15 -15
  42. package/dist/tools/streaming.js +3 -3
  43. package/dist/tools/types.js +41 -4
  44. package/dist/tools/vice.js +2 -5
  45. package/dist/vice/process.js +79 -2
  46. package/dist/vice/readiness.js +35 -0
  47. package/dist/vice/smokeOptions.js +44 -0
  48. package/dist/viceRunner.js +2 -0
  49. package/doc/plans/prompts/README.md +7 -7
  50. package/mcp/prompts.json +42 -59
  51. package/mcp/protocol-examples.json +2 -2
  52. package/mcp/resources.json +179 -166
  53. package/mcp/schemas/c64_config.schema.json +109 -326
  54. package/mcp/schemas/c64_debug.schema.json +158 -337
  55. package/mcp/schemas/c64_disk.schema.json +180 -262
  56. package/mcp/schemas/c64_drive.schema.json +31 -111
  57. package/mcp/schemas/c64_extract.schema.json +193 -291
  58. package/mcp/schemas/c64_graphics.schema.json +208 -308
  59. package/mcp/schemas/c64_memory.schema.json +94 -144
  60. package/mcp/schemas/c64_printer.schema.json +151 -205
  61. package/mcp/schemas/c64_program.schema.json +229 -367
  62. package/mcp/schemas/c64_rag.schema.json +25 -59
  63. package/mcp/schemas/c64_select_backend.schema.json +19 -26
  64. package/mcp/schemas/c64_sound.schema.json +346 -622
  65. package/mcp/schemas/c64_stream.schema.json +25 -54
  66. package/mcp/schemas/c64_system.schema.json +79 -212
  67. package/mcp/schemas/c64_vice.schema.json +24 -55
  68. package/mcp/server.json +1 -1
  69. package/mcp/tools.json +1935 -3443
  70. package/mcp.json +3 -3
  71. package/package.json +17 -14
  72. package/scripts/fetch-external-sources.mjs +1 -2
  73. package/scripts/run-coverage.mjs +26 -1
  74. package/scripts/run-tests.mjs +2 -2
  75. package/scripts/run-tests.ts +273 -52
  76. package/scripts/update-readme.ts +54 -2
  77. package/server.json +2 -2
@@ -1,61 +1,32 @@
1
1
  {
2
2
  "type": "object",
3
- "description": "Streaming operations available via the c64_stream tool.",
4
- "oneOf": [
5
- {
6
- "type": "object",
7
- "description": "Start an Ultimate streaming session toward a host:port target.",
8
- "properties": {
9
- "stream": {
10
- "type": "string",
11
- "description": "Stream type to control (video/audio/debug).",
12
- "enum": [
13
- "video",
14
- "audio",
15
- "debug"
16
- ]
17
- },
18
- "target": {
19
- "type": "string",
20
- "description": "Destination host:port or UDP target understood by the firmware.",
21
- "minLength": 3
22
- },
23
- "op": {
24
- "const": "start"
25
- }
26
- },
27
- "required": [
28
- "stream",
29
- "target",
30
- "op"
3
+ "properties": {
4
+ "op": {
5
+ "type": "string",
6
+ "enum": [
7
+ "start",
8
+ "stop"
31
9
  ],
32
- "additionalProperties": false
10
+ "description": "Selects the operation."
33
11
  },
34
- {
35
- "type": "object",
36
- "description": "Stop an active Ultimate streaming session.",
37
- "properties": {
38
- "stream": {
39
- "type": "string",
40
- "description": "Stream type to control (video/audio/debug).",
41
- "enum": [
42
- "video",
43
- "audio",
44
- "debug"
45
- ]
46
- },
47
- "op": {
48
- "const": "stop"
49
- }
50
- },
51
- "required": [
52
- "stream",
53
- "op"
54
- ],
55
- "additionalProperties": false
12
+ "stream": {
13
+ "type": "string",
14
+ "description": "Stream type to control (video/audio/debug).",
15
+ "enum": [
16
+ "video",
17
+ "audio",
18
+ "debug"
19
+ ]
20
+ },
21
+ "target": {
22
+ "type": "string",
23
+ "description": "Destination host:port or UDP target understood by the firmware.",
24
+ "minLength": 3
56
25
  }
26
+ },
27
+ "required": [
28
+ "op"
57
29
  ],
58
- "discriminator": {
59
- "propertyName": "op"
60
- }
30
+ "description": "Streaming operations available via the c64_stream tool.\n\nOperations:\n- start: Start an Ultimate streaming session toward a host:port target.\n- stop: Stop an active Ultimate streaming session.",
31
+ "additionalProperties": false
61
32
  }
@@ -1,227 +1,94 @@
1
1
  {
2
2
  "type": "object",
3
- "description": "System operations available via the c64_system tool.",
4
- "oneOf": [
5
- {
6
- "type": "object",
7
- "description": "Pause the machine until resumed.",
8
- "properties": {
9
- "op": {
10
- "const": "pause"
11
- }
12
- },
13
- "additionalProperties": false,
14
- "required": [
15
- "op"
16
- ]
17
- },
18
- {
19
- "type": "object",
20
- "description": "Resume CPU execution after a pause.",
21
- "properties": {
22
- "op": {
23
- "const": "resume"
24
- }
25
- },
26
- "additionalProperties": false,
27
- "required": [
28
- "op"
29
- ]
30
- },
31
- {
32
- "type": "object",
33
- "description": "Issue a soft reset without cutting power.",
34
- "properties": {
35
- "op": {
36
- "const": "reset"
37
- }
38
- },
39
- "additionalProperties": false,
40
- "required": [
41
- "op"
42
- ]
3
+ "properties": {
4
+ "op": {
5
+ "type": "string",
6
+ "enum": [
7
+ "pause",
8
+ "resume",
9
+ "reset",
10
+ "reboot",
11
+ "poweroff",
12
+ "menu",
13
+ "start_task",
14
+ "stop_task",
15
+ "stop_all_tasks",
16
+ "list_tasks",
17
+ "performance_report"
18
+ ],
19
+ "description": "Selects the operation."
43
20
  },
44
- {
45
- "type": "object",
46
- "description": "Trigger a firmware reboot to recover from faults.",
47
- "properties": {
48
- "op": {
49
- "const": "reboot"
50
- }
51
- },
52
- "additionalProperties": false,
53
- "required": [
54
- "op"
55
- ]
21
+ "name": {
22
+ "type": "string",
23
+ "description": "Unique task name",
24
+ "minLength": 1
56
25
  },
57
- {
58
- "type": "object",
59
- "description": "Request a controlled shutdown via the Ultimate firmware.",
60
- "properties": {
61
- "op": {
62
- "const": "poweroff"
63
- }
64
- },
65
- "additionalProperties": false,
66
- "required": [
67
- "op"
68
- ]
26
+ "operation": {
27
+ "type": "string",
28
+ "description": "Operation name (e.g., read, read_screen)",
29
+ "minLength": 1
69
30
  },
70
- {
71
- "type": "object",
72
- "description": "Toggle the Ultimate menu button for navigation.",
73
- "properties": {
74
- "op": {
75
- "const": "menu"
76
- }
77
- },
78
- "additionalProperties": false,
79
- "required": [
80
- "op"
81
- ]
31
+ "arguments": {
32
+ "type": [
33
+ "object",
34
+ "null"
35
+ ],
36
+ "description": "Operation-specific arguments",
37
+ "properties": {},
38
+ "additionalProperties": true,
39
+ "default": {}
82
40
  },
83
- {
84
- "type": "object",
85
- "description": "Start a named background task that runs on an interval.",
86
- "properties": {
87
- "name": {
88
- "type": "string",
89
- "description": "Unique task name",
90
- "minLength": 1
91
- },
92
- "operation": {
93
- "type": "string",
94
- "description": "Operation name (e.g., read, read_screen)",
95
- "minLength": 1
96
- },
97
- "arguments": {
98
- "type": [
99
- "object",
100
- "null"
101
- ],
102
- "description": "Operation-specific arguments",
103
- "properties": {},
104
- "additionalProperties": true,
105
- "default": {}
106
- },
107
- "intervalMs": {
108
- "type": [
109
- "integer",
110
- "null"
111
- ],
112
- "description": "Interval milliseconds",
113
- "minimum": 1,
114
- "default": 1000
115
- },
116
- "maxIterations": {
117
- "type": [
118
- "integer",
119
- "null"
120
- ],
121
- "description": "Maximum number of iterations (omit for indefinite)",
122
- "minimum": 1
123
- },
124
- "op": {
125
- "const": "start_task"
126
- }
127
- },
128
- "required": [
129
- "name",
130
- "operation",
131
- "op"
41
+ "intervalMs": {
42
+ "type": [
43
+ "integer",
44
+ "null"
132
45
  ],
133
- "additionalProperties": false
46
+ "description": "Interval milliseconds",
47
+ "minimum": 1,
48
+ "default": 1000
134
49
  },
135
- {
136
- "type": "object",
137
- "description": "Stop a specific background task and clear its timer.",
138
- "properties": {
139
- "name": {
140
- "type": "string",
141
- "description": "Task name",
142
- "minLength": 1
143
- },
144
- "op": {
145
- "const": "stop_task"
146
- }
147
- },
148
- "required": [
149
- "name",
150
- "op"
50
+ "maxIterations": {
51
+ "type": [
52
+ "integer",
53
+ "null"
151
54
  ],
152
- "additionalProperties": false
55
+ "description": "Maximum number of iterations (omit for indefinite)",
56
+ "minimum": 1
153
57
  },
154
- {
155
- "type": "object",
156
- "description": "Stop every running background task and persist state.",
157
- "properties": {
158
- "op": {
159
- "const": "stop_all_tasks"
160
- }
161
- },
162
- "additionalProperties": false,
163
- "required": [
164
- "op"
165
- ]
58
+ "scope": {
59
+ "type": [
60
+ "string",
61
+ "null"
62
+ ],
63
+ "description": "Which diagnostics session to summarize.",
64
+ "enum": [
65
+ "current",
66
+ "latest"
67
+ ],
68
+ "default": "current"
166
69
  },
167
- {
168
- "type": "object",
169
- "description": "List known background tasks with status metadata.",
170
- "properties": {
171
- "op": {
172
- "const": "list_tasks"
173
- }
174
- },
175
- "additionalProperties": false,
176
- "required": [
177
- "op"
178
- ]
70
+ "includeTimeline": {
71
+ "type": [
72
+ "boolean",
73
+ "null"
74
+ ],
75
+ "description": "Include the tail of the event timeline.",
76
+ "default": true
179
77
  },
180
- {
181
- "type": "object",
182
- "description": "Summarize diagnostics spans and tool latencies from the current or latest MCP session.",
183
- "properties": {
184
- "scope": {
185
- "type": [
186
- "string",
187
- "null"
188
- ],
189
- "description": "Which diagnostics session to summarize.",
190
- "enum": [
191
- "current",
192
- "latest"
193
- ],
194
- "default": "current"
195
- },
196
- "includeTimeline": {
197
- "type": [
198
- "boolean",
199
- "null"
200
- ],
201
- "description": "Include the tail of the event timeline.",
202
- "default": true
203
- },
204
- "maxEntries": {
205
- "type": [
206
- "integer",
207
- "null"
208
- ],
209
- "description": "Maximum number of span and timeline entries to return.",
210
- "minimum": 1,
211
- "maximum": 200,
212
- "default": 25
213
- },
214
- "op": {
215
- "const": "performance_report"
216
- }
217
- },
218
- "additionalProperties": false,
219
- "required": [
220
- "op"
221
- ]
78
+ "maxEntries": {
79
+ "type": [
80
+ "integer",
81
+ "null"
82
+ ],
83
+ "description": "Maximum number of span and timeline entries to return.",
84
+ "minimum": 1,
85
+ "maximum": 200,
86
+ "default": 25
222
87
  }
88
+ },
89
+ "required": [
90
+ "op"
223
91
  ],
224
- "discriminator": {
225
- "propertyName": "op"
226
- }
92
+ "description": "System operations available via the c64_system tool.\n\nOperations:\n- pause: Pause the machine until resumed.\n- resume: Resume CPU execution after a pause.\n- reset: Issue a soft reset without cutting power.\n- reboot: Trigger a firmware reboot to recover from faults.\n- poweroff: Request a controlled shutdown via the Ultimate firmware.\n- menu: Toggle the Ultimate menu button for navigation.\n- start_task: Start a named background task that runs on an interval.\n- stop_task: Stop a specific background task and clear its timer.\n- stop_all_tasks: Stop every running background task and persist state.\n- list_tasks: List known background tasks with status metadata.\n- performance_report: Summarize diagnostics spans and tool latencies from the current or latest MCP session.",
93
+ "additionalProperties": false
227
94
  }
@@ -1,63 +1,32 @@
1
1
  {
2
2
  "type": "object",
3
- "description": "VICE emulator operations available via the c64_vice tool.",
4
- "oneOf": [
5
- {
6
- "type": "object",
7
- "description": "Read a VICE configuration resource (safe prefixes only).",
8
- "properties": {
9
- "op": {
10
- "const": "resource_get"
11
- },
12
- "name": {
13
- "type": "string",
14
- "description": "VICE resource name (example: SidEngine, C64Model).",
15
- "minLength": 1,
16
- "maxLength": 64,
17
- "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
18
- }
19
- },
20
- "required": [
21
- "op",
22
- "name"
3
+ "properties": {
4
+ "op": {
5
+ "type": "string",
6
+ "enum": [
7
+ "resource_get",
8
+ "resource_set"
23
9
  ],
24
- "additionalProperties": false
10
+ "description": "Selects the operation."
25
11
  },
26
- {
27
- "type": "object",
28
- "description": "Write a VICE configuration resource (safe prefixes only).",
29
- "properties": {
30
- "op": {
31
- "const": "resource_set"
32
- },
33
- "name": {
34
- "type": "string",
35
- "description": "VICE resource name (example: SidEngine, C64Model).",
36
- "minLength": 1,
37
- "maxLength": 64,
38
- "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
39
- },
40
- "value": {
41
- "description": "VICE resource value (string or integer).",
42
- "oneOf": [
43
- {
44
- "type": "string"
45
- },
46
- {
47
- "type": "integer"
48
- }
49
- ]
50
- }
51
- },
52
- "required": [
53
- "op",
54
- "name",
55
- "value"
12
+ "name": {
13
+ "type": "string",
14
+ "description": "VICE resource name (example: SidEngine, C64Model).",
15
+ "minLength": 1,
16
+ "maxLength": 64,
17
+ "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
18
+ },
19
+ "value": {
20
+ "type": [
21
+ "string",
22
+ "integer"
56
23
  ],
57
- "additionalProperties": false
24
+ "description": "VICE resource value (string or integer)."
58
25
  }
26
+ },
27
+ "required": [
28
+ "op"
59
29
  ],
60
- "discriminator": {
61
- "propertyName": "op"
62
- }
30
+ "description": "VICE emulator operations available via the c64_vice tool.\n\nOperations:\n- resource_get: Read a VICE configuration resource (safe prefixes only).\n- resource_set: Write a VICE configuration resource (safe prefixes only).",
31
+ "additionalProperties": false
63
32
  }
package/mcp/server.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "c64bridge",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
4
4
  "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
5
5
  "transports": [
6
6
  "stdio"