@bendyline/gezel-mcp 1.2.13 → 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/harness.js CHANGED
@@ -90,7 +90,7 @@ import { z as z3 } from "zod";
90
90
 
91
91
  // src/harness/docblocks-tools.json
92
92
  var docblocks_tools_default = {
93
- docblocksVersion: "2.7.5",
93
+ docblocksVersion: "2.7.13",
94
94
  tools: [
95
95
  {
96
96
  name: "convert_document",
@@ -842,21 +842,25 @@ var docblocks_tools_default = {
842
842
  type: "string",
843
843
  minLength: 1,
844
844
  maxLength: 256,
845
- pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
845
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
846
+ description: "A write root id from list_roots."
846
847
  },
847
848
  path: {
848
849
  type: "string",
849
850
  minLength: 1,
850
851
  maxLength: 4096,
851
- pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
852
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$",
853
+ description: "Path below that root."
852
854
  },
853
855
  ifExists: {
854
856
  type: "string",
855
- const: "error"
857
+ const: "error",
858
+ description: "Create the file; fails if one is already there."
856
859
  },
857
860
  expectedSha256: {
858
861
  type: "null",
859
- default: null
862
+ default: null,
863
+ description: "Omit or null when creating a file."
860
864
  }
861
865
  },
862
866
  required: ["rootId", "path", "ifExists"],
@@ -866,18 +870,25 @@ var docblocks_tools_default = {
866
870
  type: "object",
867
871
  properties: {
868
872
  rootId: {
869
- $ref: "#/properties/destination/anyOf/0/properties/rootId"
873
+ type: "string",
874
+ minLength: 1,
875
+ maxLength: 256,
876
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
877
+ description: "A write root id from list_roots."
870
878
  },
871
879
  path: {
872
- $ref: "#/properties/destination/anyOf/0/properties/path"
880
+ $ref: "#/properties/destination/anyOf/0/properties/path",
881
+ description: "Path below that root."
873
882
  },
874
883
  ifExists: {
875
884
  type: "string",
876
- const: "replace"
885
+ const: "replace",
886
+ description: "Replace the file already at this path; fails if nothing is there."
877
887
  },
878
888
  expectedSha256: {
879
889
  type: "string",
880
- pattern: "^[a-f0-9]{64}$"
890
+ pattern: "^[a-f0-9]{64}$",
891
+ description: "SHA-256 of the file now at this path (the sha256 returned when it was saved), not of the artifact being saved."
881
892
  }
882
893
  },
883
894
  required: ["rootId", "path", "ifExists", "expectedSha256"],
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() ? `
@@ -3838,10 +3861,20 @@ function taskStepMutationRejection(scope) {
3838
3861
  return `Step "${sessionStepId2}" on ${taskRef} no longer owns project writes.${active} ${yieldTo} Do not rewrite, append to, move, or delete the completed step's deliverable.`;
3839
3862
  }
3840
3863
  function staleTaskStepRefusal(err) {
3864
+ return daemonRefusal(err, "stale_task_step");
3865
+ }
3866
+ function checkInTurnRefusal(err) {
3867
+ return daemonRefusal(err, "check_in_turn");
3868
+ }
3869
+ function checkInTurnResult(err) {
3870
+ const hint = checkInTurnRefusal(err);
3871
+ return hint ? errorResult(hint, { code: "check_in_turn", retryable: false }) : null;
3872
+ }
3873
+ function daemonRefusal(err, code) {
3841
3874
  const details = err?.details;
3842
3875
  if (!details || typeof details !== "object") return null;
3843
3876
  const { error, hint } = details;
3844
- return error === "stale_task_step" && typeof hint === "string" && hint.trim() ? hint : null;
3877
+ return error === code && typeof hint === "string" && hint.trim() ? hint : null;
3845
3878
  }
3846
3879
  function sessionReboundToCurrentPass(args) {
3847
3880
  return args.activeStepId === args.sessionStepId && !!args.activeStepActivation && args.sessionActivation === args.activeStepActivation;
@@ -4907,6 +4940,11 @@ var sessionContextWindow = Number.isFinite(rawSessionContextWindow) && rawSessio
4907
4940
  var certPath = process.env.GEZEL_CERT_PATH;
4908
4941
  var fetchImpl = local?.fetch ?? (certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch());
4909
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
+ }
4910
4948
  var { resolveProjectId, resolveGezelId, availableGezelsHint, parseRef } = createEntityResolvers({
4911
4949
  api,
4912
4950
  projectId,
@@ -5805,6 +5843,7 @@ async function fetchRepoReviewNextHint(projectId2) {
5805
5843
  }
5806
5844
  async function handoffFetchedRepoReview(projectId2) {
5807
5845
  const reviewer = await api.ensureGezel({ jobTitle: "Code Reviewer" });
5846
+ if (reviewer.action !== "reused") introduceHires(reviewer.gezelId);
5808
5847
  const message = await fetchRepoReviewHandoffMessage(projectId2);
5809
5848
  const res = await api.messageGezel(reviewer.gezelId, {
5810
5849
  fromGezelId: gezelId,
@@ -8003,6 +8042,7 @@ server.tool(
8003
8042
  ...templateId && model ? { model } : {}
8004
8043
  });
8005
8044
  }
8045
+ introduceHires(created.id);
8006
8046
  return {
8007
8047
  content: [
8008
8048
  {
@@ -8061,7 +8101,7 @@ server.tool(
8061
8101
  content: [
8062
8102
  {
8063
8103
  type: "text",
8064
- 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).`
8065
8105
  }
8066
8106
  ]
8067
8107
  };
@@ -8363,9 +8403,11 @@ async function currentRootTurnContext() {
8363
8403
  return null;
8364
8404
  }
8365
8405
  const latestUser = [...session.messages].reverse().find((message) => message.role === "user");
8406
+ const requestTitle = requestedTaskTitle(void 0, session.messages);
8366
8407
  return {
8367
8408
  rootTurnId,
8368
- ...latestUser?.content.trim() ? { userText: latestUser.content.trim() } : {}
8409
+ ...latestUser?.content.trim() ? { userText: latestUser.content.trim() } : {},
8410
+ ...requestTitle ? { requestTitle } : {}
8369
8411
  };
8370
8412
  } catch (err) {
8371
8413
  process.stderr.write(
@@ -8658,7 +8700,7 @@ server.tool(
8658
8700
  project: z8.string().optional().describe(
8659
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."
8660
8702
  ),
8661
- 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."),
8662
8704
  description: z8.string().optional().describe(
8663
8705
  "Optional task description \u2014 the job-to-be-done. Falls back to the craftbook description when omitted."
8664
8706
  ),
@@ -8701,10 +8743,12 @@ async function runInvokeCraftbook({
8701
8743
  ...tonight ? { tonight: true } : {}
8702
8744
  };
8703
8745
  const rootTurnId = rootTurn?.rootTurnId ?? null;
8704
- const launchInvocation = rootTurnId ? {
8746
+ const taskTitle = title?.trim() || rootTurn?.requestTitle;
8747
+ const launchInvocation = {
8705
8748
  ...invocation,
8706
- craftbookInvocationKey: rootTurnInvocationKey(rootTurnId, invocation)
8707
- } : invocation;
8749
+ ...taskTitle ? { title: taskTitle } : {},
8750
+ ...rootTurnId ? { craftbookInvocationKey: rootTurnInvocationKey(rootTurnId, invocation) } : {}
8751
+ };
8708
8752
  const launched = rootTurnId ? await invokeCraftbookRootTurnCache.run({
8709
8753
  rootTurnId,
8710
8754
  invocation,
@@ -8748,6 +8792,8 @@ async function runInvokeCraftbook({
8748
8792
  }
8749
8793
  );
8750
8794
  } catch (err) {
8795
+ const checkIn = checkInTurnResult(err);
8796
+ if (checkIn) return checkIn;
8751
8797
  const details = err.details;
8752
8798
  if (details?.code === "task-input" && typeof details.param === "string") {
8753
8799
  const paramSchema = await api.listProjectCraftbooks(resolvedProject).then((listing) => {
@@ -9304,6 +9350,7 @@ server.tool(
9304
9350
  const res = await api.ensureGezel({
9305
9351
  jobTitle
9306
9352
  });
9353
+ if (res.action !== "reused") introduceHires(res.gezelId);
9307
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`;
9308
9355
  const tail = res.alternatives && res.alternatives.length > 0 ? `
9309
9356
  Runner-ups on the roster: ${res.alternatives.join(", ")}. If ${res.name} is wrong, pass a more specific \`jobTitle\` next time.` : "";
@@ -9332,6 +9379,7 @@ server.tool(
9332
9379
  async ({ templateId }) => {
9333
9380
  const { name, gender } = await pickFreshGezelName();
9334
9381
  const created = await api.createGezelFromTemplate(templateId, { name, gender });
9382
+ introduceHires(created.id);
9335
9383
  return {
9336
9384
  content: [
9337
9385
  {
@@ -9690,6 +9738,7 @@ server.tool(
9690
9738
  const ensured = await api.ensureGezel({
9691
9739
  jobTitle
9692
9740
  });
9741
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9693
9742
  if (ensured.gezelId === gezelId) {
9694
9743
  return {
9695
9744
  content: [
@@ -9870,6 +9919,7 @@ ${expectedDeliverable?.kind === "file" ? expectedDeliverable.filePath ?? "" : ""
9870
9919
  });
9871
9920
  if (repoGuard) return repoGuard;
9872
9921
  const ensured = await api.ensureGezel({ jobTitle });
9922
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9873
9923
  const normalizedMessage = normalizeFileHandoffMessage(task, expectedDeliverable);
9874
9924
  const res = await api.messageGezel(ensured.gezelId, {
9875
9925
  fromGezelId: gezelId,
@@ -9939,6 +9989,7 @@ ${expectedDeliverable?.kind === "file" ? expectedDeliverable.filePath ?? "" : ""
9939
9989
  });
9940
9990
  if (repoGuard) return repoGuard;
9941
9991
  const ensured = await api.ensureGezel({ jobTitle });
9992
+ if (ensured.action !== "reused") introduceHires(ensured.gezelId);
9942
9993
  if (ensured.gezelId === gezelId) {
9943
9994
  return {
9944
9995
  content: [
@@ -10122,15 +10173,17 @@ ${fallbackSentence}`;
10122
10173
  var SPECIALIST_TEMPLATE_IDS = {
10123
10174
  "image-generator": "illustrator"
10124
10175
  };
10125
- async function createSpecialistFromTemplate(role, identity) {
10126
- const preferred = SPECIALIST_TEMPLATE_IDS[role];
10127
- if (preferred) {
10128
- try {
10129
- return { ...await api.createGezelFromTemplate(preferred, identity), templateId: preferred };
10130
- } catch {
10131
- }
10132
- }
10133
- 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}`;
10134
10187
  }
10135
10188
  function normalizeSpecialistRole(value) {
10136
10189
  const lower = value?.trim().toLowerCase() ?? "";
@@ -10363,11 +10416,7 @@ ${idempotent.resultText}`
10363
10416
  mode: "crew",
10364
10417
  lead: "none"
10365
10418
  });
10366
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10367
- const voorman = await api.createGezelFromTemplate("voorman", {
10368
- name: gezelName,
10369
- gender: gezelGender
10370
- });
10419
+ const voorman = await ensureMainGezel("voorman");
10371
10420
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10372
10421
  const effectiveTaskDescription = buildBinaryDocumentTaskDescription(
10373
10422
  {
@@ -10435,11 +10484,7 @@ ${idempotent.resultText}`
10435
10484
  mode: "crew",
10436
10485
  lead: "none"
10437
10486
  });
10438
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10439
- const voorman = await api.createGezelFromTemplate("voorman", {
10440
- name: gezelName,
10441
- gender: gezelGender
10442
- });
10487
+ const voorman = await ensureMainGezel("voorman");
10443
10488
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10444
10489
  const effectiveTaskDescription = buildKickoffTaskDescription({
10445
10490
  ...brief,
@@ -10476,7 +10521,7 @@ ${idempotent.resultText}`
10476
10521
  dispatchEntry: true
10477
10522
  });
10478
10523
  const entryName = await macroEntryAssigneeName(task, voorman.id, voorman.name);
10479
- 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}`;
10480
10525
  recordMacroResult("start_project", brief.name, project.id, resultText);
10481
10526
  return {
10482
10527
  content: [
@@ -10724,11 +10769,7 @@ ${idempotent.resultText}`
10724
10769
  mode: "crew",
10725
10770
  lead: "none"
10726
10771
  });
10727
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10728
- const voorman = await api.createGezelFromTemplate("voorman", {
10729
- name: gezelName,
10730
- gender: gezelGender
10731
- });
10772
+ const voorman = await ensureMainGezel("voorman");
10732
10773
  await api.updateProject(project.id, { voormanGezelId: voorman.id });
10733
10774
  const effectiveTaskDescription = buildKickoffTaskDescription({
10734
10775
  ...brief,
@@ -10767,7 +10808,7 @@ ${idempotent.resultText}`
10767
10808
  dispatchEntry: true
10768
10809
  });
10769
10810
  const entryName = await macroEntryAssigneeName(task, voorman.id, voorman.name);
10770
- 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}`;
10771
10812
  recordMacroResult(tool, brief.name, project.id, resultText);
10772
10813
  return {
10773
10814
  content: [
@@ -10803,7 +10844,7 @@ async function personsRoutingRequest() {
10803
10844
  ).map((m) => m.content.trim());
10804
10845
  const latest = said.at(-1);
10805
10846
  if (!latest) return void 0;
10806
- 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;
10807
10848
  return routingRequestText(latest, previous);
10808
10849
  } catch {
10809
10850
  return void 0;
@@ -11103,11 +11144,10 @@ ${idempotent.resultText}`
11103
11144
  missionObjectives: normalizeMarkdown(brief.missionObjectives),
11104
11145
  mode: "solo"
11105
11146
  });
11106
- const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
11107
- const builder = await createSpecialistFromTemplate(effectiveSpecialistRole, {
11108
- name: gezelName,
11109
- gender: gezelGender
11110
- });
11147
+ const builder = await ensureMainGezel(
11148
+ SPECIALIST_TEMPLATE_IDS[effectiveSpecialistRole] ?? effectiveSpecialistRole,
11149
+ effectiveSpecialistRole
11150
+ );
11111
11151
  await api.updateProject(project.id, { voormanGezelId: builder.id });
11112
11152
  const effectiveTaskDescription = buildKickoffTaskDescription({
11113
11153
  ...brief,
@@ -11147,7 +11187,7 @@ ${idempotent.resultText}`
11147
11187
  ],
11148
11188
  dispatchEntry: true
11149
11189
  });
11150
- 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}`;
11151
11191
  recordMacroResult(cacheTool, brief.name, project.id, resultText);
11152
11192
  return {
11153
11193
  content: [
@@ -11589,7 +11629,7 @@ server.tool(
11589
11629
  { text }
11590
11630
  );
11591
11631
  } catch (err) {
11592
- return errorResult(`create_task failed: ${unwrapApiError(err)}`);
11632
+ return checkInTurnResult(err) ?? errorResult(`create_task failed: ${unwrapApiError(err)}`);
11593
11633
  }
11594
11634
  }
11595
11635
  );
@@ -12404,7 +12444,7 @@ ${lines.join("\n")}` : summary }
12404
12444
  );
12405
12445
  server.tool(
12406
12446
  "how_do_i",
12407
- "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.",
12408
12448
  {
12409
12449
  question: z8.string().min(2).describe('Plain-language question, e.g. "how do I give a gezel a different model?"'),
12410
12450
  limit: z8.number().optional().describe("Max articles to return (default 2)")
@@ -12416,7 +12456,7 @@ server.tool(
12416
12456
  content: [
12417
12457
  {
12418
12458
  type: "text",
12419
- 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."
12420
12460
  }
12421
12461
  ]
12422
12462
  };
@@ -12648,7 +12688,7 @@ If you are working on a website/logo task and an HTML file already exists, your
12648
12688
  const styleLine = appliedStyle ? ` Style: ${appliedStyle.name}.` : "";
12649
12689
  const stylesLine = styles?.length && !imageStylesShown.has(meta.model) ? ` Styles this model has: ${styles.map((s) => s.name).join(", ")}.` : "";
12650
12690
  if (styles?.length) imageStylesShown.add(meta.model);
12651
- 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}`;
12652
12692
  const content = [{ type: "text", text: summary }];
12653
12693
  if (b64Png) {
12654
12694
  content.push({ type: "image", data: b64Png, mimeType: "image/png" });
@@ -12673,9 +12713,20 @@ If you are working on a website/logo task and an HTML file already exists, your
12673
12713
  }
12674
12714
  }
12675
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
+ }
12676
12727
  server.tool(
12677
12728
  "generate_video",
12678
- "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.",
12679
12730
  {
12680
12731
  prompt: z8.string().min(1).describe("What the video should depict."),
12681
12732
  negativePrompt: z8.string().optional().describe("Concepts to avoid."),
@@ -12696,7 +12747,13 @@ server.tool(
12696
12747
  data: z8.string().min(1).describe("Base64-encoded image bytes."),
12697
12748
  mimeType: z8.string().default("image/png")
12698
12749
  })
12699
- ]).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."),
12700
12757
  saveAs: z8.string().optional().describe(
12701
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."
12702
12759
  )
@@ -12714,6 +12771,8 @@ server.tool(
12714
12771
  ...args.steps ? { steps: args.steps } : {},
12715
12772
  ...args.seed !== void 0 ? { seed: args.seed } : {},
12716
12773
  ...args.inputImage ? { inputImage: args.inputImage } : {},
12774
+ ...args.requireImageToVideo ? { requireImageToVideo: true } : {},
12775
+ ...args.aspectRatio ? { aspectRatio: args.aspectRatio } : {},
12717
12776
  ...args.saveAs ? { saveAs: args.saveAs } : {},
12718
12777
  projectId,
12719
12778
  ...gezelId ? { gezelId } : {},
@@ -12722,19 +12781,35 @@ server.tool(
12722
12781
  // the tool call (chat can't embed the clip itself).
12723
12782
  inline: true
12724
12783
  });
12725
- const { meta, artifactPath, workspacePath, b64Poster } = res;
12784
+ const { meta, artifactPath, workspacePath, b64Poster, posterPath, posterMimeType } = res;
12726
12785
  const workspaceLine = workspacePath ? `
12727
12786
 
12728
12787
  To display this video in HTML, copy this exact tag verbatim \u2014 do not add any prefix, do not change the filename:
12729
12788
  \`<video src="${workspacePath}" controls></video>\`` : "\n\nNOTE: workspace copy was skipped (project has an external workingDir not approved for writes).";
12730
- 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}`;
12731
12796
  const content = [{ type: "text", text: summary }];
12732
12797
  if (b64Poster) {
12733
- content.push({ type: "image", data: b64Poster, mimeType: "image/png" });
12798
+ content.push({
12799
+ type: "image",
12800
+ data: b64Poster,
12801
+ mimeType: posterMimeType ?? "image/png"
12802
+ });
12734
12803
  }
12735
12804
  return {
12736
12805
  content,
12737
- structuredContent: { gezelVideo: { artifactPath, mimeType: meta.mimeType } }
12806
+ structuredContent: {
12807
+ gezelVideo: {
12808
+ artifactPath,
12809
+ mimeType: meta.mimeType,
12810
+ ...posterPath ? { posterPath } : {}
12811
+ }
12812
+ }
12738
12813
  };
12739
12814
  } catch (err) {
12740
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.13",
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.13",
60
- "@bendyline/gezel-client": "1.2.13",
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"