@mostra/mcp 0.0.0-placeholder → 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.
- package/LICENSE +202 -0
- package/README.md +26 -1
- package/dist/index.d.ts +283 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1405 -0
- package/dist/index.js.map +1 -0
- package/package.json +64 -4
- package/schemas/mcp-tools.draft-07.json +421 -0
- package/schemas/mcp-tools.schema.json +421 -0
- package/src/http.ts +188 -0
- package/src/index.ts +52 -0
- package/src/patch.ts +232 -0
- package/src/ports.ts +116 -0
- package/src/results.ts +45 -0
- package/src/search.ts +98 -0
- package/src/server.ts +273 -0
- package/src/tools.ts +812 -0
- package/src/workspace.ts +351 -0
package/src/tools.ts
ADDED
|
@@ -0,0 +1,812 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The MCP server's tools (INTERFACES §12, D61, D164 item 2): stateless, each taking explicit
|
|
3
|
+
* handles (a directory, an artifact, a cursor) and calling the instance through the host
|
|
4
|
+
* protocol. A tool is a definition: its name, its input schema (a wire-schema bundle, so a change
|
|
5
|
+
* that isn't additive fails the snapshot check, D32), its description and what it does. The server
|
|
6
|
+
* module registers them; nothing here knows the transport.
|
|
7
|
+
*/
|
|
8
|
+
import { randomUUID } from "node:crypto";
|
|
9
|
+
import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/server";
|
|
10
|
+
import {
|
|
11
|
+
type ArtifactRef,
|
|
12
|
+
artifactCreateMethod,
|
|
13
|
+
artifactListMethod,
|
|
14
|
+
artifactPublishMethod,
|
|
15
|
+
artifactVerifyMethod,
|
|
16
|
+
CapabilityScope,
|
|
17
|
+
createDiagnostic,
|
|
18
|
+
type Diagnostic,
|
|
19
|
+
Duration,
|
|
20
|
+
livePushMethod,
|
|
21
|
+
MutationId,
|
|
22
|
+
RpcError,
|
|
23
|
+
resultsGetMethod,
|
|
24
|
+
stateGetMethod,
|
|
25
|
+
statePatchMethod,
|
|
26
|
+
viewDefaultMethod,
|
|
27
|
+
viewLaunchMethod,
|
|
28
|
+
viewUrlMethod,
|
|
29
|
+
WaitCondition,
|
|
30
|
+
waitMethod,
|
|
31
|
+
} from "@mostra/protocol";
|
|
32
|
+
import * as z from "zod";
|
|
33
|
+
import { planPatch } from "./patch.ts";
|
|
34
|
+
import type { McpServerOptions } from "./ports.ts";
|
|
35
|
+
import { errorResult, jsonResult, textResult } from "./results.ts";
|
|
36
|
+
import { searchDocs } from "./search.ts";
|
|
37
|
+
|
|
38
|
+
/** The registry of every tool's input schema, published as the `mcp-tools` bundle. */
|
|
39
|
+
export const toolRegistry: z.core.$ZodRegistry<{ id: string; description?: string }> = z.registry<{
|
|
40
|
+
id: string;
|
|
41
|
+
description?: string;
|
|
42
|
+
}>();
|
|
43
|
+
|
|
44
|
+
/** The longest `artifact_wait`, in seconds (INTERFACES §12, FAILURE_MODEL §9). */
|
|
45
|
+
export const WAIT_MAX_SECONDS = 50;
|
|
46
|
+
|
|
47
|
+
/** What a tool's run gets besides its arguments. */
|
|
48
|
+
export interface ToolCall {
|
|
49
|
+
/** The ports and settings the server was built with. */
|
|
50
|
+
readonly options: McpServerOptions;
|
|
51
|
+
/** Reports progress to a client that asked for it (`progressToken`); a no-op otherwise. */
|
|
52
|
+
progress(message: string): void;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** One tool. */
|
|
56
|
+
export interface ToolDefinition<Input> {
|
|
57
|
+
/** Its name in `tools/list`: short and stable (D32). */
|
|
58
|
+
readonly name: string;
|
|
59
|
+
/** Its display name. */
|
|
60
|
+
readonly title: string;
|
|
61
|
+
/** What the model reads to choose it (agent-facing prose, D74). */
|
|
62
|
+
readonly description: string;
|
|
63
|
+
/** Its arguments' schema, published in the `mcp-tools` bundle. */
|
|
64
|
+
readonly input: z.ZodType<Input>;
|
|
65
|
+
/** Hints for the client: whether it reads only, changes or destroys anything. */
|
|
66
|
+
readonly annotations: ToolAnnotations;
|
|
67
|
+
/** Does the tool's work; a throw becomes an `isError` result with its diagnostic. */
|
|
68
|
+
run(args: Input, call: ToolCall): Promise<CallToolResult>;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** An input schema, registered for the wire bundle under `id`. */
|
|
72
|
+
function input<T extends z.ZodObject>(id: string, schema: T): T {
|
|
73
|
+
toolRegistry.add(schema, { id });
|
|
74
|
+
return schema;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function defineTool<Input>(tool: ToolDefinition<Input>): ToolDefinition<unknown> {
|
|
78
|
+
return tool as ToolDefinition<unknown>;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const ARTIFACT_ID = /^art_[0-9A-HJKMNP-TV-Z]{26}$/;
|
|
82
|
+
|
|
83
|
+
/** An artifact named by its ID, or by its directory (absolute, or inside the workspace). */
|
|
84
|
+
function artifactRef(value: string, options: McpServerOptions): ArtifactRef {
|
|
85
|
+
return ARTIFACT_ID.test(value)
|
|
86
|
+
? { artifactId: value }
|
|
87
|
+
: { path: options.workspace.resolveDir(value) };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const dirField = z
|
|
91
|
+
.string()
|
|
92
|
+
.min(1)
|
|
93
|
+
.describe(
|
|
94
|
+
"The artifact's directory: an absolute path, or a name inside the workspace folder (the server's instructions name it).",
|
|
95
|
+
);
|
|
96
|
+
const artifactField = z
|
|
97
|
+
.string()
|
|
98
|
+
.min(1)
|
|
99
|
+
.describe("The artifact: its ID (art_…), or its directory as artifact_create returned it.");
|
|
100
|
+
|
|
101
|
+
// ── Authoring ────────────────────────────────────────────────────────────────────────────
|
|
102
|
+
|
|
103
|
+
const createInput = input(
|
|
104
|
+
"ArtifactCreateInput",
|
|
105
|
+
z.object({
|
|
106
|
+
dir: dirField
|
|
107
|
+
.optional()
|
|
108
|
+
.describe(
|
|
109
|
+
"Where to create it: a directory that doesn't exist yet or is empty. Without it, a new folder in the workspace, named after the title.",
|
|
110
|
+
),
|
|
111
|
+
title: z.string().min(1).max(200).optional().describe("The artifact's title."),
|
|
112
|
+
template: z.string().min(1).optional().describe("A template to start from (none by default)."),
|
|
113
|
+
}),
|
|
114
|
+
);
|
|
115
|
+
|
|
116
|
+
const writeInput = input(
|
|
117
|
+
"ArtifactWriteInput",
|
|
118
|
+
z.object({
|
|
119
|
+
dir: dirField,
|
|
120
|
+
files: z
|
|
121
|
+
.array(
|
|
122
|
+
z.object({
|
|
123
|
+
path: z
|
|
124
|
+
.string()
|
|
125
|
+
.min(1)
|
|
126
|
+
.describe(
|
|
127
|
+
"Relative to the artifact's directory, such as index.tsx or components/chart.tsx.",
|
|
128
|
+
),
|
|
129
|
+
content: z.string().describe("The file's whole content."),
|
|
130
|
+
encoding: z
|
|
131
|
+
.enum(["utf8", "base64"])
|
|
132
|
+
.optional()
|
|
133
|
+
.describe("utf8 (the default) for text; base64 for an image or other binary file."),
|
|
134
|
+
}),
|
|
135
|
+
)
|
|
136
|
+
.default([])
|
|
137
|
+
.describe("Files to write, each replaced whole."),
|
|
138
|
+
deletes: z
|
|
139
|
+
.array(z.string().min(1))
|
|
140
|
+
.optional()
|
|
141
|
+
.describe("Files to delete, relative to the artifact's directory."),
|
|
142
|
+
}),
|
|
143
|
+
);
|
|
144
|
+
|
|
145
|
+
const patchInput = input(
|
|
146
|
+
"ArtifactPatchInput",
|
|
147
|
+
z.object({
|
|
148
|
+
dir: dirField,
|
|
149
|
+
path: z
|
|
150
|
+
.string()
|
|
151
|
+
.min(1)
|
|
152
|
+
.optional()
|
|
153
|
+
.describe(
|
|
154
|
+
"The file to change, relative to the artifact's directory. Needed with edits; with a diff, it overrides the file the diff names.",
|
|
155
|
+
),
|
|
156
|
+
edits: z
|
|
157
|
+
.array(
|
|
158
|
+
z.object({
|
|
159
|
+
old: z
|
|
160
|
+
.string()
|
|
161
|
+
.describe("Text that appears exactly once in the file (empty to write a new file)."),
|
|
162
|
+
new: z.string().describe("What replaces it."),
|
|
163
|
+
}),
|
|
164
|
+
)
|
|
165
|
+
.min(1)
|
|
166
|
+
.optional()
|
|
167
|
+
.describe("Exact replacements, applied in order."),
|
|
168
|
+
diff: z.string().min(1).optional().describe("A unified diff of one or more files."),
|
|
169
|
+
}),
|
|
170
|
+
);
|
|
171
|
+
|
|
172
|
+
const verifyInput = input(
|
|
173
|
+
"ArtifactVerifyInput",
|
|
174
|
+
z.object({
|
|
175
|
+
dir: dirField,
|
|
176
|
+
screenshots: z
|
|
177
|
+
.enum(["on-failure", "always", "never"])
|
|
178
|
+
.optional()
|
|
179
|
+
.describe(
|
|
180
|
+
"Which screenshots come back as images: on-failure (the default), always (to look at the page), or never.",
|
|
181
|
+
),
|
|
182
|
+
}),
|
|
183
|
+
);
|
|
184
|
+
|
|
185
|
+
const publishInput = input(
|
|
186
|
+
"ArtifactPublishInput",
|
|
187
|
+
z.object({
|
|
188
|
+
dir: dirField,
|
|
189
|
+
force: z
|
|
190
|
+
.boolean()
|
|
191
|
+
.optional()
|
|
192
|
+
.describe("Publish even though verify reports errors; the version records them."),
|
|
193
|
+
}),
|
|
194
|
+
);
|
|
195
|
+
|
|
196
|
+
// ── Viewing and interaction ──────────────────────────────────────────────────────────────
|
|
197
|
+
|
|
198
|
+
const openInput = input(
|
|
199
|
+
"ArtifactOpenInput",
|
|
200
|
+
z.object({
|
|
201
|
+
artifact: artifactField,
|
|
202
|
+
version: z
|
|
203
|
+
.union([z.int().min(1), z.string().min(1)])
|
|
204
|
+
.optional()
|
|
205
|
+
.describe("A new link that opens only this version (its number or ID)."),
|
|
206
|
+
viewer: z
|
|
207
|
+
.object({
|
|
208
|
+
ref: z
|
|
209
|
+
.string()
|
|
210
|
+
.min(1)
|
|
211
|
+
.max(256)
|
|
212
|
+
.describe("Your own stable key for the person, such as their email."),
|
|
213
|
+
name: z.string().min(1).max(200).optional().describe("Their display name."),
|
|
214
|
+
})
|
|
215
|
+
.optional()
|
|
216
|
+
.describe(
|
|
217
|
+
"A new link for one person: their own draft and, under once per-viewer, their own submission.",
|
|
218
|
+
),
|
|
219
|
+
scopes: z
|
|
220
|
+
.array(CapabilityScope)
|
|
221
|
+
.min(1)
|
|
222
|
+
.optional()
|
|
223
|
+
.describe(
|
|
224
|
+
"A new link that allows only these: view, draft, submit, review, signal, action:*, action:<name>.",
|
|
225
|
+
),
|
|
226
|
+
ttl: Duration.optional().describe(
|
|
227
|
+
"A new link that stops working after this long, such as 24h or 7d.",
|
|
228
|
+
),
|
|
229
|
+
open: z
|
|
230
|
+
.boolean()
|
|
231
|
+
.optional()
|
|
232
|
+
.describe("Also open the link in a browser on this computer, for the person sitting at it."),
|
|
233
|
+
}),
|
|
234
|
+
);
|
|
235
|
+
|
|
236
|
+
const waitInput = input(
|
|
237
|
+
"ArtifactWaitInput",
|
|
238
|
+
z.object({
|
|
239
|
+
artifact: artifactField,
|
|
240
|
+
until: WaitCondition.describe(
|
|
241
|
+
"submitted, signal:<name>, state:<fieldId> or event:<type> (event:submission.* matches a family).",
|
|
242
|
+
),
|
|
243
|
+
after: z
|
|
244
|
+
.string()
|
|
245
|
+
.regex(/^[0-9]{1,20}$/)
|
|
246
|
+
.optional()
|
|
247
|
+
.describe("Wait for what happens after this cursor: the one a previous wait returned."),
|
|
248
|
+
timeoutSeconds: z
|
|
249
|
+
.int()
|
|
250
|
+
.min(0)
|
|
251
|
+
.max(WAIT_MAX_SECONDS)
|
|
252
|
+
.optional()
|
|
253
|
+
.describe(
|
|
254
|
+
`How long to wait, at most ${WAIT_MAX_SECONDS} seconds (the default); 0 checks once.`,
|
|
255
|
+
),
|
|
256
|
+
}),
|
|
257
|
+
);
|
|
258
|
+
|
|
259
|
+
const resultsInput = input(
|
|
260
|
+
"ArtifactResultsInput",
|
|
261
|
+
z.object({
|
|
262
|
+
artifact: artifactField,
|
|
263
|
+
submission: z
|
|
264
|
+
.string()
|
|
265
|
+
.min(1)
|
|
266
|
+
.optional()
|
|
267
|
+
.describe("A submission's ID (sub_…); the latest by default."),
|
|
268
|
+
format: z
|
|
269
|
+
.enum(["md", "json"])
|
|
270
|
+
.optional()
|
|
271
|
+
.describe("md (the default): Markdown to read; json: the full Results structure."),
|
|
272
|
+
}),
|
|
273
|
+
);
|
|
274
|
+
|
|
275
|
+
const listInput = input(
|
|
276
|
+
"ArtifactListInput",
|
|
277
|
+
z.object({
|
|
278
|
+
filter: z
|
|
279
|
+
.object({ family: z.string().min(1).optional().describe("Only artifacts of this family.") })
|
|
280
|
+
.optional(),
|
|
281
|
+
}),
|
|
282
|
+
);
|
|
283
|
+
|
|
284
|
+
const livePushInput = input(
|
|
285
|
+
"LivePushInput",
|
|
286
|
+
z.object({
|
|
287
|
+
artifact: artifactField,
|
|
288
|
+
key: z.string().min(1).max(128).describe("The live source's key."),
|
|
289
|
+
value: z.unknown().describe("Any JSON value, at most 4 MiB."),
|
|
290
|
+
mode: z
|
|
291
|
+
.enum(["replace", "append"])
|
|
292
|
+
.optional()
|
|
293
|
+
.describe(
|
|
294
|
+
"replace (the default): the new latest value; append: also kept in the source's ring.",
|
|
295
|
+
),
|
|
296
|
+
}),
|
|
297
|
+
);
|
|
298
|
+
|
|
299
|
+
const stateGetInput = input(
|
|
300
|
+
"StateGetInput",
|
|
301
|
+
z.object({
|
|
302
|
+
artifact: artifactField,
|
|
303
|
+
ids: z
|
|
304
|
+
.array(z.string().min(1))
|
|
305
|
+
.optional()
|
|
306
|
+
.describe("Only these field IDs; every field by default."),
|
|
307
|
+
}),
|
|
308
|
+
);
|
|
309
|
+
|
|
310
|
+
const statePatchInput = input(
|
|
311
|
+
"StatePatchInput",
|
|
312
|
+
z.object({
|
|
313
|
+
artifact: artifactField,
|
|
314
|
+
ops: z
|
|
315
|
+
.array(
|
|
316
|
+
z.object({
|
|
317
|
+
id: z.string().min(1).describe("The field ID."),
|
|
318
|
+
value: z.unknown().optional().describe("The new value, any JSON."),
|
|
319
|
+
delete: z.literal(true).optional().describe("Remove the field instead."),
|
|
320
|
+
}),
|
|
321
|
+
)
|
|
322
|
+
.min(1)
|
|
323
|
+
.describe("The changes, applied together."),
|
|
324
|
+
baseRevision: z
|
|
325
|
+
.string()
|
|
326
|
+
.min(1)
|
|
327
|
+
.optional()
|
|
328
|
+
.describe(
|
|
329
|
+
"The revision you last read: fields changed after it aren't overwritten and come back in conflicts.",
|
|
330
|
+
),
|
|
331
|
+
mutationId: MutationId.schema
|
|
332
|
+
.optional()
|
|
333
|
+
.describe(
|
|
334
|
+
"Your ID for this change (mut_ and a ULID), so a retry applies it once; one is made when you leave it out.",
|
|
335
|
+
),
|
|
336
|
+
}),
|
|
337
|
+
);
|
|
338
|
+
|
|
339
|
+
const docsInput = input(
|
|
340
|
+
"DocsSearchInput",
|
|
341
|
+
z.object({
|
|
342
|
+
query: z.string().min(1).max(500).optional().describe("What you want to know, in a few words."),
|
|
343
|
+
topic: z
|
|
344
|
+
.string()
|
|
345
|
+
.min(1)
|
|
346
|
+
.max(128)
|
|
347
|
+
.optional()
|
|
348
|
+
.describe(
|
|
349
|
+
"A topic to read whole instead, such as guide, guide/answers or a diagnostic code.",
|
|
350
|
+
),
|
|
351
|
+
}),
|
|
352
|
+
);
|
|
353
|
+
|
|
354
|
+
/** Reads a verdict's screenshots that are marked worth looking at, as image content. */
|
|
355
|
+
async function screenshotImages(
|
|
356
|
+
verdict: {
|
|
357
|
+
readonly screenshots: readonly {
|
|
358
|
+
readonly path: string;
|
|
359
|
+
readonly returned: boolean;
|
|
360
|
+
readonly viewport: string;
|
|
361
|
+
}[];
|
|
362
|
+
},
|
|
363
|
+
read: (path: string) => Promise<Uint8Array | undefined>,
|
|
364
|
+
): Promise<CallToolResult["content"]> {
|
|
365
|
+
const content: CallToolResult["content"] = [];
|
|
366
|
+
for (const shot of verdict.screenshots) {
|
|
367
|
+
if (!shot.returned) continue;
|
|
368
|
+
const bytes = await read(shot.path).catch(() => undefined);
|
|
369
|
+
if (bytes === undefined) continue;
|
|
370
|
+
content.push({ type: "text", text: `Screenshot ${shot.viewport}:` });
|
|
371
|
+
content.push({
|
|
372
|
+
type: "image",
|
|
373
|
+
mimeType: "image/png",
|
|
374
|
+
data: Buffer.from(bytes).toString("base64"),
|
|
375
|
+
});
|
|
376
|
+
}
|
|
377
|
+
return content;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** Every tool, in the order clients list them: the authoring loop first. */
|
|
381
|
+
export function createTools(
|
|
382
|
+
readScreenshot: (path: string) => Promise<Uint8Array | undefined>,
|
|
383
|
+
): readonly ToolDefinition<unknown>[] {
|
|
384
|
+
return [
|
|
385
|
+
defineTool({
|
|
386
|
+
name: "artifact_create",
|
|
387
|
+
title: "Create an artifact",
|
|
388
|
+
description:
|
|
389
|
+
"Create a new artifact: a directory with an index.tsx page, an AGENTS.md and a CLAUDE.md. The page's defineArtifact holds the artifact's id: keep that line when you rewrite the page. Returns the directory to pass to the other tools.",
|
|
390
|
+
input: createInput,
|
|
391
|
+
annotations: {
|
|
392
|
+
readOnlyHint: false,
|
|
393
|
+
destructiveHint: false,
|
|
394
|
+
idempotentHint: false,
|
|
395
|
+
openWorldHint: false,
|
|
396
|
+
},
|
|
397
|
+
async run(args, { options }) {
|
|
398
|
+
const dir =
|
|
399
|
+
args.dir !== undefined
|
|
400
|
+
? options.workspace.resolveDir(args.dir)
|
|
401
|
+
: await options.workspace.allocateDir(args.title);
|
|
402
|
+
return jsonResult(
|
|
403
|
+
await options.instance.call(artifactCreateMethod, {
|
|
404
|
+
dir,
|
|
405
|
+
...(args.title !== undefined ? { title: args.title } : {}),
|
|
406
|
+
...(args.template !== undefined ? { template: args.template } : {}),
|
|
407
|
+
}),
|
|
408
|
+
);
|
|
409
|
+
},
|
|
410
|
+
}),
|
|
411
|
+
defineTool({
|
|
412
|
+
name: "artifact_write",
|
|
413
|
+
title: "Write artifact files",
|
|
414
|
+
description:
|
|
415
|
+
"Write files of an artifact, each replaced whole, and delete files, all or nothing. Paths are relative to the artifact's directory. Use it to write a page in full; for a small change to a file, artifact_patch sends less.",
|
|
416
|
+
input: writeInput,
|
|
417
|
+
annotations: {
|
|
418
|
+
readOnlyHint: false,
|
|
419
|
+
destructiveHint: true,
|
|
420
|
+
idempotentHint: true,
|
|
421
|
+
openWorldHint: false,
|
|
422
|
+
},
|
|
423
|
+
async run(args, { options }) {
|
|
424
|
+
const dir = options.workspace.resolveDir(args.dir);
|
|
425
|
+
const write = args.files.map((file) => ({
|
|
426
|
+
path: file.path,
|
|
427
|
+
content:
|
|
428
|
+
file.encoding === "base64"
|
|
429
|
+
? new Uint8Array(Buffer.from(file.content, "base64"))
|
|
430
|
+
: new TextEncoder().encode(file.content),
|
|
431
|
+
}));
|
|
432
|
+
const deletes = args.deletes ?? [];
|
|
433
|
+
const warnings = await droppedIds(options, dir, write, deletes);
|
|
434
|
+
const changed = await options.workspace.apply(dir, { write, delete: deletes });
|
|
435
|
+
return jsonResult({ dir, ...changed, ...(warnings.length > 0 ? { warnings } : {}) });
|
|
436
|
+
},
|
|
437
|
+
}),
|
|
438
|
+
defineTool({
|
|
439
|
+
name: "artifact_patch",
|
|
440
|
+
title: "Patch an artifact file",
|
|
441
|
+
description:
|
|
442
|
+
"Change files of an artifact with exact replacements in one file (each old text must appear exactly once), or with a unified diff of one or more files. All or nothing: when an edit or hunk doesn't apply, nothing is written and the result lists each one that didn't, and why.",
|
|
443
|
+
input: patchInput,
|
|
444
|
+
annotations: {
|
|
445
|
+
readOnlyHint: false,
|
|
446
|
+
destructiveHint: true,
|
|
447
|
+
idempotentHint: false,
|
|
448
|
+
openWorldHint: false,
|
|
449
|
+
},
|
|
450
|
+
async run(args, { options }) {
|
|
451
|
+
const dir = options.workspace.resolveDir(args.dir);
|
|
452
|
+
if ((args.edits === undefined) === (args.diff === undefined)) {
|
|
453
|
+
throw usage("Give either edits (with path) or diff, not both.");
|
|
454
|
+
}
|
|
455
|
+
if (args.edits !== undefined && args.path === undefined) {
|
|
456
|
+
throw usage("Edits need the path of the file they change.");
|
|
457
|
+
}
|
|
458
|
+
const request =
|
|
459
|
+
args.edits !== undefined
|
|
460
|
+
? { path: args.path as string, edits: args.edits }
|
|
461
|
+
: {
|
|
462
|
+
...(args.path !== undefined ? { path: args.path } : {}),
|
|
463
|
+
diff: args.diff as string,
|
|
464
|
+
};
|
|
465
|
+
const plan = await planPatch(request, (path) => options.workspace.read(dir, path));
|
|
466
|
+
if (!plan.ok) {
|
|
467
|
+
return errorResult(
|
|
468
|
+
createDiagnostic("MOSTRA_ARTIFACT_PATCH_REJECTED", {
|
|
469
|
+
message: `${plan.rejected.length === 1 ? "One edit or hunk doesn't" : `${plan.rejected.length} edits or hunks don't`} apply; nothing was written.`,
|
|
470
|
+
}),
|
|
471
|
+
{ rejected: plan.rejected },
|
|
472
|
+
);
|
|
473
|
+
}
|
|
474
|
+
const write = plan.change.write.map((file) => ({
|
|
475
|
+
path: file.path,
|
|
476
|
+
content: new TextEncoder().encode(file.content),
|
|
477
|
+
}));
|
|
478
|
+
const warnings = await droppedIds(options, dir, write, plan.change.delete);
|
|
479
|
+
const changed = await options.workspace.apply(dir, { write, delete: plan.change.delete });
|
|
480
|
+
return jsonResult({
|
|
481
|
+
dir,
|
|
482
|
+
patched: changed.written,
|
|
483
|
+
deleted: changed.deleted,
|
|
484
|
+
...(warnings.length > 0 ? { warnings } : {}),
|
|
485
|
+
});
|
|
486
|
+
},
|
|
487
|
+
}),
|
|
488
|
+
defineTool({
|
|
489
|
+
name: "artifact_verify",
|
|
490
|
+
title: "Verify an artifact",
|
|
491
|
+
description:
|
|
492
|
+
"Check an artifact before anyone sees it: type-check, build, render it headlessly, click through it, check accessibility and screenshot it at 1280×800 and 390×844. Returns the verdict (status pass or fail, with diagnostics that carry codes and hints) and the screenshots worth looking at. Fix every error and verify again until the status is pass, then look at the screenshots. Can take a few minutes.",
|
|
493
|
+
input: verifyInput,
|
|
494
|
+
annotations: {
|
|
495
|
+
readOnlyHint: true,
|
|
496
|
+
destructiveHint: false,
|
|
497
|
+
idempotentHint: true,
|
|
498
|
+
openWorldHint: false,
|
|
499
|
+
},
|
|
500
|
+
async run(args, { options, progress }) {
|
|
501
|
+
const progressToken = randomUUID();
|
|
502
|
+
const stop = options.instance.onProgress(progressToken, (update) =>
|
|
503
|
+
progress(`verify: ${update.stage}`),
|
|
504
|
+
);
|
|
505
|
+
try {
|
|
506
|
+
const verdict = await options.instance.call(artifactVerifyMethod, {
|
|
507
|
+
source: { path: options.workspace.resolveDir(args.dir) },
|
|
508
|
+
progressToken,
|
|
509
|
+
...(args.screenshots !== undefined ? { screenshots: args.screenshots } : {}),
|
|
510
|
+
});
|
|
511
|
+
return {
|
|
512
|
+
content: [
|
|
513
|
+
{ type: "text", text: JSON.stringify(verdict) },
|
|
514
|
+
...(await screenshotImages(verdict, readScreenshot)),
|
|
515
|
+
],
|
|
516
|
+
};
|
|
517
|
+
} finally {
|
|
518
|
+
stop();
|
|
519
|
+
}
|
|
520
|
+
},
|
|
521
|
+
}),
|
|
522
|
+
defineTool({
|
|
523
|
+
name: "artifact_publish",
|
|
524
|
+
title: "Publish an artifact",
|
|
525
|
+
description:
|
|
526
|
+
"Publish an artifact as a new immutable version people can open. Publish verifies the source first (reusing a verdict for the same source) and refuses when verify reports errors. Returns the version and the artifact's link (url): a private link, so whoever holds it can use the page.",
|
|
527
|
+
input: publishInput,
|
|
528
|
+
annotations: {
|
|
529
|
+
readOnlyHint: false,
|
|
530
|
+
destructiveHint: false,
|
|
531
|
+
idempotentHint: true,
|
|
532
|
+
openWorldHint: false,
|
|
533
|
+
},
|
|
534
|
+
async run(args, { options, progress }) {
|
|
535
|
+
progress("publish: verifying and building");
|
|
536
|
+
return jsonResult(
|
|
537
|
+
await options.instance.call(artifactPublishMethod, {
|
|
538
|
+
source: { path: options.workspace.resolveDir(args.dir) },
|
|
539
|
+
...(args.force === true ? { force: true } : {}),
|
|
540
|
+
}),
|
|
541
|
+
);
|
|
542
|
+
},
|
|
543
|
+
}),
|
|
544
|
+
defineTool({
|
|
545
|
+
name: "artifact_open",
|
|
546
|
+
title: "Get an artifact's link",
|
|
547
|
+
description:
|
|
548
|
+
"Get a link to an artifact's page to hand to a person. Without options it is the artifact's default link. A link made without viewer is shared by everyone who holds it: they edit one draft and, under the once policy, have one submission between them. For several people, call once per person with viewer, so each gets their own. open: true also opens it in a browser on this computer.",
|
|
549
|
+
input: openInput,
|
|
550
|
+
annotations: {
|
|
551
|
+
readOnlyHint: false,
|
|
552
|
+
destructiveHint: false,
|
|
553
|
+
idempotentHint: false,
|
|
554
|
+
openWorldHint: false,
|
|
555
|
+
},
|
|
556
|
+
async run(args, { options }) {
|
|
557
|
+
const artifact = artifactRef(args.artifact, options);
|
|
558
|
+
const fresh =
|
|
559
|
+
args.version !== undefined ||
|
|
560
|
+
args.viewer !== undefined ||
|
|
561
|
+
args.scopes !== undefined ||
|
|
562
|
+
args.ttl !== undefined;
|
|
563
|
+
const link = fresh
|
|
564
|
+
? await options.instance.call(viewUrlMethod, {
|
|
565
|
+
artifact,
|
|
566
|
+
...(args.version !== undefined ? { version: args.version } : {}),
|
|
567
|
+
...(args.viewer !== undefined
|
|
568
|
+
? {
|
|
569
|
+
viewer: {
|
|
570
|
+
ref: args.viewer.ref,
|
|
571
|
+
...(args.viewer.name !== undefined ? { name: args.viewer.name } : {}),
|
|
572
|
+
},
|
|
573
|
+
}
|
|
574
|
+
: {}),
|
|
575
|
+
...(args.scopes !== undefined ? { scopes: args.scopes } : {}),
|
|
576
|
+
...(args.ttl !== undefined ? { ttl: args.ttl } : {}),
|
|
577
|
+
})
|
|
578
|
+
: await options.instance.call(viewDefaultMethod, { artifact });
|
|
579
|
+
if (args.open !== true) return jsonResult(link);
|
|
580
|
+
if (options.browser === undefined) return jsonResult({ ...link, opened: false });
|
|
581
|
+
const launch = await options.instance.call(viewLaunchMethod, { tokenId: link.tokenId });
|
|
582
|
+
return jsonResult({ ...link, opened: await options.browser.open(launch.url) });
|
|
583
|
+
},
|
|
584
|
+
}),
|
|
585
|
+
defineTool({
|
|
586
|
+
name: "artifact_wait",
|
|
587
|
+
title: "Wait for an answer",
|
|
588
|
+
description: `Wait until a person submits (until: submitted), raises a signal (signal:<name>), changes shared state (state:<fieldId>) or an event happens (event:<type>). Waits at most timeoutSeconds (${WAIT_MAX_SECONDS} at most). Returns satisfied with the event once it happens, or still_waiting with a cursor: nothing is lost, so call again with after set to that cursor, or do other work and check later.`,
|
|
589
|
+
input: waitInput,
|
|
590
|
+
annotations: {
|
|
591
|
+
readOnlyHint: true,
|
|
592
|
+
destructiveHint: false,
|
|
593
|
+
idempotentHint: true,
|
|
594
|
+
openWorldHint: false,
|
|
595
|
+
},
|
|
596
|
+
async run(args, { options }) {
|
|
597
|
+
return jsonResult(
|
|
598
|
+
await options.instance.call(waitMethod, {
|
|
599
|
+
artifact: artifactRef(args.artifact, options),
|
|
600
|
+
until: args.until,
|
|
601
|
+
...(args.after !== undefined ? { after: args.after } : {}),
|
|
602
|
+
timeoutMs: (args.timeoutSeconds ?? WAIT_MAX_SECONDS) * 1000,
|
|
603
|
+
}),
|
|
604
|
+
);
|
|
605
|
+
},
|
|
606
|
+
}),
|
|
607
|
+
defineTool({
|
|
608
|
+
name: "artifact_results",
|
|
609
|
+
title: "Read the results",
|
|
610
|
+
description:
|
|
611
|
+
"Read a submission: the person's answers by label, their choices, comments, actions and signals. Markdown by default; format json gives the full structure. The latest submission unless submission names one.",
|
|
612
|
+
input: resultsInput,
|
|
613
|
+
annotations: {
|
|
614
|
+
readOnlyHint: true,
|
|
615
|
+
destructiveHint: false,
|
|
616
|
+
idempotentHint: true,
|
|
617
|
+
openWorldHint: false,
|
|
618
|
+
},
|
|
619
|
+
async run(args, { options }) {
|
|
620
|
+
const format = args.format ?? "md";
|
|
621
|
+
const results = await options.instance.call(resultsGetMethod, {
|
|
622
|
+
artifact: artifactRef(args.artifact, options),
|
|
623
|
+
...(args.submission !== undefined ? { submission: args.submission } : {}),
|
|
624
|
+
format,
|
|
625
|
+
});
|
|
626
|
+
return format === "md" && "markdown" in results
|
|
627
|
+
? textResult(results.markdown)
|
|
628
|
+
: jsonResult(results);
|
|
629
|
+
},
|
|
630
|
+
}),
|
|
631
|
+
defineTool({
|
|
632
|
+
name: "artifact_list",
|
|
633
|
+
title: "List artifacts",
|
|
634
|
+
description:
|
|
635
|
+
"List the artifacts published in this Mostra home, with their IDs, titles, source directories and latest versions.",
|
|
636
|
+
input: listInput,
|
|
637
|
+
annotations: {
|
|
638
|
+
readOnlyHint: true,
|
|
639
|
+
destructiveHint: false,
|
|
640
|
+
idempotentHint: true,
|
|
641
|
+
openWorldHint: false,
|
|
642
|
+
},
|
|
643
|
+
async run(args, { options }) {
|
|
644
|
+
return jsonResult(
|
|
645
|
+
await options.instance.call(artifactListMethod, {
|
|
646
|
+
...(args.filter?.family !== undefined
|
|
647
|
+
? { filter: { family: args.filter.family } }
|
|
648
|
+
: {}),
|
|
649
|
+
}),
|
|
650
|
+
);
|
|
651
|
+
},
|
|
652
|
+
}),
|
|
653
|
+
defineTool({
|
|
654
|
+
name: "live_push",
|
|
655
|
+
title: "Push a live value",
|
|
656
|
+
description:
|
|
657
|
+
"Push a value to an artifact's live source (a key its live.ts defines, or a new one); open pages show it at once. mode append also keeps it in the source's ring, for charts of recent values.",
|
|
658
|
+
input: livePushInput,
|
|
659
|
+
annotations: {
|
|
660
|
+
readOnlyHint: false,
|
|
661
|
+
destructiveHint: true,
|
|
662
|
+
idempotentHint: false,
|
|
663
|
+
openWorldHint: false,
|
|
664
|
+
},
|
|
665
|
+
async run(args, { options }) {
|
|
666
|
+
return jsonResult(
|
|
667
|
+
await options.instance.call(livePushMethod, {
|
|
668
|
+
artifact: artifactRef(args.artifact, options),
|
|
669
|
+
key: args.key,
|
|
670
|
+
value: args.value,
|
|
671
|
+
...(args.mode !== undefined ? { mode: args.mode } : {}),
|
|
672
|
+
}),
|
|
673
|
+
);
|
|
674
|
+
},
|
|
675
|
+
}),
|
|
676
|
+
defineTool({
|
|
677
|
+
name: "state_get",
|
|
678
|
+
title: "Read shared state",
|
|
679
|
+
description:
|
|
680
|
+
"Read an artifact's shared state (the fields with scope artifact that every viewer sees), with its revision.",
|
|
681
|
+
input: stateGetInput,
|
|
682
|
+
annotations: {
|
|
683
|
+
readOnlyHint: true,
|
|
684
|
+
destructiveHint: false,
|
|
685
|
+
idempotentHint: true,
|
|
686
|
+
openWorldHint: false,
|
|
687
|
+
},
|
|
688
|
+
async run(args, { options }) {
|
|
689
|
+
return jsonResult(
|
|
690
|
+
await options.instance.call(stateGetMethod, {
|
|
691
|
+
artifact: artifactRef(args.artifact, options),
|
|
692
|
+
...(args.ids !== undefined ? { ids: args.ids } : {}),
|
|
693
|
+
}),
|
|
694
|
+
);
|
|
695
|
+
},
|
|
696
|
+
}),
|
|
697
|
+
defineTool({
|
|
698
|
+
name: "state_patch",
|
|
699
|
+
title: "Change shared state",
|
|
700
|
+
description:
|
|
701
|
+
"Change an artifact's shared state as a viewer's edit would: set fields ({ id, value }) or delete them ({ id, delete: true }), together. With baseRevision, a field someone changed after it isn't overwritten and comes back in conflicts. Open pages update at once.",
|
|
702
|
+
input: statePatchInput,
|
|
703
|
+
annotations: {
|
|
704
|
+
readOnlyHint: false,
|
|
705
|
+
destructiveHint: true,
|
|
706
|
+
idempotentHint: true,
|
|
707
|
+
openWorldHint: false,
|
|
708
|
+
},
|
|
709
|
+
async run(args, { options }) {
|
|
710
|
+
return jsonResult(
|
|
711
|
+
await options.instance.call(statePatchMethod, {
|
|
712
|
+
artifact: artifactRef(args.artifact, options),
|
|
713
|
+
ops: args.ops.map((op) => {
|
|
714
|
+
if (op.delete === true) return { id: op.id, delete: true as const };
|
|
715
|
+
if (!("value" in op))
|
|
716
|
+
throw usage(`The op for ${op.id} needs a value, or delete: true.`);
|
|
717
|
+
return { id: op.id, value: op.value };
|
|
718
|
+
}),
|
|
719
|
+
...(args.baseRevision !== undefined ? { baseRevision: args.baseRevision } : {}),
|
|
720
|
+
mutationId: args.mutationId ?? MutationId.create(),
|
|
721
|
+
as: "agent",
|
|
722
|
+
}),
|
|
723
|
+
);
|
|
724
|
+
},
|
|
725
|
+
}),
|
|
726
|
+
defineTool({
|
|
727
|
+
name: "docs_search",
|
|
728
|
+
title: "Search Mostra's reference",
|
|
729
|
+
description:
|
|
730
|
+
"Search Mostra's reference: the guide to writing pages (fields, submission, design, server actions, live data, sharing), the CLI and every diagnostic code. Returns the best passages and each topic's URI; give topic instead of query to read one topic whole (start with topic guide).",
|
|
731
|
+
input: docsInput,
|
|
732
|
+
annotations: {
|
|
733
|
+
readOnlyHint: true,
|
|
734
|
+
destructiveHint: false,
|
|
735
|
+
idempotentHint: true,
|
|
736
|
+
openWorldHint: false,
|
|
737
|
+
},
|
|
738
|
+
async run(args, { options }) {
|
|
739
|
+
if ((args.query === undefined) === (args.topic === undefined)) {
|
|
740
|
+
throw usage("Give either query or topic.");
|
|
741
|
+
}
|
|
742
|
+
if (args.topic !== undefined) {
|
|
743
|
+
const markdown = options.docs.read(args.topic);
|
|
744
|
+
if (markdown !== undefined) return textResult(markdown);
|
|
745
|
+
return errorResult(
|
|
746
|
+
createDiagnostic("MOSTRA_CLI_USAGE", {
|
|
747
|
+
message: `No topic "${args.topic}" in the reference.`,
|
|
748
|
+
}),
|
|
749
|
+
{ nearest: searchDocs(options.docs, args.topic, 3).map((hit) => hit.topic) },
|
|
750
|
+
);
|
|
751
|
+
}
|
|
752
|
+
return jsonResult({ hits: searchDocs(options.docs, args.query as string) });
|
|
753
|
+
},
|
|
754
|
+
}),
|
|
755
|
+
];
|
|
756
|
+
}
|
|
757
|
+
|
|
758
|
+
const ENTRIES = new Set(["index.tsx", "index.jsx", "index.mdx"]);
|
|
759
|
+
const MANIFEST_ID = /\bid\s*:\s*["'`]?(art_[0-9A-HJKMNP-TV-Z]{26})\b/;
|
|
760
|
+
|
|
761
|
+
/**
|
|
762
|
+
* Warnings for a change after which no entry file names the artifact's `id` any more: the next
|
|
763
|
+
* publish would bind the artifact by its path under a new ID (found in an external Codex session).
|
|
764
|
+
* The change is judged whole: an entry rewritten without the id, deleted, or swapped for another
|
|
765
|
+
* entry, with entry names matched without regard to case, since macOS and Windows keep
|
|
766
|
+
* `Index.tsx` and `index.tsx` as one file (Opus review of WP-15, finding 4). The change is made
|
|
767
|
+
* as given either way.
|
|
768
|
+
*/
|
|
769
|
+
async function droppedIds(
|
|
770
|
+
options: McpServerOptions,
|
|
771
|
+
dir: string,
|
|
772
|
+
write: readonly { readonly path: string; readonly content: Uint8Array }[],
|
|
773
|
+
deletes: readonly string[],
|
|
774
|
+
): Promise<Diagnostic[]> {
|
|
775
|
+
const decoder = new TextDecoder();
|
|
776
|
+
const entry = (path: string): string | undefined => {
|
|
777
|
+
const name = path.replaceAll("\\", "/").toLowerCase();
|
|
778
|
+
return ENTRIES.has(name) ? name : undefined;
|
|
779
|
+
};
|
|
780
|
+
const touched = [...write.map((file) => file.path), ...deletes].some((path) => entry(path));
|
|
781
|
+
if (!touched) return [];
|
|
782
|
+
// The id the entries hold now, and what each entry holds once the change is made.
|
|
783
|
+
let id: string | undefined;
|
|
784
|
+
const after = new Map<string, string | undefined>();
|
|
785
|
+
for (const name of ENTRIES) {
|
|
786
|
+
const before = await options.workspace.read(dir, name).catch(() => undefined);
|
|
787
|
+
const text = before === undefined ? undefined : decoder.decode(before);
|
|
788
|
+
id ??= text === undefined ? undefined : MANIFEST_ID.exec(text)?.[1];
|
|
789
|
+
after.set(name, text);
|
|
790
|
+
}
|
|
791
|
+
if (id === undefined) return [];
|
|
792
|
+
for (const path of deletes) {
|
|
793
|
+
const name = entry(path);
|
|
794
|
+
if (name !== undefined) after.set(name, undefined);
|
|
795
|
+
}
|
|
796
|
+
for (const file of write) {
|
|
797
|
+
const name = entry(file.path);
|
|
798
|
+
if (name !== undefined) after.set(name, decoder.decode(file.content));
|
|
799
|
+
}
|
|
800
|
+
if ([...after.values()].some((text) => text?.includes(id))) return [];
|
|
801
|
+
const changed = [...write.map((file) => file.path), ...deletes].filter((path) => entry(path));
|
|
802
|
+
return [
|
|
803
|
+
createDiagnostic("MOSTRA_ARTIFACT_ID_DROPPED", {
|
|
804
|
+
message: `After this change no entry file names the artifact's id, ${id} (${changed.join(", ")} changed); it was made as given.`,
|
|
805
|
+
}),
|
|
806
|
+
];
|
|
807
|
+
}
|
|
808
|
+
|
|
809
|
+
/** A usage error the model can correct: the arguments don't fit together. */
|
|
810
|
+
function usage(message: string): RpcError {
|
|
811
|
+
return new RpcError(createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message }));
|
|
812
|
+
}
|