@bendyline/gezel-mcp 1.2.5 → 1.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +12 -3
  2. package/dist/server.js +110 -27
  3. package/package.json +4 -4
package/README.md CHANGED
@@ -1,13 +1,18 @@
1
1
  # @bendyline/gezel-mcp
2
2
 
3
3
  The [Model Context Protocol](https://modelcontextprotocol.io) server that gives
4
- [gezel](https://github.com/bendyline/gezel) agents their hands.
4
+ gezels, the AI companions in [Gezel](https://github.com/bendyline/gezel), their
5
+ hands.
5
6
 
6
7
  Every tool a gezel can call lives here: memory search and save, workspace file
7
8
  operations, project artifacts, the shared document library, script and
8
9
  Playwright execution, task management, team and project management, image
9
10
  rendering, and history search.
10
11
 
12
+ Gezel runs this server for every gezel's chat. You can also run it from any
13
+ other MCP client, so that client works with your gezels' memories, projects,
14
+ and tasks.
15
+
11
16
  ```bash
12
17
  npm install @bendyline/gezel-mcp
13
18
  ```
@@ -49,6 +54,10 @@ it, then reconnect the server from your MCP client.
49
54
  Run this way, the server acts with your own access, as the `gezel` command
50
55
  does; `GEZEL_PROJECT_ID` picks a default, not a boundary.
51
56
 
57
+ `gezel agent list` (from `@bendyline/gezel-cli`) lists your gezels and their
58
+ ids. The `agent` in that command and in `GEZEL_AGENT_ID` is a historical name:
59
+ both refer to your gezels.
60
+
52
61
  When Gezel starts the server itself, for a gezel's chat, it passes the
53
62
  connection directly: `GEZEL_BASE_URL`, `GEZEL_TOKEN` (a token it mints for that
54
63
  one session, confined to its project unless the gezel coordinates across
@@ -70,8 +79,8 @@ Run the server and call `tools/list` for the authoritative, current inventory.
70
79
  | Subpath | Contents |
71
80
  |---|---|
72
81
  | `@bendyline/gezel-mcp` | Server construction helpers |
73
- | `@bendyline/gezel-mcp/lint-contracts` | Tool-contract linting used by the eval harness |
74
- | `@bendyline/gezel-mcp/dist/server.js` | The stdio entry point. Resolved by string from `packages/service/src/chat/manager.ts` — removing this export makes chat sessions silently run with no tools |
82
+ | `@bendyline/gezel-mcp/lint-contracts` | The exact input and output schemas the built-in tools publish, for checking tool contracts |
83
+ | `@bendyline/gezel-mcp/dist/server.js` | The stdio server itself, also installed as the `gezel-mcp` command. The Gezel service launches this file for every chat, so it stays a supported path |
75
84
 
76
85
  ## Stability
77
86
 
package/dist/server.js CHANGED
@@ -43,12 +43,14 @@ import {
43
43
  findGezelInRoster,
44
44
  findProjectByReference,
45
45
  formatMediaClock,
46
+ gezelNamesInUse,
46
47
  gezelNotFoundMessage,
47
48
  gezelRosterHint,
48
49
  matchProjectTypeForBrief,
49
50
  normalizeArtifactPath,
50
51
  projectNotFoundMessage,
51
52
  projectTypeNamedByBrief,
53
+ projectTypesMentionedByBrief,
52
54
  roleWithGloss
53
55
  } from "@bendyline/gezel";
54
56
  import { readFileSync } from "fs";
@@ -104,7 +106,7 @@ import {
104
106
  messageGezelText,
105
107
  nearbyPathMatches,
106
108
  parseKnowledgeUri,
107
- pickRandomNameWithGender,
109
+ pickUnusedGezelName,
108
110
  prioritizePullsForCurrentBranch,
109
111
  readTaskNotesText,
110
112
  removeStepAndCleanEdges,
@@ -1238,15 +1240,29 @@ function buildTypedKickoffStep(input) {
1238
1240
  const goal = input.request ?? input.brief.taskDescription ?? input.brief.about;
1239
1241
  const unsaid = input.unsaid.length > 0 ? ` They have not said ${input.unsaid.map((t) => `"${t}"`).join(" or ")} yet; plan around it and ask for it in your reply.` : "";
1240
1242
  const known = input.known && input.known.length > 0 ? ` Already recorded from their words: ${input.known.map((k) => `"${k.title}" ${k.value}`).join(", ")}. Start on the plan itself, not on recording those again.` : "";
1241
- const where = input.dataFile ? ` The project's Output page shows \`${input.dataFile}\`, so make the first version there with this project's own tools; this step finishes when it has something in it.` : " Make the first version with this project's own tools.";
1243
+ const where = input.dataFile ? ` The project's Output page shows \`${input.dataFile}\`, so make the whole first version there with this project's own tools: every part of what they asked for (each day of a trip, each guest, each card), and every section the page has room for.` : " Make the whole first version with this project's own tools: every part of what they asked for.";
1242
1244
  const tools = input.tools && input.tools.length > 0 ? ` Your tools for it: ${input.tools.map(
1243
1245
  (t) => t.description ? `\`${t.name}\` (${t.description.replace(/\.$/, "")})` : `\`${t.name}\``
1244
1246
  ).join(", ")}. Call one for each piece rather than writing the file yourself.` : "";
1245
1247
  return {
1246
1248
  name: "First draft",
1247
- description: `You lead this ${input.typeName} project for the person. Their goal: ${goal}${where}${tools}${known}${unsaid} Make what they asked for; if something more would help, offer it in your reply instead of adding it. Do the real work this turn rather than describing it. Then reply in two or three sentences: what you made, and the one thing you need from them next.`
1249
+ description: `You lead this ${input.typeName} project for the person. Their goal: ${goal}${where}${tools}${known}${unsaid} Make what they asked for; if something more would help, offer it in your reply instead of adding it. Do the real work this turn rather than describing it, and finish it before you ask anything. Then reply in two or three sentences: what you made, and at most one question.`
1248
1250
  };
1249
1251
  }
1252
+ function typedKickoffWatch(type) {
1253
+ const files = /* @__PURE__ */ new Set();
1254
+ for (const read of type.pages?.reads ?? []) {
1255
+ if (read.source !== "workspace") continue;
1256
+ if (read.subtree) {
1257
+ for (const seeded of type.workspaceSeed ?? []) {
1258
+ if (seeded.startsWith(`${read.path}/`) && seeded.endsWith(".json")) files.add(seeded);
1259
+ }
1260
+ } else if (read.path.endsWith(".json")) {
1261
+ files.add(read.path);
1262
+ }
1263
+ }
1264
+ return [...files];
1265
+ }
1250
1266
  function kickoffTaskTitle(input) {
1251
1267
  return macroLooksLikeBuildMission(input.name, input.about, input.missionObjectives) ? `Build ${input.name}` : input.name;
1252
1268
  }
@@ -1337,6 +1353,8 @@ import {
1337
1353
  GEZEL_TOOL_DESCRIPTIONS,
1338
1354
  WORKSPACE_READ_MAX_FILES,
1339
1355
  WORKSPACE_READ_MAX_RANGE_LINES,
1356
+ cappedWorkspaceReadEnd,
1357
+ cappedWorkspaceReadRange,
1340
1358
  formatWorkspaceRead,
1341
1359
  renderExactToolCall,
1342
1360
  withLineNumbers,
@@ -1431,11 +1449,31 @@ Opened ${JSON.stringify(path)} as a binary office document and converted it to m
1431
1449
  return `[Rerouted ${requestedTool} \u2192 ${resolvedTool}]
1432
1450
  Opened ${surface} file ${JSON.stringify(path)}. Use ${surface === "artifact" ? "read_artifact/write_artifact" : "read_file/workspace write tools"} for subsequent operations on this path.`;
1433
1451
  }
1452
+ var BINARY_MEDIA_EXTENSIONS = new Set(
1453
+ "png jpg jpeg gif webp bmp ico avif tif tiff heic mp3 wav ogg flac m4a mp4 mov webm woff woff2 ttf otf zip gz".split(" ")
1454
+ );
1455
+ function binaryMediaExtension(path) {
1456
+ const ext = /\.([a-z0-9]+)$/i.exec(path.trim())?.[1]?.toLowerCase();
1457
+ return ext && BINARY_MEDIA_EXTENSIONS.has(ext) ? ext : null;
1458
+ }
1459
+ function binaryMediaReadResult(requestedTool, path, ext) {
1460
+ return {
1461
+ content: [
1462
+ {
1463
+ type: "text",
1464
+ text: `${requestedTool} "${path}": this is a binary ${ext.toUpperCase()} file, not text, so it was not read. Its bytes carry nothing you can use here; refer to the file by its path instead (for example in an <img> or <audio> element).`
1465
+ }
1466
+ ],
1467
+ structuredContent: { requestedTool, requestedPath: path, binary: true, extension: ext }
1468
+ };
1469
+ }
1434
1470
  async function rerouteBinaryDocumentRead(dependencies, path, surface) {
1435
1471
  const { api: api2, projectId: projectId2, toolIsAuthorized, unwrapApiError: unwrapApiError2 } = dependencies;
1436
- if (!isBinaryDocumentPath2(path)) return null;
1437
1472
  const artifact = surface === "artifact";
1438
1473
  const requestedTool = artifact ? "read_artifact" : "read_file";
1474
+ const media = binaryMediaExtension(path);
1475
+ if (media) return binaryMediaReadResult(requestedTool, path, media);
1476
+ if (!isBinaryDocumentPath2(path)) return null;
1439
1477
  const exactCall = renderExactToolCall("read_doc_as_markdown", {
1440
1478
  path,
1441
1479
  ...artifact ? { artifact: true } : {}
@@ -1503,7 +1541,8 @@ function registerWorkspaceReadTools(dependencies) {
1503
1541
  `1-based last line to return (inclusive). Maximum ${WORKSPACE_READ_MAX_RANGE_LINES} lines per ranged read; omit to read the next bounded chunk.`
1504
1542
  )
1505
1543
  }).shape,
1506
- async ({ path, startLine, endLine, raw }) => {
1544
+ async ({ path, startLine, endLine: requestedEndLine, raw }) => {
1545
+ const endLine = cappedWorkspaceReadEnd(startLine, requestedEndLine);
1507
1546
  try {
1508
1547
  const rerouted = await rerouteBinaryDocumentRead(dependencies, path, "workspace");
1509
1548
  if (rerouted) return rerouted;
@@ -1651,7 +1690,8 @@ ${body}` }],
1651
1690
  if (files === void 0 === (paths === void 0)) {
1652
1691
  throw new Error("pass exactly one of `paths` or `files`");
1653
1692
  }
1654
- const requests = files ?? paths?.map((path) => ({ path })) ?? [];
1693
+ const requested = files ?? paths?.map((path) => ({ path })) ?? [];
1694
+ const requests = requested.map(cappedWorkspaceReadRange);
1655
1695
  for (const request of requests) {
1656
1696
  const rangeError = workspaceReadRangeError(request);
1657
1697
  if (rangeError) throw new Error(`${request.path}: ${rangeError}`);
@@ -1827,7 +1867,13 @@ function registerArtifactReadTools(dependencies) {
1827
1867
  tail: z4.number().int().min(0).optional().describe("Legacy: read just the last N lines.")
1828
1868
  }).shape,
1829
1869
  async ({ path, startLine, endLine, lines, head, tail }) => {
1830
- const sliceArgs = { startLine, endLine, lines, head, tail };
1870
+ const sliceArgs = {
1871
+ startLine,
1872
+ endLine: cappedWorkspaceReadEnd(startLine, endLine),
1873
+ lines,
1874
+ head,
1875
+ tail
1876
+ };
1831
1877
  const sliceError = artifactSliceArgsError(sliceArgs);
1832
1878
  if (sliceError) return errorResult(`read_artifact "${path}": ${sliceError}`);
1833
1879
  const opts = artifactSliceOpts(sliceArgs);
@@ -1877,7 +1923,7 @@ function registerArtifactReadTools(dependencies) {
1877
1923
  } : typeof head === "number" ? { path: workspaceCollision.path, startLine: 1, endLine: Math.max(1, head) } : startLine !== void 0 || endLine !== void 0 ? {
1878
1924
  path: workspaceCollision.path,
1879
1925
  ...startLine !== void 0 ? { startLine } : {},
1880
- ...endLine !== void 0 ? { endLine } : {}
1926
+ ...sliceArgs.endLine !== void 0 ? { endLine: sliceArgs.endLine } : {}
1881
1927
  } : { path: workspaceCollision.path };
1882
1928
  if (request.startLine === void 0 && request.endLine === void 0) {
1883
1929
  const workspace = await readWorkspaceFile2(workspaceCollision.path);
@@ -2006,7 +2052,8 @@ ${result.candidates.map((candidate) => ` \u2022 ${candidate}`).join("\n")}`
2006
2052
  if (files === void 0 === (paths === void 0)) {
2007
2053
  return errorResult("read_artifacts failed: pass exactly one of `paths` or `files`");
2008
2054
  }
2009
- const requests = files ?? paths?.map((path) => ({ path })) ?? [];
2055
+ const requested = files ?? paths?.map((path) => ({ path })) ?? [];
2056
+ const requests = requested.map(cappedWorkspaceReadRange);
2010
2057
  for (const request of requests) {
2011
2058
  const rangeError = workspaceReadRangeError(request);
2012
2059
  if (rangeError) return errorResult(`read_artifacts failed: ${request.path}: ${rangeError}`);
@@ -2558,7 +2605,7 @@ function repoIntakeRedirect(input) {
2558
2605
  }
2559
2606
 
2560
2607
  // src/script-tools.ts
2561
- import { scriptRunText } from "@bendyline/gezel";
2608
+ import { scriptRunText, scriptToolArgs } from "@bendyline/gezel";
2562
2609
  import {
2563
2610
  ProjectTypeToolSchema
2564
2611
  } from "@bendyline/gezel";
@@ -2669,7 +2716,10 @@ function registerScriptTools(server2, specs, deps) {
2669
2716
  try {
2670
2717
  const res = await deps.api.runProjectScript(deps.projectId, {
2671
2718
  name: spec.script,
2672
- input: { ...args, ...spec.bind ?? {} }
2719
+ input: {
2720
+ ...scriptToolArgs(args, spec.inputs),
2721
+ ...spec.bind ?? {}
2722
+ }
2673
2723
  });
2674
2724
  return formatScriptRunResult(res);
2675
2725
  } catch (err) {
@@ -4186,6 +4236,10 @@ var sessionContextWindow = Number.isFinite(rawSessionContextWindow) && rawSessio
4186
4236
  var certPath = process.env.GEZEL_CERT_PATH;
4187
4237
  var fetchImpl = local?.fetch ?? (certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch());
4188
4238
  var api = new GezelClient({ baseUrl, token, fetch: fetchImpl });
4239
+ async function pickFreshGezelName() {
4240
+ const roster = await api.listGezels().then((response) => response.gezels).catch(() => []);
4241
+ return pickUnusedGezelName(gezelNamesInUse(roster));
4242
+ }
4189
4243
  var linkedFetchImpl = (input, init) => {
4190
4244
  const headers = new Headers(init?.headers);
4191
4245
  headers.set("x-gezel-linked-from", projectId);
@@ -4607,6 +4661,13 @@ server.tool(
4607
4661
  })
4608
4662
  });
4609
4663
  if (!res.ok) {
4664
+ const refusal = await personMemoryRefusal(res.clone());
4665
+ if (refusal) {
4666
+ return errorResult(`save_memory refused: ${refusal}`, {
4667
+ code: "person_memory_needs_user_turn",
4668
+ retryable: false
4669
+ });
4670
+ }
4610
4671
  return errorResult(`save_memory failed: ${await responseErrorMessage(res)}`);
4611
4672
  }
4612
4673
  const data = await res.json().catch(() => ({}));
@@ -6243,6 +6304,14 @@ function unwrapApiError(err) {
6243
6304
  const joined = joinErrorAndHint(err.details);
6244
6305
  return joined ?? message;
6245
6306
  }
6307
+ async function personMemoryRefusal(res) {
6308
+ try {
6309
+ const body = await res.json();
6310
+ return body.error === "person_memory_needs_user_turn" && typeof body.hint === "string" ? body.hint : null;
6311
+ } catch {
6312
+ return null;
6313
+ }
6314
+ }
6246
6315
  async function responseErrorMessage(res) {
6247
6316
  const body = await res.text().catch(() => "");
6248
6317
  if (body) {
@@ -7192,7 +7261,7 @@ server.tool(
7192
7261
  "create_gezel accepts either templateId or a custom about, not both. Omit about to use the template."
7193
7262
  );
7194
7263
  }
7195
- const { name, gender } = pickRandomNameWithGender();
7264
+ const { name, gender } = await pickFreshGezelName();
7196
7265
  const created = templateId ? await api.createGezelFromTemplate(templateId, { name, gender }) : await api.createGezel({
7197
7266
  name,
7198
7267
  gender,
@@ -8476,7 +8545,7 @@ server.tool(
8476
8545
  templateId: z6.string().describe('Template id from `list_gilde` (e.g. "voorman", "designer")')
8477
8546
  },
8478
8547
  async ({ templateId }) => {
8479
- const { name, gender } = pickRandomNameWithGender();
8548
+ const { name, gender } = await pickFreshGezelName();
8480
8549
  const created = await api.createGezelFromTemplate(templateId, { name, gender });
8481
8550
  return {
8482
8551
  content: [
@@ -9501,7 +9570,7 @@ ${idempotent.resultText}`
9501
9570
  mode: "crew",
9502
9571
  lead: "none"
9503
9572
  });
9504
- const { name: gezelName, gender: gezelGender } = pickRandomNameWithGender();
9573
+ const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
9505
9574
  const voorman = await api.createGezelFromTemplate("voorman", {
9506
9575
  name: gezelName,
9507
9576
  gender: gezelGender
@@ -9573,7 +9642,7 @@ ${idempotent.resultText}`
9573
9642
  mode: "crew",
9574
9643
  lead: "none"
9575
9644
  });
9576
- const { name: gezelName, gender: gezelGender } = pickRandomNameWithGender();
9645
+ const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
9577
9646
  const voorman = await api.createGezelFromTemplate("voorman", {
9578
9647
  name: gezelName,
9579
9648
  gender: gezelGender
@@ -9648,7 +9717,7 @@ async function routeBriefToProjectType(brief) {
9648
9717
  const types = await listRoutableProjectTypes();
9649
9718
  const said = await personsLatestRequest();
9650
9719
  const fromSaid = said ? matchProjectTypeForBrief(said, types) : null;
9651
- const match = fromSaid && fromSaid.typeId === projectTypeNamedByBrief(text, types) ? fromSaid : matchProjectTypeForBrief(text, types);
9720
+ const match = fromSaid && (fromSaid.typeId === projectTypeNamedByBrief(text, types) || projectTypesMentionedByBrief(text, types).includes(fromSaid.typeId)) ? fromSaid : matchProjectTypeForBrief(text, types);
9652
9721
  const type = match ? types.find((t) => t.id === match.typeId) : void 0;
9653
9722
  return match && type ? { match, type } : null;
9654
9723
  } catch {
@@ -9726,15 +9795,28 @@ ${idempotent.resultText}`
9726
9795
  const crew = created.applied.gezelsCreated;
9727
9796
  const lead = crew.find((g) => g.voorman) ?? crew[0];
9728
9797
  if (!lead) return startedWithoutTask("the project type recruited no lead");
9729
- let advanceWhen;
9730
- if (match.dataFile) {
9731
- const seed = await api.readProjectWorkspaceFile(project.id, match.dataFile).catch(() => null);
9732
- advanceWhen = {
9733
- file: match.dataFile,
9734
- minBytes: (seed?.content.length ?? 0) + TYPED_KICKOFF_MIN_GROWTH_BYTES,
9735
- requireChange: false
9736
- };
9737
- }
9798
+ const watch = typedKickoffWatch(type);
9799
+ const watched = watch.length > 0 ? watch : match.dataFile ? [match.dataFile] : [];
9800
+ const seeds = await Promise.all(
9801
+ watched.map(
9802
+ (file) => api.readProjectWorkspaceFile(project.id, file).then((seed) => seed.content.length).catch(() => 0)
9803
+ )
9804
+ );
9805
+ const advanceWhen = watched[0] !== void 0 ? {
9806
+ file: watched[0],
9807
+ minBytes: (seeds[0] ?? 0) + TYPED_KICKOFF_MIN_GROWTH_BYTES,
9808
+ requireChange: false
9809
+ } : void 0;
9810
+ const gate = watched.length > 0 ? {
9811
+ at: "completion",
9812
+ checks: [
9813
+ {
9814
+ kind: "totalMinBytes",
9815
+ files: watched,
9816
+ bytes: seeds.reduce((sum, n) => sum + n, 0) + TYPED_KICKOFF_MIN_GROWTH_BYTES
9817
+ }
9818
+ ]
9819
+ } : void 0;
9738
9820
  const known = Object.entries(match.params).filter(([key, value]) => !match.assumed.includes(key) && value.trim().length > 0).map(([key, value]) => ({ title: type.params?.properties?.[key]?.title ?? key, value }));
9739
9821
  const request = await personsRequestFor(type.id);
9740
9822
  const step = buildTypedKickoffStep({
@@ -9761,6 +9843,7 @@ Note from the meester: ${opts.kickoffMessage.trim()}` : "";
9761
9843
  ...step,
9762
9844
  assignee: { kind: "gezel", gezelId: lead.id },
9763
9845
  ...advanceWhen ? { advanceWhen } : {},
9846
+ ...gate ? { gate } : {},
9764
9847
  // The page's data is written through the type's tools, in the shape
9765
9848
  // the page reads; the file tools would let the lead invent one.
9766
9849
  toolPolicy: { outputMedium: "none", disallowBuiltinToolsets: ["workspace-fs-write"] }
@@ -9852,7 +9935,7 @@ ${idempotent.resultText}`
9852
9935
  mode: "crew",
9853
9936
  lead: "none"
9854
9937
  });
9855
- const { name: gezelName, gender: gezelGender } = pickRandomNameWithGender();
9938
+ const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
9856
9939
  const voorman = await api.createGezelFromTemplate("voorman", {
9857
9940
  name: gezelName,
9858
9941
  gender: gezelGender
@@ -9997,7 +10080,7 @@ ${idempotent.resultText}`
9997
10080
  missionObjectives: normalizeMarkdown(brief.missionObjectives),
9998
10081
  mode: "solo"
9999
10082
  });
10000
- const { name: gezelName, gender: gezelGender } = pickRandomNameWithGender();
10083
+ const { name: gezelName, gender: gezelGender } = await pickFreshGezelName();
10001
10084
  const builder = await api.createGezelFromTemplate(effectiveSpecialistRole, {
10002
10085
  name: gezelName,
10003
10086
  gender: gezelGender
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "1.2.5",
4
- "description": "Gezel MCP server — gives agents access to memory, workspace, artifacts, and tools.",
3
+ "version": "1.2.6",
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": [
7
7
  "gezel",
@@ -55,8 +55,8 @@
55
55
  "!dist/**/*.map"
56
56
  ],
57
57
  "dependencies": {
58
- "@bendyline/gezel": "1.2.5",
59
- "@bendyline/gezel-client": "1.2.5",
58
+ "@bendyline/gezel": "1.2.6",
59
+ "@bendyline/gezel-client": "1.2.6",
60
60
  "@modelcontextprotocol/sdk": "1.31.0",
61
61
  "typescript": "^6.0.3",
62
62
  "zod": "^4.4.3"