@bendyline/gezel-mcp 1.2.14 → 1.3.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/README.md CHANGED
@@ -1,15 +1,14 @@
1
1
  # @bendyline/gezel-mcp
2
2
 
3
3
  The [Model Context Protocol](https://modelcontextprotocol.io) server that gives
4
- gezels, the AI companions in [Gezel](https://github.com/bendyline/gezel), their
5
- hands.
4
+ [Gezel](https://github.com/bendyline/gezel) its hands.
6
5
 
7
- Every tool a gezel can call lives here: memory search and save, workspace file
6
+ Every tool Gezel can call lives here: memory search and save, workspace file
8
7
  operations, project artifacts, the shared document library, script and
9
- Playwright execution, task management, team and project management, image
8
+ Playwright execution, task management, crew and project management, image
10
9
  rendering, and history search.
11
10
 
12
- Gezel runs this server for every gezel's chat. It also gives other AI apps
11
+ Gezel runs this server for every chat. It also gives other AI apps
13
12
  (Claude Code, Codex, Cursor, Claude Desktop, VS Code) a small set of Gezel's
14
13
  tools; see [For other AI apps](#for-other-ai-apps).
15
14
 
@@ -50,7 +49,7 @@ Gezel is not running, every tool says so instead of the server exiting.
50
49
 
51
50
  ## The full surface, with your own access
52
51
 
53
- Without `--harness` the server offers every tool a gezel has, acting with your
52
+ Without `--harness` the server offers every tool Gezel has, acting with your
54
53
  own access, as the `gezel` command does. It speaks stdio, so any MCP client can
55
54
  run it. With Gezel running on the same computer:
56
55
 
@@ -61,7 +60,7 @@ run it. With Gezel running on the same computer:
61
60
  "command": "npx",
62
61
  "args": ["-y", "@bendyline/gezel-mcp"],
63
62
  "env": {
64
- "GEZEL_AGENT_ID": "<a gezel id from `gezel agent list`>",
63
+ "GEZEL_AGENT_ID": "<an id from `gezel agent list`>",
65
64
  "GEZEL_PROJECT_ID": "default"
66
65
  }
67
66
  }
@@ -81,20 +80,20 @@ it, then reconnect the server from your MCP client.
81
80
 
82
81
  | Variable | |
83
82
  |---|---|
84
- | `GEZEL_AGENT_ID` | The gezel the tools work as: whose memories they search and save, whose tasks they see. |
83
+ | `GEZEL_AGENT_ID` | The crew member the tools work as: whose memories they search and save, whose tasks they see. |
85
84
  | `GEZEL_PROJECT_ID` | The project tools use when a call names none. Default `default`. |
86
85
  | `GEZEL_HOME` | A Gezel home other than `~/.gezel`. |
87
86
 
88
87
  Run this way, the server acts with your own access, as the `gezel` command
89
88
  does; `GEZEL_PROJECT_ID` picks a default, not a boundary.
90
89
 
91
- `gezel agent list` (from `@bendyline/gezel-cli`) lists your gezels and their
90
+ `gezel agent list` (from `@bendyline/gezel-cli`) lists your crew and their
92
91
  ids. The `agent` in that command and in `GEZEL_AGENT_ID` is a historical name:
93
- both refer to your gezels.
92
+ both refer to your crew members.
94
93
 
95
- When Gezel starts the server itself, for a gezel's chat, it passes the
94
+ When Gezel starts the server itself, for a chat, it passes the
96
95
  connection directly: `GEZEL_BASE_URL`, `GEZEL_TOKEN` (a token it mints for that
97
- one session, confined to its project unless the gezel coordinates across
96
+ one session, confined to its project unless the session coordinates across
98
97
  projects), and `GEZEL_CERT_PATH` (the
99
98
  `runtime/cert.pem` that token's service is using). Setting `GEZEL_BASE_URL`
100
99
  yourself turns the lookup off, and keeping all three current across restarts
@@ -103,7 +102,7 @@ is then up to you.
103
102
  ## Tool categories
104
103
 
105
104
  Memory · workspace files · project artifacts · shared documents · script and
106
- Playwright execution · package installation · team and project management ·
105
+ Playwright execution · package installation · crew and project management ·
107
106
  tasks · user questions · history search · image rendering.
108
107
 
109
108
  Run the server and call `tools/list` for the authoritative, current inventory.
package/dist/bin.js CHANGED
@@ -1,5 +1,38 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ // src/bin-args.ts
4
+ function parseGezelMcpArgs(argv) {
5
+ if (argv.some((arg) => arg === "--help" || arg === "-h")) return { kind: "help" };
6
+ if (argv.some((arg) => arg === "--version" || arg === "-V" || arg === "-v")) {
7
+ return { kind: "version" };
8
+ }
9
+ return { kind: "run" };
10
+ }
11
+ var GEZEL_MCP_HELP = `Usage: gezel-mcp [--harness <app>] [--help] [--version]
12
+
13
+ gezel-mcp is Gezel's tool server, spoken over MCP on stdin and stdout. You
14
+ do not usually run it yourself.
15
+
16
+ gezel-mcp the full tool set Gezel uses itself;
17
+ the Gezel service starts it for each chat
18
+ gezel-mcp --harness <app> Gezel's tools for another AI app: claude-code,
19
+ claude-desktop, codex, cursor or vscode
20
+
21
+ To give an app Gezel's tools, run \`gezel mcp install <app>\`, or set it up
22
+ from Settings -> Integrations in the Gezel app.
23
+
24
+ More: https://github.com/bendyline/gezel/tree/main/packages/mcp
25
+ `;
26
+
3
27
  // src/bin.ts
4
- var entry = process.argv.includes("--harness") ? "./harness.js" : "./server.js";
5
- await import(new URL(entry, import.meta.url).href);
28
+ var args = parseGezelMcpArgs(process.argv.slice(2));
29
+ if (args.kind === "help") {
30
+ process.stdout.write(GEZEL_MCP_HELP);
31
+ } else if (args.kind === "version") {
32
+ const { GEZEL_VERSION } = await import("@bendyline/gezel");
33
+ process.stdout.write(`${GEZEL_VERSION}
34
+ `);
35
+ } else {
36
+ const entry = process.argv.includes("--harness") ? "./harness.js" : "./server.js";
37
+ await import(new URL(entry, import.meta.url).href);
38
+ }
package/dist/server.js CHANGED
@@ -45,7 +45,7 @@ import {
45
45
  fillProjectTypeParams,
46
46
  formatMediaClock,
47
47
  gezelNamesInUse,
48
- isAnswerEnvelope,
48
+ isAnswerEnvelope as isAnswerEnvelope2,
49
49
  isOrdinalWorkOptionId,
50
50
  matchProjectTypeForBrief,
51
51
  normalizeArtifactPath,
@@ -404,7 +404,9 @@ var EditToolOutputSchema = z.object({
404
404
  var VideoToolOutputSchema = z.object({
405
405
  gezelVideo: z.object({
406
406
  artifactPath: z.string(),
407
- mimeType: z.string()
407
+ mimeType: z.string(),
408
+ /** The poster frame's artifact path, when the daemon saved one. */
409
+ posterPath: z.string().optional()
408
410
  })
409
411
  });
410
412
  var TOOL_OUTPUT_SCHEMAS = {
@@ -1263,7 +1265,9 @@ ${invocationSignature(args.invocation)}`;
1263
1265
  // src/craftbook-routing.ts
1264
1266
  import {
1265
1267
  craftbookInputParams,
1266
- fillMainContentParam
1268
+ deriveTaskTitle,
1269
+ fillMainContentParam,
1270
+ isAnswerEnvelope
1267
1271
  } from "@bendyline/gezel";
1268
1272
  import { z as z4 } from "zod";
1269
1273
 
@@ -1518,6 +1522,25 @@ function normalizeCraftbookInvocationParams(params, outputPath) {
1518
1522
  };
1519
1523
  return merged.outputPath ? { ...merged, outputPath: normalizeDocumentOutputPath(merged.outputPath) } : merged;
1520
1524
  }
1525
+ function isPersonsMessage(message) {
1526
+ return message.role === "user" && !message.hidden && !message.from && message.origin !== "system" && message.content.trim().length > 0;
1527
+ }
1528
+ function requestedTaskTitle(title, messages) {
1529
+ const given = title?.trim();
1530
+ if (given) return given;
1531
+ let opened = messages.length - 1;
1532
+ while (opened >= 0 && messages[opened].role !== "user") opened -= 1;
1533
+ const opener = messages[opened];
1534
+ if (!opener || !isPersonsMessage(opener)) return void 0;
1535
+ if (!isAnswerEnvelope(opener.content)) return deriveTaskTitle(opener.content);
1536
+ for (let index = opened - 1; index >= 0; index -= 1) {
1537
+ const earlier = messages[index];
1538
+ if (isPersonsMessage(earlier) && !isAnswerEnvelope(earlier.content)) {
1539
+ return deriveTaskTitle(earlier.content);
1540
+ }
1541
+ }
1542
+ return void 0;
1543
+ }
1521
1544
  function buildBinaryDocumentTaskDescription(input, request) {
1522
1545
  const base = input.taskDescription?.trim() || `Create the requested ${request.route.label} deliverable for "${input.name}" at ${request.outputPath}.`;
1523
1546
  const note = input.kickoffMessage?.trim() ? `
@@ -4917,6 +4940,11 @@ var sessionContextWindow = Number.isFinite(rawSessionContextWindow) && rawSessio
4917
4940
  var certPath = process.env.GEZEL_CERT_PATH;
4918
4941
  var fetchImpl = local?.fetch ?? (certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch());
4919
4942
  var api = new GezelClient({ baseUrl, token, fetch: fetchImpl });
4943
+ function introduceHires(...gezelIds) {
4944
+ if (!sessionId || gezelIds.length === 0) return;
4945
+ void api.introduceCrew(sessionId, { gezelIds }).catch(() => {
4946
+ });
4947
+ }
4920
4948
  var { resolveProjectId, resolveGezelId, availableGezelsHint, parseRef } = createEntityResolvers({
4921
4949
  api,
4922
4950
  projectId,
@@ -5815,6 +5843,7 @@ async function fetchRepoReviewNextHint(projectId2) {
5815
5843
  }
5816
5844
  async function handoffFetchedRepoReview(projectId2) {
5817
5845
  const reviewer = await api.ensureGezel({ jobTitle: "Code Reviewer" });
5846
+ if (reviewer.action !== "reused") introduceHires(reviewer.gezelId);
5818
5847
  const message = await fetchRepoReviewHandoffMessage(projectId2);
5819
5848
  const res = await api.messageGezel(reviewer.gezelId, {
5820
5849
  fromGezelId: gezelId,
@@ -8013,6 +8042,7 @@ server.tool(
8013
8042
  ...templateId && model ? { model } : {}
8014
8043
  });
8015
8044
  }
8045
+ introduceHires(created.id);
8016
8046
  return {
8017
8047
  content: [
8018
8048
  {
@@ -8071,7 +8101,7 @@ server.tool(
8071
8101
  content: [
8072
8102
  {
8073
8103
  type: "text",
8074
- text: `Applied project type ${applied.typeId}@${applied.version} to ${resolvedProject}. Crew: ${gz || "no gezels"}. Installed ${applied.scriptsInstalled.length} script(s); seeded ${applied.workspaceSeeded.length} file(s).`
8104
+ text: applied.upgradedFrom ? `Updated ${resolvedProject} from ${applied.typeId}@${applied.upgradedFrom} to ${applied.version}. Data files the person changed were kept (${applied.seedsSkipped.length}).` : `Applied project type ${applied.typeId}@${applied.version} to ${resolvedProject}. Crew: ${gz || "no gezels"}. Installed ${applied.scriptsInstalled.length} script(s); seeded ${applied.workspaceSeeded.length} file(s).`
8075
8105
  }
8076
8106
  ]
8077
8107
  };
@@ -8373,9 +8403,11 @@ async function currentRootTurnContext() {
8373
8403
  return null;
8374
8404
  }
8375
8405
  const latestUser = [...session.messages].reverse().find((message) => message.role === "user");
8406
+ const requestTitle = requestedTaskTitle(void 0, session.messages);
8376
8407
  return {
8377
8408
  rootTurnId,
8378
- ...latestUser?.content.trim() ? { userText: latestUser.content.trim() } : {}
8409
+ ...latestUser?.content.trim() ? { userText: latestUser.content.trim() } : {},
8410
+ ...requestTitle ? { requestTitle } : {}
8379
8411
  };
8380
8412
  } catch (err) {
8381
8413
  process.stderr.write(
@@ -8668,7 +8700,7 @@ server.tool(
8668
8700
  project: z8.string().optional().describe(
8669
8701
  "Existing project id or name. Defaults to the current project; this tool does not create a new project. Use start_project when the user requests a new project."
8670
8702
  ),
8671
- title: z8.string().optional().describe("Optional task title. Defaults to the craftbook name."),
8703
+ title: z8.string().optional().describe("Optional task title. Defaults to the person's request, else the craftbook name."),
8672
8704
  description: z8.string().optional().describe(
8673
8705
  "Optional task description \u2014 the job-to-be-done. Falls back to the craftbook description when omitted."
8674
8706
  ),
@@ -8711,10 +8743,12 @@ async function runInvokeCraftbook({
8711
8743
  ...tonight ? { tonight: true } : {}
8712
8744
  };
8713
8745
  const rootTurnId = rootTurn?.rootTurnId ?? null;
8714
- const launchInvocation = rootTurnId ? {
8746
+ const taskTitle = title?.trim() || rootTurn?.requestTitle;
8747
+ const launchInvocation = {
8715
8748
  ...invocation,
8716
- craftbookInvocationKey: rootTurnInvocationKey(rootTurnId, invocation)
8717
- } : invocation;
8749
+ ...taskTitle ? { title: taskTitle } : {},
8750
+ ...rootTurnId ? { craftbookInvocationKey: rootTurnInvocationKey(rootTurnId, invocation) } : {}
8751
+ };
8718
8752
  const launched = rootTurnId ? await invokeCraftbookRootTurnCache.run({
8719
8753
  rootTurnId,
8720
8754
  invocation,
@@ -9316,6 +9350,7 @@ server.tool(
9316
9350
  const res = await api.ensureGezel({
9317
9351
  jobTitle
9318
9352
  });
9353
+ if (res.action !== "reused") introduceHires(res.gezelId);
9319
9354
  const headline = res.action === "reused" ? `Reused ${res.name} (${res.role}) \u2014 existing gezel, match score ${res.matchScore?.toFixed(2) ?? "?"}` : res.action === "created-from-gilde" ? `Created ${res.name} from the "${res.templateId}" gilde template` : `Created ${res.name} (${res.role}) with a bespoke about.md`;
9320
9355
  const tail = res.alternatives && res.alternatives.length > 0 ? `
9321
9356
  Runner-ups on the roster: ${res.alternatives.join(", ")}. If ${res.name} is wrong, pass a more specific \`jobTitle\` next time.` : "";
@@ -9344,6 +9379,7 @@ server.tool(
9344
9379
  async ({ templateId }) => {
9345
9380
  const { name, gender } = await pickFreshGezelName();
9346
9381
  const created = await api.createGezelFromTemplate(templateId, { name, gender });
9382
+ introduceHires(created.id);
9347
9383
  return {
9348
9384
  content: [
9349
9385
  {
@@ -9702,6 +9738,7 @@ server.tool(
9702
9738
  const ensured = await api.ensureGezel({
9703
9739
  jobTitle
9704
9740
  });
9741
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9705
9742
  if (ensured.gezelId === gezelId) {
9706
9743
  return {
9707
9744
  content: [
@@ -9882,6 +9919,7 @@ ${expectedDeliverable?.kind === "file" ? expectedDeliverable.filePath ?? "" : ""
9882
9919
  });
9883
9920
  if (repoGuard) return repoGuard;
9884
9921
  const ensured = await api.ensureGezel({ jobTitle });
9922
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9885
9923
  const normalizedMessage = normalizeFileHandoffMessage(task, expectedDeliverable);
9886
9924
  const res = await api.messageGezel(ensured.gezelId, {
9887
9925
  fromGezelId: gezelId,
@@ -9951,6 +9989,7 @@ ${expectedDeliverable?.kind === "file" ? expectedDeliverable.filePath ?? "" : ""
9951
9989
  });
9952
9990
  if (repoGuard) return repoGuard;
9953
9991
  const ensured = await api.ensureGezel({ jobTitle });
9992
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9954
9993
  if (ensured.gezelId === gezelId) {
9955
9994
  return {
9956
9995
  content: [
@@ -10134,15 +10173,17 @@ ${fallbackSentence}`;
10134
10173
  var SPECIALIST_TEMPLATE_IDS = {
10135
10174
  "image-generator": "illustrator"
10136
10175
  };
10137
- async function createSpecialistFromTemplate(role, identity) {
10138
- const preferred = SPECIALIST_TEMPLATE_IDS[role];
10139
- if (preferred) {
10140
- try {
10141
- return { ...await api.createGezelFromTemplate(preferred, identity), templateId: preferred };
10142
- } catch {
10143
- }
10144
- }
10145
- return { ...await api.createGezelFromTemplate(role, identity), templateId: role };
10176
+ async function ensureMainGezel(templateId, role = templateId) {
10177
+ const ensured = await api.ensureGezel({ jobTitle: role, templateId });
10178
+ return {
10179
+ id: ensured.gezelId,
10180
+ name: ensured.name,
10181
+ templateId: ensured.templateId ?? templateId,
10182
+ reused: ensured.action === "reused"
10183
+ };
10184
+ }
10185
+ function mainGezelClause(gezel, as) {
10186
+ return gezel.reused ? `${gezel.name} takes it on as ${as}` : `Recruited ${gezel.name} as ${as}`;
10146
10187
  }
10147
10188
  function normalizeSpecialistRole(value) {
10148
10189
  const lower = value?.trim().toLowerCase() ?? "";
@@ -10375,11 +10416,7 @@ ${idempotent.resultText}`
10375
10416
  mode: "crew",
10376
10417
  lead: "none"
10377
10418
  });
10378
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10379
- const voorman = await api.createGezelFromTemplate("voorman", {
10380
- name: gezelName,
10381
- gender: gezelGender
10382
- });
10419
+ const voorman = await ensureMainGezel("voorman");
10383
10420
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10384
10421
  const effectiveTaskDescription = buildBinaryDocumentTaskDescription(
10385
10422
  {
@@ -10447,11 +10484,7 @@ ${idempotent.resultText}`
10447
10484
  mode: "crew",
10448
10485
  lead: "none"
10449
10486
  });
10450
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10451
- const voorman = await api.createGezelFromTemplate("voorman", {
10452
- name: gezelName,
10453
- gender: gezelGender
10454
- });
10487
+ const voorman = await ensureMainGezel("voorman");
10455
10488
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10456
10489
  const effectiveTaskDescription = buildKickoffTaskDescription({
10457
10490
  ...brief,
@@ -10488,7 +10521,7 @@ ${idempotent.resultText}`
10488
10521
  dispatchEntry: true
10489
10522
  });
10490
10523
  const entryName = await macroEntryAssigneeName(task, voorman.id, voorman.name);
10491
- const resultText = `Started project "${brief.name}" (${project.id}). Recruited ${voorman.name} as crew lead. Created task ${task.ref} ("${task.title}") and handed its entry step to ${entryName} \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (get_task / read_task_notes when the user asks). Tell the user ${entryName} is on it; they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
10524
+ const resultText = `Started project "${brief.name}" (${project.id}). ${mainGezelClause(voorman, "crew lead")}. Created task ${task.ref} ("${task.title}") and handed its entry step to ${entryName} \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (get_task / read_task_notes when the user asks). Tell the user ${entryName} is on it; they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
10492
10525
  recordMacroResult("start_project", brief.name, project.id, resultText);
10493
10526
  return {
10494
10527
  content: [
@@ -10736,11 +10769,7 @@ ${idempotent.resultText}`
10736
10769
  mode: "crew",
10737
10770
  lead: "none"
10738
10771
  });
10739
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10740
- const voorman = await api.createGezelFromTemplate("voorman", {
10741
- name: gezelName,
10742
- gender: gezelGender
10743
- });
10772
+ const voorman = await ensureMainGezel("voorman");
10744
10773
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10745
10774
  const effectiveTaskDescription = buildKickoffTaskDescription({
10746
10775
  ...brief,
@@ -10779,7 +10808,7 @@ ${idempotent.resultText}`
10779
10808
  dispatchEntry: true
10780
10809
  });
10781
10810
  const entryName = await macroEntryAssigneeName(task, voorman.id, voorman.name);
10782
- const resultText = `Started project "${brief.name}" (${project.id}). Recruited ${voorman.name} as crew lead. Created task ${task.ref} ("${task.title}") and handed its entry step to ${entryName} \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (get_task / read_task_notes when the user asks). Tell the user ${entryName} is on it; they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
10811
+ const resultText = `Started project "${brief.name}" (${project.id}). ${mainGezelClause(voorman, "crew lead")}. Created task ${task.ref} ("${task.title}") and handed its entry step to ${entryName} \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (get_task / read_task_notes when the user asks). Tell the user ${entryName} is on it; they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
10783
10812
  recordMacroResult(tool, brief.name, project.id, resultText);
10784
10813
  return {
10785
10814
  content: [
@@ -10815,7 +10844,7 @@ async function personsRoutingRequest() {
10815
10844
  ).map((m) => m.content.trim());
10816
10845
  const latest = said.at(-1);
10817
10846
  if (!latest) return void 0;
10818
- const previous = isAnswerEnvelope(latest) ? said.slice(0, -1).reverse().find((text) => !isAnswerEnvelope(text)) : void 0;
10847
+ const previous = isAnswerEnvelope2(latest) ? said.slice(0, -1).reverse().find((text) => !isAnswerEnvelope2(text)) : void 0;
10819
10848
  return routingRequestText(latest, previous);
10820
10849
  } catch {
10821
10850
  return void 0;
@@ -11115,11 +11144,10 @@ ${idempotent.resultText}`
11115
11144
  missionObjectives: normalizeMarkdown(brief.missionObjectives),
11116
11145
  mode: "solo"
11117
11146
  });
11118
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
11119
- const builder = await createSpecialistFromTemplate(effectiveSpecialistRole, {
11120
- name: gezelName,
11121
- gender: gezelGender
11122
- });
11147
+ const builder = await ensureMainGezel(
11148
+ SPECIALIST_TEMPLATE_IDS[effectiveSpecialistRole] ?? effectiveSpecialistRole,
11149
+ effectiveSpecialistRole
11150
+ );
11123
11151
  await api.updateProject(project.id, { voormanGezelId: builder.id });
11124
11152
  const effectiveTaskDescription = buildKickoffTaskDescription({
11125
11153
  ...brief,
@@ -11159,7 +11187,7 @@ ${idempotent.resultText}`
11159
11187
  ],
11160
11188
  dispatchEntry: true
11161
11189
  });
11162
- const resultText = `Started project "${brief.name}" (${project.id}). Recruited ${builder.name} as lead (template: ${builder.templateId}). Created task ${task.ref} ("${task.title}") and handed ${builder.name} its entry step \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (notes, gates, status \u2014 get_task / read_task_notes when the user asks). Tell the user ${builder.name} is on it and they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
11190
+ const resultText = `Started project "${brief.name}" (${project.id}). ${mainGezelClause(builder, "lead")} (template: ${builder.templateId}). Created task ${task.ref} ("${task.title}") and handed ${builder.name} its entry step \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (notes, gates, status \u2014 get_task / read_task_notes when the user asks). Tell the user ${builder.name} is on it and they can watch the work in the ${brief.name} project. ${PLAIN_WORDS_RELAY}`;
11163
11191
  recordMacroResult(cacheTool, brief.name, project.id, resultText);
11164
11192
  return {
11165
11193
  content: [
@@ -12416,7 +12444,7 @@ ${lines.join("\n")}` : summary }
12416
12444
  );
12417
12445
  server.tool(
12418
12446
  "how_do_i",
12419
- "Consult the Handboek \u2014 gezel's built-in documentation \u2014 for meta questions about gezel itself: what a role can do, how craftbooks / projects / memory / models work, where files live, how to set something up. Ask in plain language and answer from what it returns instead of guessing.",
12447
+ "Consult Help \u2014 Gezel's built-in documentation \u2014 for meta questions about gezel itself: what a role can do, how craftbooks / projects / memory / models work, where files live, how to set something up. Ask in plain language and answer from what it returns instead of guessing.",
12420
12448
  {
12421
12449
  question: z8.string().min(2).describe('Plain-language question, e.g. "how do I give a gezel a different model?"'),
12422
12450
  limit: z8.number().optional().describe("Max articles to return (default 2)")
@@ -12428,7 +12456,7 @@ server.tool(
12428
12456
  content: [
12429
12457
  {
12430
12458
  type: "text",
12431
- text: "The Handboek has no matching article. Answer from your own knowledge of gezel and say so when unsure."
12459
+ text: "Help has no matching article. Answer from your own knowledge of Gezel and say so when unsure."
12432
12460
  }
12433
12461
  ]
12434
12462
  };
@@ -12660,7 +12688,7 @@ If you are working on a website/logo task and an HTML file already exists, your
12660
12688
  const styleLine = appliedStyle ? ` Style: ${appliedStyle.name}.` : "";
12661
12689
  const stylesLine = styles?.length && !imageStylesShown.has(meta.model) ? ` Styles this model has: ${styles.map((s) => s.name).join(", ")}.` : "";
12662
12690
  if (styles?.length) imageStylesShown.add(meta.model);
12663
- const summary = `Generated ${meta.widthPx}\xD7${meta.heightPx} image with ${meta.model} (seed ${meta.seed}, ${meta.steps} steps, ${meta.durationMs}ms).${styleLine}${settingsLine}${skippedLine}${guideLine}${stylesLine} The user already sees this image inline below the tool call \u2014 DO NOT embed it again as Markdown (e.g. \`![alt](artifacts/${artifactPath})\`); just refer to it by name in your reply when needed. To iterate on it, pass \`{ inputImages: [{ artifactPath: "${artifactPath}" }] }\` to a follow-up generate_image call. To read its bytes, call \`read_artifact\` with path \`${artifactPath}\`.${workspaceLine}`;
12691
+ const summary = `Generated ${meta.widthPx}\xD7${meta.heightPx} image with ${meta.model} (seed ${meta.seed}, ${meta.steps} steps, ${meta.durationMs}ms).${styleLine}${settingsLine}${skippedLine}${guideLine}${stylesLine} The user already sees this image inline below the tool call \u2014 DO NOT embed it again as Markdown (e.g. \`![alt](artifacts/${artifactPath})\`); just refer to it by name in your reply when needed. To iterate on it, pass \`{ inputImages: [{ artifactPath: "${artifactPath}" }] }\` to a follow-up generate_image call.${await installedVideoAnimates() ? ` To animate it, pass \`{ inputImage: { artifactPath: "${artifactPath}" } }\` to generate_video.` : ""} To read its bytes, call \`read_artifact\` with path \`${artifactPath}\`.${workspaceLine}`;
12664
12692
  const content = [{ type: "text", text: summary }];
12665
12693
  if (b64Png) {
12666
12694
  content.push({ type: "image", data: b64Png, mimeType: "image/png" });
@@ -12685,9 +12713,20 @@ If you are working on a website/logo task and an HTML file already exists, your
12685
12713
  }
12686
12714
  }
12687
12715
  );
12716
+ var videoAnimatesCache;
12717
+ function installedVideoAnimates() {
12718
+ const now = Date.now();
12719
+ if (!videoAnimatesCache || now - videoAnimatesCache.at > 6e4) {
12720
+ videoAnimatesCache = {
12721
+ at: now,
12722
+ value: api.listInstalledVideoModels().then((res) => res.defaultImageToVideoModel !== void 0).catch(() => false)
12723
+ };
12724
+ }
12725
+ return videoAnimatesCache.value;
12726
+ }
12688
12727
  server.tool(
12689
12728
  "generate_video",
12690
- "Generate a short video clip from a text prompt (and optionally a starting image for image-to-video). Routes through the local bundled diffusers engine (LTX by default). The encoded MP4 is written to the project's `artifacts/generated/` folder and a workspace copy is dropped at `assets/generated/` for HTML `<video src>` references. Video generation is slow and GPU-intensive \u2014 it pauses the chat model while it runs \u2014 so the user may see a one-time confirmation card before each call (they can choose Always allow to silence it). Omit width, height, numFrames, fps, and steps unless the user explicitly asked for specific values. On error the tool returns a message directing the user to the Video generation settings.",
12729
+ "Generate a short video clip from a text prompt, or animate a picture: pass it as `inputImage` and it becomes the first frame, so the prompt should describe how it moves. Renders on this computer's video engine. The clip is written to the project's `artifacts/generated/` folder (MP4, or WebM when MP4 cannot be made) and a workspace copy is dropped at `assets/generated/` for HTML `<video src>` references. Video generation is slow and GPU-intensive \u2014 it pauses the chat model while it runs \u2014 so the user may see a one-time confirmation card before each call (they can choose Always allow to silence it). Omit width, height, numFrames, fps, and steps unless the user explicitly asked for specific values. On error the tool returns a message directing the user to the Video generation settings.",
12691
12730
  {
12692
12731
  prompt: z8.string().min(1).describe("What the video should depict."),
12693
12732
  negativePrompt: z8.string().optional().describe("Concepts to avoid."),
@@ -12708,7 +12747,13 @@ server.tool(
12708
12747
  data: z8.string().min(1).describe("Base64-encoded image bytes."),
12709
12748
  mimeType: z8.string().default("image/png")
12710
12749
  })
12711
- ]).optional().describe("Optional starting image for image-to-video (I2V-capable models only)."),
12750
+ ]).optional().describe(
12751
+ "A picture to animate: it becomes the clip's first frame and sets its shape. To animate a picture you made with generate_image, pass its artifactPath."
12752
+ ),
12753
+ requireImageToVideo: z8.boolean().optional().describe(
12754
+ "Set when animating the picture is the point: the call fails rather than make a clip from the words alone if no installed model animates pictures."
12755
+ ),
12756
+ aspectRatio: z8.enum(IMAGE_ASPECT_RATIOS).optional().describe("The clip's shape. Omit to use the picture's shape, or the model's default."),
12712
12757
  saveAs: z8.string().optional().describe(
12713
12758
  "Workspace-relative path to write the clip at (e.g. `assets/hero.mp4`). Must be a relative path with no `..` segments and a `.mp4` / `.webm` extension."
12714
12759
  )
@@ -12726,6 +12771,8 @@ server.tool(
12726
12771
  ...args.steps ? { steps: args.steps } : {},
12727
12772
  ...args.seed !== void 0 ? { seed: args.seed } : {},
12728
12773
  ...args.inputImage ? { inputImage: args.inputImage } : {},
12774
+ ...args.requireImageToVideo ? { requireImageToVideo: true } : {},
12775
+ ...args.aspectRatio ? { aspectRatio: args.aspectRatio } : {},
12729
12776
  ...args.saveAs ? { saveAs: args.saveAs } : {},
12730
12777
  projectId,
12731
12778
  ...gezelId ? { gezelId } : {},
@@ -12734,19 +12781,35 @@ server.tool(
12734
12781
  // the tool call (chat can't embed the clip itself).
12735
12782
  inline: true
12736
12783
  });
12737
- const { meta, artifactPath, workspacePath, b64Poster } = res;
12784
+ const { meta, artifactPath, workspacePath, b64Poster, posterPath, posterMimeType } = res;
12738
12785
  const workspaceLine = workspacePath ? `
12739
12786
 
12740
12787
  To display this video in HTML, copy this exact tag verbatim \u2014 do not add any prefix, do not change the filename:
12741
12788
  \`<video src="${workspacePath}" controls></video>\`` : "\n\nNOTE: workspace copy was skipped (project has an external workingDir not approved for writes).";
12742
- const summary = `Generated a ${meta.widthPx}\xD7${meta.heightPx} video with ${meta.model} (${meta.numFrames} frames @ ${meta.fps}fps, seed ${meta.seed}, ${meta.steps} steps, ${meta.durationMs}ms). The user sees the clip in an inline player below the tool call. The clip is at \`${artifactPath}\` \u2014 read its bytes with \`read_artifact\` if needed.${workspaceLine}`;
12789
+ const skipped = meta.i2vSkippedReason ? `
12790
+
12791
+ The picture was not used: ${meta.i2vSkippedReason}` : "";
12792
+ const notes = `${skipped}${meta.settingsNotes?.length ? `
12793
+
12794
+ ${meta.settingsNotes.join(" ")}` : ""}`;
12795
+ const summary = `Generated a ${meta.widthPx}\xD7${meta.heightPx} video with ${meta.model} (${meta.numFrames} frames @ ${meta.fps}fps, seed ${meta.seed}, ${meta.steps} steps, ${meta.durationMs}ms). The user sees the clip in an inline player below the tool call. The clip is at \`${artifactPath}\` \u2014 read its bytes with \`read_artifact\` if needed.${workspaceLine}${notes}`;
12743
12796
  const content = [{ type: "text", text: summary }];
12744
12797
  if (b64Poster) {
12745
- content.push({ type: "image", data: b64Poster, mimeType: "image/png" });
12798
+ content.push({
12799
+ type: "image",
12800
+ data: b64Poster,
12801
+ mimeType: posterMimeType ?? "image/png"
12802
+ });
12746
12803
  }
12747
12804
  return {
12748
12805
  content,
12749
- structuredContent: { gezelVideo: { artifactPath, mimeType: meta.mimeType } }
12806
+ structuredContent: {
12807
+ gezelVideo: {
12808
+ artifactPath,
12809
+ mimeType: meta.mimeType,
12810
+ ...posterPath ? { posterPath } : {}
12811
+ }
12812
+ }
12750
12813
  };
12751
12814
  } catch (err) {
12752
12815
  let msg = err instanceof Error ? err.message : String(err);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "1.2.14",
3
+ "version": "1.3.0",
4
4
  "description": "Gezel's Model Context Protocol server: gives gezels and other MCP clients access to memory, workspace files, artifacts, tasks, and team tools.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -56,8 +56,8 @@
56
56
  "!dist/**/*.map"
57
57
  ],
58
58
  "dependencies": {
59
- "@bendyline/gezel": "1.2.14",
60
- "@bendyline/gezel-client": "1.2.14",
59
+ "@bendyline/gezel": "1.3.0",
60
+ "@bendyline/gezel-client": "1.3.0",
61
61
  "@modelcontextprotocol/sdk": "1.32.2",
62
62
  "typescript": "^6.0.3",
63
63
  "zod": "4.6.7"