@bendyline/gezel-mcp 1.2.1 → 1.2.2

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 +29 -8
  2. package/dist/server.js +140 -31
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -12,7 +12,8 @@ rendering, and history search.
12
12
  npm install @bendyline/gezel-mcp
13
13
  ```
14
14
 
15
- It speaks stdio, so any MCP client can run it:
15
+ It speaks stdio, so any MCP client can run it. With Gezel running on the same
16
+ computer:
16
17
 
17
18
  ```json
18
19
  {
@@ -21,9 +22,7 @@ It speaks stdio, so any MCP client can run it:
21
22
  "command": "npx",
22
23
  "args": ["-y", "@bendyline/gezel-mcp"],
23
24
  "env": {
24
- "GEZEL_BASE_URL": "https://127.0.0.1:8080",
25
- "GEZEL_TOKEN": "…",
26
- "GEZEL_AGENT_ID": "…",
25
+ "GEZEL_AGENT_ID": "<a gezel id from `gezel agent list`>",
27
26
  "GEZEL_PROJECT_ID": "default"
28
27
  }
29
28
  }
@@ -31,10 +30,32 @@ It speaks stdio, so any MCP client can run it:
31
30
  }
32
31
  ```
33
32
 
34
- The server is a thin front end: it calls back into a running `gezeld` over
35
- HTTP using the environment variables above. It runs as a child process with a
36
- fresh Node environment, so those variables are its only connection to the
37
- service — nothing else is inherited implicitly.
33
+ There is no address, password, or certificate to configure. The server is a
34
+ thin front end that calls back into the running Gezel service, and finds it on
35
+ its own: Gezel picks its port, its sign-in token, and its TLS certificate at
36
+ each launch and writes them to `~/.gezel/runtime/` (`port`, `auth-token`,
37
+ `cert.pem`), readable only by you. The server reads them when it starts and
38
+ follows Gezel across a restart, so a long-lived MCP client keeps working after
39
+ Gezel updates. If Gezel is not running when the client starts the server, it
40
+ exits with a message saying to open the Gezel app or run `gezel start`; start
41
+ it, then reconnect the server from your MCP client.
42
+
43
+ | Variable | |
44
+ |---|---|
45
+ | `GEZEL_AGENT_ID` | The gezel the tools work as: whose memories they search and save, whose tasks they see. |
46
+ | `GEZEL_PROJECT_ID` | The project tools use when a call names none. Default `default`. |
47
+ | `GEZEL_HOME` | A Gezel home other than `~/.gezel`. |
48
+
49
+ Run this way, the server acts with your own access, as the `gezel` command
50
+ does; `GEZEL_PROJECT_ID` picks a default, not a boundary.
51
+
52
+ When Gezel starts the server itself, for a gezel's chat, it passes the
53
+ connection directly: `GEZEL_BASE_URL`, `GEZEL_TOKEN` (a token it mints for that
54
+ one session, confined to its project unless the gezel coordinates across
55
+ projects), and `GEZEL_CERT_PATH` (the
56
+ `runtime/cert.pem` that token's service is using). Setting `GEZEL_BASE_URL`
57
+ yourself turns the lookup off, and keeping all three current across restarts
58
+ is then up to you.
38
59
 
39
60
  ## Tool categories
40
61
 
package/dist/server.js CHANGED
@@ -68,6 +68,7 @@ import {
68
68
  composeCraftbookLaunch,
69
69
  craftbookDocFormatFromEnv,
70
70
  createTaskText,
71
+ crewMemberNamedIn,
71
72
  deliverableStep,
72
73
  deniedTaskScopedWrite,
73
74
  expandStepDeliverable,
@@ -76,10 +77,12 @@ import {
76
77
  getScriptRunText,
77
78
  getTaskText,
78
79
  inferDeliverableKind,
80
+ inferScriptScope,
79
81
  isReservedShadowArtifactPath,
80
82
  isSafeEntityId,
81
83
  isTrustedConstrainedToolset,
82
84
  listArtifactsText,
85
+ listDirMissingText,
83
86
  listDirText,
84
87
  listDocumentsText,
85
88
  listGezelsText,
@@ -89,6 +92,7 @@ import {
89
92
  listScriptsText,
90
93
  listTasksText,
91
94
  messageGezelText,
95
+ nearbyPathMatches,
92
96
  parseKnowledgeUri,
93
97
  pickRandomNameWithGender,
94
98
  prioritizePullsForCurrentBranch,
@@ -100,15 +104,21 @@ import {
100
104
  saveMemoryText,
101
105
  searchMemoryText,
102
106
  searchResultText,
107
+ stepCheckedArtifactPaths,
103
108
  stepInsertionIndex,
104
109
  stepOwnerGezelId,
105
110
  taskOwnedPrefixes,
106
111
  taskScopedWriteDeniedMessage,
107
112
  uniqueStepId,
113
+ workspaceDrawerPrefix,
108
114
  writeTaskNoteText
109
115
  } from "@bendyline/gezel";
110
116
  import { GezelApiError, GezelClient } from "@bendyline/gezel-client";
111
- import { createPatientFetch, createTrustingFetch } from "@bendyline/gezel-client/node";
117
+ import {
118
+ connectToLocalGezel,
119
+ createPatientFetch,
120
+ createTrustingFetch
121
+ } from "@bendyline/gezel-client/node";
112
122
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
113
123
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
114
124
  import { z as z5 } from "zod";
@@ -2647,6 +2657,12 @@ function taskStepMutationRejection(scope) {
2647
2657
  const yieldTo = activeStepId && scope.activeStepOwnedBySession ? `That step is yours as well: end this turn now, and the runtime re-engages you with the "${activeStepId}" procedure in front of you.` : "Stop this turn and yield to the active step's gezel.";
2648
2658
  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.`;
2649
2659
  }
2660
+ function staleTaskStepRefusal(err) {
2661
+ const details = err?.details;
2662
+ if (!details || typeof details !== "object") return null;
2663
+ const { error, hint } = details;
2664
+ return error === "stale_task_step" && typeof hint === "string" && hint.trim() ? hint : null;
2665
+ }
2650
2666
 
2651
2667
  // src/validate.ts
2652
2668
  import ts2 from "typescript";
@@ -3677,8 +3693,19 @@ function containsLooseJavascript(text) {
3677
3693
  }
3678
3694
 
3679
3695
  // src/server.ts
3680
- var baseUrl = process.env.GEZEL_BASE_URL ?? "http://127.0.0.1:0";
3681
- var token = process.env.GEZEL_TOKEN ?? "";
3696
+ async function localGezelUnlessSpawned() {
3697
+ if (process.env.GEZEL_BASE_URL || process.env.GEZEL_MCP_NO_MAIN === "1") return null;
3698
+ try {
3699
+ return await connectToLocalGezel();
3700
+ } catch (err) {
3701
+ process.stderr.write(`gezel-mcp: ${err instanceof Error ? err.message : String(err)}
3702
+ `);
3703
+ process.exit(1);
3704
+ }
3705
+ }
3706
+ var local = await localGezelUnlessSpawned();
3707
+ var baseUrl = local?.baseUrl ?? process.env.GEZEL_BASE_URL ?? "http://127.0.0.1:0";
3708
+ var token = local?.token ?? process.env.GEZEL_TOKEN ?? "";
3682
3709
  var gezelId = process.env.GEZEL_AGENT_ID ?? "";
3683
3710
  var projectId = process.env.GEZEL_PROJECT_ID ?? "default";
3684
3711
  var sessionId = process.env.GEZEL_SESSION_ID ?? "";
@@ -3693,7 +3720,7 @@ var sessionCraftbookId = process.env.GEZEL_CRAFTBOOK_ID ?? "";
3693
3720
  var rawSessionContextWindow = Number(process.env.GEZEL_CONTEXT_WINDOW ?? "");
3694
3721
  var sessionContextWindow = Number.isFinite(rawSessionContextWindow) && rawSessionContextWindow > 0 ? rawSessionContextWindow : void 0;
3695
3722
  var certPath = process.env.GEZEL_CERT_PATH;
3696
- var fetchImpl = certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch();
3723
+ var fetchImpl = local?.fetch ?? (certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch());
3697
3724
  var api = new GezelClient({ baseUrl, token, fetch: fetchImpl });
3698
3725
  var linkedFetchImpl = (input, init) => {
3699
3726
  const headers = new Headers(init?.headers);
@@ -3703,9 +3730,11 @@ var linkedFetchImpl = (input, init) => {
3703
3730
  var linkedApi = new GezelClient({ baseUrl, token, fetch: linkedFetchImpl });
3704
3731
  var sessionStepCompleted = false;
3705
3732
  var sessionStepCompletion = "unknown";
3733
+ var sessionStepCheckedArtifacts = [];
3706
3734
  async function staleStepMutationResult() {
3707
3735
  if (!sessionTaskRef || !sessionStepId) return null;
3708
3736
  sessionStepCompletion = "unknown";
3737
+ sessionStepCheckedArtifacts = [];
3709
3738
  let activeStepId;
3710
3739
  let activeStepOwnedBySession = false;
3711
3740
  if (!sessionStepCompleted) {
@@ -3716,6 +3745,7 @@ async function staleStepMutationResult() {
3716
3745
  const activeStep = task.craftbook.steps.find((s) => s.id === activeStepId);
3717
3746
  if (activeStep && activeStepId === sessionStepId) {
3718
3747
  sessionStepCompletion = activeStep.advanceWhen ? "automatic" : "manual";
3748
+ sessionStepCheckedArtifacts = stepCheckedArtifactPaths(activeStep);
3719
3749
  }
3720
3750
  const owner = activeStep ? stepOwnerGezelId(task, activeStep) : void 0;
3721
3751
  activeStepOwnedBySession = !!gezelId && owner === gezelId;
@@ -3763,7 +3793,14 @@ async function linkedProjectIds() {
3763
3793
  return ids;
3764
3794
  }
3765
3795
  async function workspaceTarget(path) {
3766
- if (!isLinkedWorkspacePath(path)) return resolveLinkedWorkspacePath(projectId, [], path);
3796
+ if (!isLinkedWorkspacePath(path)) {
3797
+ const target = resolveLinkedWorkspacePath(projectId, [], path);
3798
+ if (target.kind !== "current") return target;
3799
+ const prefixed = workspaceDrawerPrefix(target.path);
3800
+ if (!prefixed) return target;
3801
+ const folder = await api.statProjectWorkspacePath(projectId, prefixed.folder).catch(() => ({ kind: "missing" }));
3802
+ return folder.kind === "missing" ? { ...target, path: prefixed.rest, displayPath: prefixed.rest } : target;
3803
+ }
3767
3804
  return resolveLinkedWorkspacePath(projectId, await linkedProjectIds(), path);
3768
3805
  }
3769
3806
  function workspaceClient(target) {
@@ -4594,6 +4631,25 @@ server.tool(
4594
4631
  )).files.map(
4595
4632
  (entry) => target.kind === "linked" ? prefixLinkedEntry(target.projectId, entry) : entry
4596
4633
  );
4634
+ if (!files.length && target.kind !== "links-root" && target.path) {
4635
+ const client = workspaceClient(target);
4636
+ const found = await client.statProjectWorkspacePath(target.projectId, target.path).catch(() => null);
4637
+ if (found && found.kind !== "dir") {
4638
+ const slash = target.path.lastIndexOf("/");
4639
+ const siblings = found.kind === "missing" ? await client.listProjectWorkspace(
4640
+ target.projectId,
4641
+ slash >= 0 ? target.path.slice(0, slash) : "",
4642
+ false
4643
+ ).then((listing) => listing.files).catch(() => []) : [];
4644
+ const shown = path ?? target.path;
4645
+ const summary2 = listDirMissingText(shown, found.kind, nearbyPathMatches(shown, siblings));
4646
+ return okResult(
4647
+ ListToolOutputSchema,
4648
+ { summary: summary2, items: [], count: 0 },
4649
+ { text: summary2 }
4650
+ );
4651
+ }
4652
+ }
4597
4653
  const summary = files.length ? `Listed ${files.length} ${files.length === 1 ? "entry" : "entries"}.` : "Empty directory.";
4598
4654
  return okResult(
4599
4655
  ListToolOutputSchema,
@@ -5925,6 +5981,11 @@ function joinErrorAndHint(details) {
5925
5981
  if (!hint || hint.toLowerCase() === head.toLowerCase()) return head;
5926
5982
  return `${head}: ${hint}`;
5927
5983
  }
5984
+ var UPSTREAM_FETCH_FAILURES = {
5985
+ upstream_timeout: "the site did not answer before the timeout. It may be slow or down; use another source rather than repeating this URL.",
5986
+ upstream_unreachable: "the site could not be reached (no such host, or the connection was refused or dropped). Use a URL from a search result, or another source.",
5987
+ upstream_tls_failed: "the site's security certificate was rejected, so nothing was fetched. Use another source."
5988
+ };
5928
5989
  function unwrapApiError(err) {
5929
5990
  const message = err instanceof Error ? err.message : String(err);
5930
5991
  const joined = joinErrorAndHint(err.details);
@@ -6173,6 +6234,31 @@ async function workspaceCollisionForArtifactPath(cleanPath) {
6173
6234
  }
6174
6235
  return null;
6175
6236
  }
6237
+ async function installedScriptScope(project, name) {
6238
+ try {
6239
+ const [own, user, standard] = await Promise.all([
6240
+ api.listProjectScripts(project),
6241
+ api.listUserScripts().catch(() => ({ scripts: [] })),
6242
+ api.listStandardScripts().catch(() => ({ scripts: [] }))
6243
+ ]);
6244
+ return inferScriptScope(name, void 0, [
6245
+ ...own.scripts.map((script) => ({ name: script.name, scope: "project" })),
6246
+ ...user.scripts.map((script) => ({ name: script.name, scope: "user" })),
6247
+ ...standard.scripts.map((script) => ({ name: script.name, scope: "standard" }))
6248
+ ]);
6249
+ } catch {
6250
+ return void 0;
6251
+ }
6252
+ }
6253
+ async function questionColleague(question) {
6254
+ try {
6255
+ const [roster, all] = await Promise.all([api.listProjectGezels(projectId), api.listGezels()]);
6256
+ const crew = all.gezels.filter((gezel) => roster.gezelIds.includes(gezel.id)).map((gezel) => ({ id: gezel.id, name: gezel.name }));
6257
+ return crewMemberNamedIn(question, crew, gezelId);
6258
+ } catch {
6259
+ return void 0;
6260
+ }
6261
+ }
6176
6262
  function toolIsAuthorizedForThisSession(name) {
6177
6263
  const canonical = canonicalToolName(name);
6178
6264
  if (authorizedToolNames !== null) return authorizedToolNames.has(canonical);
@@ -6620,7 +6706,9 @@ server.tool(
6620
6706
  ...gezelId ? { gezelId } : {},
6621
6707
  ...sessionId ? { sessionId } : {}
6622
6708
  });
6623
- const completionHint = sessionTaskRef && sessionStepId ? artifactCompletionHint(sessionStepCompletion) : "";
6709
+ const completionHint = sessionTaskRef && sessionStepId ? artifactCompletionHint(sessionStepCompletion, {
6710
+ checkedByStep: sessionStepCheckedArtifacts.includes(clean)
6711
+ }) : "";
6624
6712
  return { content: [{ type: "text", text: `Wrote ${clean}${completionHint}` }] };
6625
6713
  }
6626
6714
  );
@@ -8754,21 +8842,12 @@ server.tool(
8754
8842
  ...effectiveTaskRef ? { taskRef: effectiveTaskRef } : {},
8755
8843
  ...documentPath ? { documentPath } : {}
8756
8844
  });
8757
- if (res.deduped) {
8758
- return {
8759
- content: [
8760
- {
8761
- type: "text",
8762
- text: askUserQuestionText(res.questionId, true)
8763
- }
8764
- ]
8765
- };
8766
- }
8845
+ const colleague = toolIsAuthorizedForThisSession("message_gezel") ? await questionColleague(body) : void 0;
8767
8846
  return {
8768
8847
  content: [
8769
8848
  {
8770
8849
  type: "text",
8771
- text: askUserQuestionText(res.questionId, false)
8850
+ text: askUserQuestionText(res.questionId, res.deduped === true, colleague)
8772
8851
  }
8773
8852
  ]
8774
8853
  };
@@ -9550,7 +9629,7 @@ server.tool(
9550
9629
  ListProjectGezelsInputSchema.shape,
9551
9630
  async ({ project }) => {
9552
9631
  const resolvedProject = project ? await resolveProjectId(project) : projectId;
9553
- const [roster, local, allGezels] = await Promise.all([
9632
+ const [roster, local2, allGezels] = await Promise.all([
9554
9633
  api.listProjectGezels(resolvedProject),
9555
9634
  api.listProjectLocalGezels(resolvedProject),
9556
9635
  api.listGezels()
@@ -9562,7 +9641,7 @@ server.tool(
9562
9641
  const gezel = byId.get(id);
9563
9642
  return gezel ? { id, gezel } : { id };
9564
9643
  }),
9565
- local.gezels
9644
+ local2.gezels
9566
9645
  );
9567
9646
  return { content: [{ type: "text", text }] };
9568
9647
  }
@@ -9727,23 +9806,37 @@ function inferDraftDeliverable(task) {
9727
9806
  function setStepDeliverableCall(ref, stepId, deliverable) {
9728
9807
  return `set_step_deliverable({ task: "${ref}", stepId: "${stepId}", path: "${deliverable.path}", kind: "${deliverable.kind}" })`;
9729
9808
  }
9809
+ var installWideTaskListingRefused = false;
9730
9810
  server.tool(
9731
9811
  "list_tasks",
9732
9812
  GEZEL_TOOL_DESCRIPTIONS2.list_tasks,
9733
9813
  ListTasksInputSchema.shape,
9734
9814
  async ({ project, status, assignee }) => {
9735
- const projectId2 = project ? await resolveProjectId(project) : void 0;
9736
- const res = projectId2 ? await api.listProjectTasks(
9737
- projectId2,
9738
- status || assignee ? { ...status ? { status } : {}, ...assignee ? { assignee } : {} } : void 0
9739
- ) : await api.listTasks(
9740
- status || assignee ? { ...status ? { status } : {}, ...assignee ? { assignee } : {} } : void 0
9741
- );
9742
- const summary = res.tasks.length ? `Listed ${res.tasks.length} matching ${res.tasks.length === 1 ? "task" : "tasks"}.` : "No tasks match.";
9815
+ const explicitProjectId = project ? await resolveProjectId(project) : void 0;
9816
+ const filter = status || assignee ? { ...status ? { status } : {}, ...assignee ? { assignee } : {} } : void 0;
9817
+ let listedProjectId = explicitProjectId ?? (installWideTaskListingRefused ? projectId : null);
9818
+ let res;
9819
+ if (listedProjectId) {
9820
+ res = await api.listProjectTasks(listedProjectId, filter);
9821
+ } else {
9822
+ try {
9823
+ res = await api.listTasks(filter);
9824
+ } catch (err) {
9825
+ if (!(err instanceof GezelApiError) || err.status !== 403) throw err;
9826
+ installWideTaskListingRefused = true;
9827
+ listedProjectId = projectId;
9828
+ res = await api.listProjectTasks(projectId, filter);
9829
+ }
9830
+ }
9831
+ const scope = !explicitProjectId && listedProjectId ? " in this project" : "";
9832
+ const summary = res.tasks.length ? `Listed ${res.tasks.length} matching ${res.tasks.length === 1 ? "task" : "tasks"}${scope}.` : `No tasks match${scope}.`;
9743
9833
  return okResult(
9744
9834
  TaskToolOutputSchema,
9745
9835
  { summary, operation: "list", tasks: res.tasks, count: res.tasks.length },
9746
- { text: listTasksText(res.tasks) }
9836
+ {
9837
+ text: scope ? `${listTasksText(res.tasks)}
9838
+ (Tasks in this project only.)` : listTasksText(res.tasks)
9839
+ }
9747
9840
  );
9748
9841
  }
9749
9842
  );
@@ -10295,7 +10388,14 @@ ${verif}`) },
10295
10388
  );
10296
10389
  }
10297
10390
  }
10298
- const updated = await api.setTaskStatus(parsed.projectId, parsed.num, status);
10391
+ let updated;
10392
+ try {
10393
+ updated = await api.setTaskStatus(parsed.projectId, parsed.num, status);
10394
+ } catch (err) {
10395
+ const stale = staleTaskStepRefusal(err);
10396
+ if (stale) return errorResult(stale, { code: "stale_task_step", retryable: false });
10397
+ throw err;
10398
+ }
10299
10399
  const summary = `${ref} \u2192 ${status}`;
10300
10400
  return okResult(
10301
10401
  TaskToolOutputSchema,
@@ -10470,6 +10570,8 @@ server.tool(
10470
10570
  next ? { next } : {}
10471
10571
  );
10472
10572
  } catch (err) {
10573
+ const stale = staleTaskStepRefusal(err);
10574
+ if (stale) return errorResult(stale, { code: "stale_task_step", retryable: false });
10473
10575
  return errorResult(await explainAdvanceFailure(err, parsed, stepId, next), {
10474
10576
  retryable: true
10475
10577
  });
@@ -11173,8 +11275,14 @@ server.tool(
11173
11275
  ${body}` }] };
11174
11276
  } catch (err) {
11175
11277
  const msg = unwrapApiError(err);
11278
+ const explained = UPSTREAM_FETCH_FAILURES[msg];
11176
11279
  return {
11177
- content: [{ type: "text", text: `fetch_url failed: ${msg}` }],
11280
+ content: [
11281
+ {
11282
+ type: "text",
11283
+ text: `fetch_url failed: ${explained ? `${explained} (${msg})` : msg}`
11284
+ }
11285
+ ],
11178
11286
  isError: true
11179
11287
  };
11180
11288
  }
@@ -12521,9 +12629,10 @@ server.tool(
12521
12629
  }
12522
12630
  const resolved = project ? await resolveProjectId(project) : projectId;
12523
12631
  try {
12632
+ const effectiveScope = scope ?? await installedScriptScope(resolved, name);
12524
12633
  const res = await api.runProjectScript(resolved, {
12525
12634
  name,
12526
- ...scope ? { scope } : {},
12635
+ ...effectiveScope ? { scope: effectiveScope } : {},
12527
12636
  ...input ? { input } : {}
12528
12637
  });
12529
12638
  return formatScriptRunResult(res);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "1.2.1",
3
+ "version": "1.2.2",
4
4
  "description": "Gezel MCP server — gives agents access to memory, workspace, artifacts, and tools.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -55,8 +55,8 @@
55
55
  "!dist/**/*.map"
56
56
  ],
57
57
  "dependencies": {
58
- "@bendyline/gezel": "1.2.1",
59
- "@bendyline/gezel-client": "1.2.1",
58
+ "@bendyline/gezel": "1.2.2",
59
+ "@bendyline/gezel-client": "1.2.2",
60
60
  "@modelcontextprotocol/sdk": "^1.29.0",
61
61
  "typescript": "^6.0.3",
62
62
  "zod": "^4.4.3"