@bendyline/gezel-mcp 1.2.1 → 1.2.3

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 +242 -40
  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
@@ -9,9 +9,13 @@ import {
9
9
  CreateTaskInputSchema,
10
10
  EmptyInputSchema,
11
11
  EnsureGezelInputSchema,
12
+ FindFilesRequestSchema,
12
13
  GEZEL_TOOL_DESCRIPTIONS as GEZEL_TOOL_DESCRIPTIONS2,
13
14
  GetScriptRunInputSchema,
14
15
  GetTaskInputSchema,
16
+ KnowledgeIdSchema,
17
+ KnowledgeNearbyRequestSchema,
18
+ KnowledgeRadiusSchema,
15
19
  ListArtifactsInputSchema,
16
20
  ListDirectoryInputSchema,
17
21
  ListDocumentsInputSchema,
@@ -68,6 +72,7 @@ import {
68
72
  composeCraftbookLaunch,
69
73
  craftbookDocFormatFromEnv,
70
74
  createTaskText,
75
+ crewMemberNamedIn,
71
76
  deliverableStep,
72
77
  deniedTaskScopedWrite,
73
78
  expandStepDeliverable,
@@ -76,10 +81,12 @@ import {
76
81
  getScriptRunText,
77
82
  getTaskText,
78
83
  inferDeliverableKind,
84
+ inferScriptScope,
79
85
  isReservedShadowArtifactPath,
80
86
  isSafeEntityId,
81
87
  isTrustedConstrainedToolset,
82
88
  listArtifactsText,
89
+ listDirMissingText,
83
90
  listDirText,
84
91
  listDocumentsText,
85
92
  listGezelsText,
@@ -89,6 +96,7 @@ import {
89
96
  listScriptsText,
90
97
  listTasksText,
91
98
  messageGezelText,
99
+ nearbyPathMatches,
92
100
  parseKnowledgeUri,
93
101
  pickRandomNameWithGender,
94
102
  prioritizePullsForCurrentBranch,
@@ -100,15 +108,21 @@ import {
100
108
  saveMemoryText,
101
109
  searchMemoryText,
102
110
  searchResultText,
111
+ stepCheckedArtifactPaths,
103
112
  stepInsertionIndex,
104
113
  stepOwnerGezelId,
105
114
  taskOwnedPrefixes,
106
115
  taskScopedWriteDeniedMessage,
107
116
  uniqueStepId,
117
+ workspaceDrawerPrefix,
108
118
  writeTaskNoteText
109
119
  } from "@bendyline/gezel";
110
120
  import { GezelApiError, GezelClient } from "@bendyline/gezel-client";
111
- import { createPatientFetch, createTrustingFetch } from "@bendyline/gezel-client/node";
121
+ import {
122
+ connectToLocalGezel,
123
+ createPatientFetch,
124
+ createTrustingFetch
125
+ } from "@bendyline/gezel-client/node";
112
126
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
113
127
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
114
128
  import { z as z5 } from "zod";
@@ -439,6 +453,7 @@ function closestFileNames(target, names, limit = 3) {
439
453
 
440
454
  // src/tool-contracts.ts
441
455
  import { toolErrorText } from "@bendyline/gezel";
456
+ import { KnowledgeLocationSchema } from "@bendyline/gezel";
442
457
  import { z as z2 } from "zod";
443
458
 
444
459
  // src/tool-inventory.ts
@@ -641,6 +656,23 @@ var TOOL_OUTPUT_SCHEMAS = {
641
656
  list_tables: ListToolOutputSchema,
642
657
  describe_table: TableDescribeToolOutputSchema,
643
658
  query_table: TableQueryToolOutputSchema,
659
+ knowledge_nearby: z2.object({
660
+ documents: z2.array(
661
+ z2.object({
662
+ documentId: z2.string(),
663
+ title: z2.string(),
664
+ summary: z2.string().nullable(),
665
+ distanceMeters: z2.number().nonnegative(),
666
+ matchedLocation: KnowledgeLocationSchema,
667
+ uri: z2.string(),
668
+ publisherId: z2.string(),
669
+ catalogId: z2.string(),
670
+ catalogVersion: z2.string()
671
+ })
672
+ ),
673
+ total: z2.number().int().nonnegative(),
674
+ nextCursor: z2.string().optional()
675
+ }),
644
676
  search: SearchToolOutputSchema,
645
677
  search_memory: SearchToolOutputSchema,
646
678
  save_memory: MemorySaveToolOutputSchema,
@@ -728,6 +760,7 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
728
760
  "describe_table",
729
761
  "query_table",
730
762
  "search",
763
+ "knowledge_nearby",
731
764
  "search_memory",
732
765
  "list_memories",
733
766
  "list_dir",
@@ -2647,6 +2680,12 @@ function taskStepMutationRejection(scope) {
2647
2680
  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
2681
  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
2682
  }
2683
+ function staleTaskStepRefusal(err) {
2684
+ const details = err?.details;
2685
+ if (!details || typeof details !== "object") return null;
2686
+ const { error, hint } = details;
2687
+ return error === "stale_task_step" && typeof hint === "string" && hint.trim() ? hint : null;
2688
+ }
2650
2689
 
2651
2690
  // src/validate.ts
2652
2691
  import ts2 from "typescript";
@@ -3677,8 +3716,19 @@ function containsLooseJavascript(text) {
3677
3716
  }
3678
3717
 
3679
3718
  // src/server.ts
3680
- var baseUrl = process.env.GEZEL_BASE_URL ?? "http://127.0.0.1:0";
3681
- var token = process.env.GEZEL_TOKEN ?? "";
3719
+ async function localGezelUnlessSpawned() {
3720
+ if (process.env.GEZEL_BASE_URL || process.env.GEZEL_MCP_NO_MAIN === "1") return null;
3721
+ try {
3722
+ return await connectToLocalGezel();
3723
+ } catch (err) {
3724
+ process.stderr.write(`gezel-mcp: ${err instanceof Error ? err.message : String(err)}
3725
+ `);
3726
+ process.exit(1);
3727
+ }
3728
+ }
3729
+ var local = await localGezelUnlessSpawned();
3730
+ var baseUrl = local?.baseUrl ?? process.env.GEZEL_BASE_URL ?? "http://127.0.0.1:0";
3731
+ var token = local?.token ?? process.env.GEZEL_TOKEN ?? "";
3682
3732
  var gezelId = process.env.GEZEL_AGENT_ID ?? "";
3683
3733
  var projectId = process.env.GEZEL_PROJECT_ID ?? "default";
3684
3734
  var sessionId = process.env.GEZEL_SESSION_ID ?? "";
@@ -3693,7 +3743,7 @@ var sessionCraftbookId = process.env.GEZEL_CRAFTBOOK_ID ?? "";
3693
3743
  var rawSessionContextWindow = Number(process.env.GEZEL_CONTEXT_WINDOW ?? "");
3694
3744
  var sessionContextWindow = Number.isFinite(rawSessionContextWindow) && rawSessionContextWindow > 0 ? rawSessionContextWindow : void 0;
3695
3745
  var certPath = process.env.GEZEL_CERT_PATH;
3696
- var fetchImpl = certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch();
3746
+ var fetchImpl = local?.fetch ?? (certPath ? createTrustingFetch({ cert: readFileSync(certPath, "utf8") }) : createPatientFetch());
3697
3747
  var api = new GezelClient({ baseUrl, token, fetch: fetchImpl });
3698
3748
  var linkedFetchImpl = (input, init) => {
3699
3749
  const headers = new Headers(init?.headers);
@@ -3703,9 +3753,11 @@ var linkedFetchImpl = (input, init) => {
3703
3753
  var linkedApi = new GezelClient({ baseUrl, token, fetch: linkedFetchImpl });
3704
3754
  var sessionStepCompleted = false;
3705
3755
  var sessionStepCompletion = "unknown";
3756
+ var sessionStepCheckedArtifacts = [];
3706
3757
  async function staleStepMutationResult() {
3707
3758
  if (!sessionTaskRef || !sessionStepId) return null;
3708
3759
  sessionStepCompletion = "unknown";
3760
+ sessionStepCheckedArtifacts = [];
3709
3761
  let activeStepId;
3710
3762
  let activeStepOwnedBySession = false;
3711
3763
  if (!sessionStepCompleted) {
@@ -3716,6 +3768,7 @@ async function staleStepMutationResult() {
3716
3768
  const activeStep = task.craftbook.steps.find((s) => s.id === activeStepId);
3717
3769
  if (activeStep && activeStepId === sessionStepId) {
3718
3770
  sessionStepCompletion = activeStep.advanceWhen ? "automatic" : "manual";
3771
+ sessionStepCheckedArtifacts = stepCheckedArtifactPaths(activeStep);
3719
3772
  }
3720
3773
  const owner = activeStep ? stepOwnerGezelId(task, activeStep) : void 0;
3721
3774
  activeStepOwnedBySession = !!gezelId && owner === gezelId;
@@ -3763,7 +3816,14 @@ async function linkedProjectIds() {
3763
3816
  return ids;
3764
3817
  }
3765
3818
  async function workspaceTarget(path) {
3766
- if (!isLinkedWorkspacePath(path)) return resolveLinkedWorkspacePath(projectId, [], path);
3819
+ if (!isLinkedWorkspacePath(path)) {
3820
+ const target = resolveLinkedWorkspacePath(projectId, [], path);
3821
+ if (target.kind !== "current") return target;
3822
+ const prefixed = workspaceDrawerPrefix(target.path);
3823
+ if (!prefixed) return target;
3824
+ const folder = await api.statProjectWorkspacePath(projectId, prefixed.folder).catch(() => ({ kind: "missing" }));
3825
+ return folder.kind === "missing" ? { ...target, path: prefixed.rest, displayPath: prefixed.rest } : target;
3826
+ }
3767
3827
  return resolveLinkedWorkspacePath(projectId, await linkedProjectIds(), path);
3768
3828
  }
3769
3829
  function workspaceClient(target) {
@@ -4594,6 +4654,25 @@ server.tool(
4594
4654
  )).files.map(
4595
4655
  (entry) => target.kind === "linked" ? prefixLinkedEntry(target.projectId, entry) : entry
4596
4656
  );
4657
+ if (!files.length && target.kind !== "links-root" && target.path) {
4658
+ const client = workspaceClient(target);
4659
+ const found = await client.statProjectWorkspacePath(target.projectId, target.path).catch(() => null);
4660
+ if (found && found.kind !== "dir") {
4661
+ const slash = target.path.lastIndexOf("/");
4662
+ const siblings = found.kind === "missing" ? await client.listProjectWorkspace(
4663
+ target.projectId,
4664
+ slash >= 0 ? target.path.slice(0, slash) : "",
4665
+ false
4666
+ ).then((listing) => listing.files).catch(() => []) : [];
4667
+ const shown = path ?? target.path;
4668
+ const summary2 = listDirMissingText(shown, found.kind, nearbyPathMatches(shown, siblings));
4669
+ return okResult(
4670
+ ListToolOutputSchema,
4671
+ { summary: summary2, items: [], count: 0 },
4672
+ { text: summary2 }
4673
+ );
4674
+ }
4675
+ }
4597
4676
  const summary = files.length ? `Listed ${files.length} ${files.length === 1 ? "entry" : "entries"}.` : "Empty directory.";
4598
4677
  return okResult(
4599
4678
  ListToolOutputSchema,
@@ -5925,6 +6004,11 @@ function joinErrorAndHint(details) {
5925
6004
  if (!hint || hint.toLowerCase() === head.toLowerCase()) return head;
5926
6005
  return `${head}: ${hint}`;
5927
6006
  }
6007
+ var UPSTREAM_FETCH_FAILURES = {
6008
+ upstream_timeout: "the site did not answer before the timeout. It may be slow or down; use another source rather than repeating this URL.",
6009
+ 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.",
6010
+ upstream_tls_failed: "the site's security certificate was rejected, so nothing was fetched. Use another source."
6011
+ };
5928
6012
  function unwrapApiError(err) {
5929
6013
  const message = err instanceof Error ? err.message : String(err);
5930
6014
  const joined = joinErrorAndHint(err.details);
@@ -6173,6 +6257,31 @@ async function workspaceCollisionForArtifactPath(cleanPath) {
6173
6257
  }
6174
6258
  return null;
6175
6259
  }
6260
+ async function installedScriptScope(project, name) {
6261
+ try {
6262
+ const [own, user, standard] = await Promise.all([
6263
+ api.listProjectScripts(project),
6264
+ api.listUserScripts().catch(() => ({ scripts: [] })),
6265
+ api.listStandardScripts().catch(() => ({ scripts: [] }))
6266
+ ]);
6267
+ return inferScriptScope(name, void 0, [
6268
+ ...own.scripts.map((script) => ({ name: script.name, scope: "project" })),
6269
+ ...user.scripts.map((script) => ({ name: script.name, scope: "user" })),
6270
+ ...standard.scripts.map((script) => ({ name: script.name, scope: "standard" }))
6271
+ ]);
6272
+ } catch {
6273
+ return void 0;
6274
+ }
6275
+ }
6276
+ async function questionColleague(question) {
6277
+ try {
6278
+ const [roster, all] = await Promise.all([api.listProjectGezels(projectId), api.listGezels()]);
6279
+ const crew = all.gezels.filter((gezel) => roster.gezelIds.includes(gezel.id)).map((gezel) => ({ id: gezel.id, name: gezel.name }));
6280
+ return crewMemberNamedIn(question, crew, gezelId);
6281
+ } catch {
6282
+ return void 0;
6283
+ }
6284
+ }
6176
6285
  function toolIsAuthorizedForThisSession(name) {
6177
6286
  const canonical = canonicalToolName(name);
6178
6287
  if (authorizedToolNames !== null) return authorizedToolNames.has(canonical);
@@ -6620,7 +6729,9 @@ server.tool(
6620
6729
  ...gezelId ? { gezelId } : {},
6621
6730
  ...sessionId ? { sessionId } : {}
6622
6731
  });
6623
- const completionHint = sessionTaskRef && sessionStepId ? artifactCompletionHint(sessionStepCompletion) : "";
6732
+ const completionHint = sessionTaskRef && sessionStepId ? artifactCompletionHint(sessionStepCompletion, {
6733
+ checkedByStep: sessionStepCheckedArtifacts.includes(clean)
6734
+ }) : "";
6624
6735
  return { content: [{ type: "text", text: `Wrote ${clean}${completionHint}` }] };
6625
6736
  }
6626
6737
  );
@@ -6695,6 +6806,24 @@ server.tool(
6695
6806
  ReadDocumentInputSchema.shape,
6696
6807
  async ({ path }) => {
6697
6808
  const knowledgeUri = parseKnowledgeUri(path);
6809
+ if (knowledgeUri?.fragment && "chunk" in knowledgeUri.fragment) {
6810
+ const passage = await api.readKnowledgePassage(
6811
+ knowledgeUri.catalogId,
6812
+ knowledgeUri.documentId,
6813
+ knowledgeUri.fragment.chunk
6814
+ );
6815
+ const articleUri = path.split("#")[0];
6816
+ const provenance = [
6817
+ `Source: ${passage.title} \u2014 ${path}`,
6818
+ ...passage.headingPath.length ? [`Section: ${passage.headingPath.join(" \u203A ")}`] : [],
6819
+ `Lines ${passage.lineStart}-${passage.lineEnd} of the article (whole article: read_document ${articleUri})`,
6820
+ ...passage.sourceUrl ? [`Origin: ${passage.sourceUrl}`] : [],
6821
+ ...passage.sourceUpdatedAt ? [`Snapshot: ${passage.sourceUpdatedAt}`] : []
6822
+ ].join("\n");
6823
+ return { content: [{ type: "text", text: `${provenance}
6824
+
6825
+ ${passage.text}` }] };
6826
+ }
6698
6827
  if (knowledgeUri) {
6699
6828
  const doc = await api.readKnowledgeDocument(knowledgeUri.catalogId, knowledgeUri.documentId);
6700
6829
  let body = doc.markdown;
@@ -8712,6 +8841,7 @@ server.tool(
8712
8841
  AskUserQuestionInputSchema.shape,
8713
8842
  async ({
8714
8843
  question,
8844
+ permissionRequest,
8715
8845
  prompt,
8716
8846
  description,
8717
8847
  choices,
@@ -8748,27 +8878,19 @@ server.tool(
8748
8878
  gezelId,
8749
8879
  sessionId,
8750
8880
  prompt: body,
8881
+ ...permissionRequest ? { permissionRequest } : {},
8751
8882
  ...choices ? { choices } : {},
8752
8883
  ...allowWriteIn !== void 0 ? { allowWriteIn } : {},
8753
8884
  ...multiSelect !== void 0 ? { multiSelect } : {},
8754
8885
  ...effectiveTaskRef ? { taskRef: effectiveTaskRef } : {},
8755
8886
  ...documentPath ? { documentPath } : {}
8756
8887
  });
8757
- if (res.deduped) {
8758
- return {
8759
- content: [
8760
- {
8761
- type: "text",
8762
- text: askUserQuestionText(res.questionId, true)
8763
- }
8764
- ]
8765
- };
8766
- }
8888
+ const colleague = toolIsAuthorizedForThisSession("message_gezel") ? await questionColleague(body) : void 0;
8767
8889
  return {
8768
8890
  content: [
8769
8891
  {
8770
8892
  type: "text",
8771
- text: askUserQuestionText(res.questionId, false)
8893
+ text: askUserQuestionText(res.questionId, res.deduped === true, colleague)
8772
8894
  }
8773
8895
  ]
8774
8896
  };
@@ -9550,7 +9672,7 @@ server.tool(
9550
9672
  ListProjectGezelsInputSchema.shape,
9551
9673
  async ({ project }) => {
9552
9674
  const resolvedProject = project ? await resolveProjectId(project) : projectId;
9553
- const [roster, local, allGezels] = await Promise.all([
9675
+ const [roster, local2, allGezels] = await Promise.all([
9554
9676
  api.listProjectGezels(resolvedProject),
9555
9677
  api.listProjectLocalGezels(resolvedProject),
9556
9678
  api.listGezels()
@@ -9562,7 +9684,7 @@ server.tool(
9562
9684
  const gezel = byId.get(id);
9563
9685
  return gezel ? { id, gezel } : { id };
9564
9686
  }),
9565
- local.gezels
9687
+ local2.gezels
9566
9688
  );
9567
9689
  return { content: [{ type: "text", text }] };
9568
9690
  }
@@ -9710,7 +9832,7 @@ server.tool(
9710
9832
  async function resolveAssigneeArg(raw) {
9711
9833
  const normalized = normalizeAssigneeArg(raw);
9712
9834
  if (!normalized) return void 0;
9713
- if (normalized.kind === "user") return { kind: "user" };
9835
+ if (normalized.kind === "user") return normalized;
9714
9836
  return { kind: "gezel", gezelId: await resolveGezelId(normalized.ref) };
9715
9837
  }
9716
9838
  function inferDraftDeliverable(task) {
@@ -9727,23 +9849,37 @@ function inferDraftDeliverable(task) {
9727
9849
  function setStepDeliverableCall(ref, stepId, deliverable) {
9728
9850
  return `set_step_deliverable({ task: "${ref}", stepId: "${stepId}", path: "${deliverable.path}", kind: "${deliverable.kind}" })`;
9729
9851
  }
9852
+ var installWideTaskListingRefused = false;
9730
9853
  server.tool(
9731
9854
  "list_tasks",
9732
9855
  GEZEL_TOOL_DESCRIPTIONS2.list_tasks,
9733
9856
  ListTasksInputSchema.shape,
9734
9857
  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.";
9858
+ const explicitProjectId = project ? await resolveProjectId(project) : void 0;
9859
+ const filter = status || assignee ? { ...status ? { status } : {}, ...assignee ? { assignee } : {} } : void 0;
9860
+ let listedProjectId = explicitProjectId ?? (installWideTaskListingRefused ? projectId : null);
9861
+ let res;
9862
+ if (listedProjectId) {
9863
+ res = await api.listProjectTasks(listedProjectId, filter);
9864
+ } else {
9865
+ try {
9866
+ res = await api.listTasks(filter);
9867
+ } catch (err) {
9868
+ if (!(err instanceof GezelApiError) || err.status !== 403) throw err;
9869
+ installWideTaskListingRefused = true;
9870
+ listedProjectId = projectId;
9871
+ res = await api.listProjectTasks(projectId, filter);
9872
+ }
9873
+ }
9874
+ const scope = !explicitProjectId && listedProjectId ? " in this project" : "";
9875
+ const summary = res.tasks.length ? `Listed ${res.tasks.length} matching ${res.tasks.length === 1 ? "task" : "tasks"}${scope}.` : `No tasks match${scope}.`;
9743
9876
  return okResult(
9744
9877
  TaskToolOutputSchema,
9745
9878
  { summary, operation: "list", tasks: res.tasks, count: res.tasks.length },
9746
- { text: listTasksText(res.tasks) }
9879
+ {
9880
+ text: scope ? `${listTasksText(res.tasks)}
9881
+ (Tasks in this project only.)` : listTasksText(res.tasks)
9882
+ }
9747
9883
  );
9748
9884
  }
9749
9885
  );
@@ -9775,6 +9911,7 @@ function blueprintToStep(s) {
9775
9911
  const d = coerceBlueprintDeliverable(s.deliverable);
9776
9912
  return {
9777
9913
  name: s.name,
9914
+ ...s.assignee ? { assignee: s.assignee } : {},
9778
9915
  ...s.description ? { description: s.description } : {},
9779
9916
  ...s.prompt ? { prompt: s.prompt } : {},
9780
9917
  ...s.suggestedGezelId ? { suggestedGezelId: s.suggestedGezelId } : {},
@@ -10295,7 +10432,14 @@ ${verif}`) },
10295
10432
  );
10296
10433
  }
10297
10434
  }
10298
- const updated = await api.setTaskStatus(parsed.projectId, parsed.num, status);
10435
+ let updated;
10436
+ try {
10437
+ updated = await api.setTaskStatus(parsed.projectId, parsed.num, status);
10438
+ } catch (err) {
10439
+ const stale = staleTaskStepRefusal(err);
10440
+ if (stale) return errorResult(stale, { code: "stale_task_step", retryable: false });
10441
+ throw err;
10442
+ }
10299
10443
  const summary = `${ref} \u2192 ${status}`;
10300
10444
  return okResult(
10301
10445
  TaskToolOutputSchema,
@@ -10374,6 +10518,7 @@ server.tool(
10374
10518
  name: z5.string().min(1),
10375
10519
  description: z5.string().optional(),
10376
10520
  prompt: z5.string().optional(),
10521
+ assignee: StepBlueprintSchema.shape.assignee,
10377
10522
  suggestedGezelId: z5.string().optional(),
10378
10523
  suggestedRole: z5.string().optional().describe('Role hint, e.g. "developer", "reviewer".'),
10379
10524
  deliverable: deliverableArg,
@@ -10386,6 +10531,7 @@ server.tool(
10386
10531
  name,
10387
10532
  description,
10388
10533
  prompt,
10534
+ assignee,
10389
10535
  suggestedGezelId,
10390
10536
  suggestedRole,
10391
10537
  deliverable,
@@ -10405,6 +10551,7 @@ server.tool(
10405
10551
  name,
10406
10552
  ...description ? { description } : {},
10407
10553
  ...prompt ? { prompt } : {},
10554
+ ...assignee ? { assignee } : {},
10408
10555
  ...suggestedGezelId ? { suggestedGezelId } : {},
10409
10556
  ...suggestedRole ? { suggestedRole } : {},
10410
10557
  ...d ? { deliverable: d } : {},
@@ -10470,6 +10617,8 @@ server.tool(
10470
10617
  next ? { next } : {}
10471
10618
  );
10472
10619
  } catch (err) {
10620
+ const stale = staleTaskStepRefusal(err);
10621
+ if (stale) return errorResult(stale, { code: "stale_task_step", retryable: false });
10473
10622
  return errorResult(await explainAdvanceFailure(err, parsed, stepId, next), {
10474
10623
  retryable: true
10475
10624
  });
@@ -11173,8 +11322,14 @@ server.tool(
11173
11322
  ${body}` }] };
11174
11323
  } catch (err) {
11175
11324
  const msg = unwrapApiError(err);
11325
+ const explained = UPSTREAM_FETCH_FAILURES[msg];
11176
11326
  return {
11177
- content: [{ type: "text", text: `fetch_url failed: ${msg}` }],
11327
+ content: [
11328
+ {
11329
+ type: "text",
11330
+ text: `fetch_url failed: ${explained ? `${explained} (${msg})` : msg}`
11331
+ }
11332
+ ],
11178
11333
  isError: true
11179
11334
  };
11180
11335
  }
@@ -11312,12 +11467,7 @@ server.tool(
11312
11467
  server.tool(
11313
11468
  "find_files",
11314
11469
  "Find files in the project workspace by glob (e.g. `**/*.spec.ts`). Complement to `grep_files`, which searches contents. Skips `node_modules` and `.git`.",
11315
- {
11316
- glob: z5.string().min(1),
11317
- path: z5.string().optional(),
11318
- caseInsensitive: z5.boolean().optional(),
11319
- maxResults: z5.number().int().positive().optional()
11320
- },
11470
+ FindFilesRequestSchema.shape,
11321
11471
  async (args) => {
11322
11472
  try {
11323
11473
  const res = await api.toolFindFiles(projectId, args);
@@ -11623,10 +11773,56 @@ server.tool(
11623
11773
  }
11624
11774
  }
11625
11775
  );
11776
+ server.tool(
11777
+ "knowledge_nearby",
11778
+ GEZEL_TOOL_DESCRIPTIONS2.knowledge_nearby,
11779
+ KnowledgeNearbyRequestSchema.shape,
11780
+ async (body) => {
11781
+ try {
11782
+ const found = await api.toolKnowledgeNearby(projectId, body);
11783
+ const result = {
11784
+ ...found,
11785
+ documents: found.documents.map((document) => ({
11786
+ documentId: document.id,
11787
+ title: document.title,
11788
+ summary: document.summary,
11789
+ distanceMeters: document.distanceMeters,
11790
+ matchedLocation: {
11791
+ id: document.matchedLocation.id,
11792
+ latitude: document.matchedLocation.latitude,
11793
+ longitude: document.matchedLocation.longitude,
11794
+ role: document.matchedLocation.role
11795
+ },
11796
+ uri: document.uri,
11797
+ publisherId: document.publisherId,
11798
+ catalogId: document.catalogId,
11799
+ catalogVersion: document.catalogVersion
11800
+ }))
11801
+ };
11802
+ return {
11803
+ content: [{ type: "text", text: JSON.stringify(result) }],
11804
+ structuredContent: result
11805
+ };
11806
+ } catch (error) {
11807
+ return {
11808
+ content: [
11809
+ { type: "text", text: `knowledge_nearby failed: ${unwrapApiError(error)}` }
11810
+ ],
11811
+ isError: true
11812
+ };
11813
+ }
11814
+ }
11815
+ );
11626
11816
  server.tool(
11627
11817
  "search",
11628
11818
  GEZEL_TOOL_DESCRIPTIONS2.search,
11629
11819
  SearchInputSchema.extend({
11820
+ spatial: KnowledgeRadiusSchema.optional().describe(
11821
+ "Restrict knowledge to subject locations within this radius, in meters."
11822
+ ),
11823
+ catalogs: z5.array(KnowledgeIdSchema).optional().describe(
11824
+ 'Search only these knowledge catalogs. Implies sources: ["knowledge"] unless sources is given.'
11825
+ ),
11630
11826
  sources: z5.array(
11631
11827
  z5.enum(["workspace", "artifacts", "project-memory", "gezel-memory", "shared", "knowledge"])
11632
11828
  ).optional().describe("Optional corpus filter. Omit to search all knowledge available to this project."),
@@ -11638,13 +11834,18 @@ server.tool(
11638
11834
  'Only results under this path prefix (e.g. "src/engine/" or "../<project-id>/docs/"). Narrowing only.'
11639
11835
  )
11640
11836
  }).shape,
11641
- async ({ query, sources, maxResults, cursor, pathPrefix }) => {
11837
+ async ({ query, sources, maxResults, cursor, pathPrefix, spatial, catalogs }) => {
11642
11838
  try {
11643
11839
  const res = await api.toolSearch(projectId, {
11644
11840
  query,
11645
11841
  gezelId,
11646
11842
  includeShared: true,
11647
- ...sources ? { sources } : {},
11843
+ // Naming catalogs is asking for reference material: without this the
11844
+ // workspace and shared library kept answering, and their rank-derived
11845
+ // "strong" hits crowded the named catalog off the page.
11846
+ ...sources ? { sources } : spatial || catalogs ? { sources: ["knowledge"] } : {},
11847
+ ...spatial ? { spatial } : {},
11848
+ ...catalogs ? { catalogs } : {},
11648
11849
  ...maxResults ? { maxResults } : {},
11649
11850
  ...cursor ? { offset: cursor } : {},
11650
11851
  ...pathPrefix ? { pathPrefix } : {}
@@ -12521,9 +12722,10 @@ server.tool(
12521
12722
  }
12522
12723
  const resolved = project ? await resolveProjectId(project) : projectId;
12523
12724
  try {
12725
+ const effectiveScope = scope ?? await installedScriptScope(resolved, name);
12524
12726
  const res = await api.runProjectScript(resolved, {
12525
12727
  name,
12526
- ...scope ? { scope } : {},
12728
+ ...effectiveScope ? { scope: effectiveScope } : {},
12527
12729
  ...input ? { input } : {}
12528
12730
  });
12529
12731
  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.3",
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.3",
59
+ "@bendyline/gezel-client": "1.2.3",
60
60
  "@modelcontextprotocol/sdk": "^1.29.0",
61
61
  "typescript": "^6.0.3",
62
62
  "zod": "^4.4.3"