@bendyline/gezel-mcp 1.0.1 → 1.0.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.
package/dist/index.d.ts CHANGED
@@ -18,7 +18,7 @@
18
18
  * whose names come from the applied type's manifest, not from this frozen
19
19
  * contract. Registration guards them against colliding with these names.
20
20
  */
21
- declare const ALWAYS_REGISTERED_TOOLS: readonly ["search_memory", "save_memory", "list_memories", "list_dir", "read_file", "read_files", "stat", "write_file", "append_to_file", "replace_in_file", "replace_lines", "apply_patch", "insert_at_marker", "delete_path", "make_dir", "rename", "copy_artifact_to_workspace", "validate", "npm_install", "list_package_scripts", "run_package_script", "run_npx", "run_nodejs_script", "derive_file", "list_packages", "run_playwright_script", "list_artifacts", "read_artifact", "write_artifact", "grep_artifact", "browser_find_page_element", "list_documents", "read_document", "write_document", "delete_document", "search_documents", "list_gezels", "create_gezel", "list_gilde", "list_project_types", "apply_project_type", "start_project_from_type", "export_project_type", "import_project_type", "ensure_gezel", "update_gezel", "message_gezel", "ask_gezel", "ask_specialist", "delegate_developer", "consult_developer", "delegate_designer", "consult_designer", "delegate_reviewer", "consult_reviewer", "delegate_planner", "consult_planner", "delegate_researcher", "consult_researcher", "delegate_builder", "consult_builder", "delegate_writer", "consult_writer", "delegate_image_generator", "consult_image_generator", "delegate_voorman", "consult_voorman", "delegate_meester", "consult_meester", "ask_user_question", "list_projects", "start_project", "fetch_repo", "fetch_diff", "update_project", "list_project_gezels", "add_gezel_to_project", "remove_gezel_from_project", "list_suggested_work", "enable_suggested_work", "disable_suggested_work", "list_tasks", "get_task", "create_task", "start_plan", "update_task", "set_outcomes", "verify_outcome", "add_verification_step", "spawn_task_instances", "list_task_children", "set_task_status", "activate_task", "assign_task", "add_task_step", "advance_task_step", "read_task_notes", "write_task_note", "search_history", "search_sessions", "how_do_i", "render_image", "generate_image", "describe_image", "read_image_metadata", "generate_video", "transcribe_audio", "synthesize_speech", "fetch_url", "web_search", "wikipedia_search", "grep_files", "find_files", "diff_files", "read_image_as_base64", "outline_file", "find_symbol", "read_symbol", "find_references", "map_repo", "search_code", "file_review", "list_file_issues", "get_file_issue", "set_file_issue_status", "security_scan", "security_overview", "scan_findings", "map_attack_surface", "list_dependencies", "trace_taint", "search_docs", "read_doc_as_markdown", "search_images", "find_similar_images", "describe_folder", "find_entity", "list_entity_mentions", "list_archive", "extract_archive", "run_git", "list_scripts", "run_installed_script", "get_script_run", "list_craftbooks", "suggest_craftbook", "invoke_craftbook", "import_skill", "craftbook_read", "craftbook_write", "craftbook_add_step", "set_step_deliverable", "craftbook_remove_step", "craftbook_reorder_steps", "craftbook_set_entry", "craftbook_update", "export_task_craftbook", "github_pr_list", "github_pr_view", "github_pr_files", "github_pr_diff", "github_pr_comments", "github_pr_comment", "github_pr_create", "github_workflow_runs", "github_check_status"];
21
+ declare const ALWAYS_REGISTERED_TOOLS: readonly ["search_memory", "save_memory", "list_memories", "list_dir", "read_file", "read_files", "stat", "write_file", "append_to_file", "replace_in_file", "replace_lines", "apply_patch", "insert_at_marker", "delete_path", "make_dir", "rename", "copy_artifact_to_workspace", "validate", "npm_install", "list_package_scripts", "run_package_script", "run_npx", "run_nodejs_script", "derive_file", "list_packages", "run_playwright_script", "list_artifacts", "read_artifact", "write_artifact", "grep_artifact", "browser_find_page_element", "list_documents", "read_document", "write_document", "delete_document", "search_documents", "list_gezels", "create_gezel", "list_gilde", "list_project_types", "apply_project_type", "start_project_from_type", "export_project_type", "import_project_type", "ensure_gezel", "update_gezel", "message_gezel", "ask_gezel", "ask_specialist", "delegate_developer", "consult_developer", "delegate_designer", "consult_designer", "delegate_reviewer", "consult_reviewer", "delegate_planner", "consult_planner", "delegate_researcher", "consult_researcher", "delegate_builder", "consult_builder", "delegate_writer", "consult_writer", "delegate_image_generator", "consult_image_generator", "delegate_voorman", "consult_voorman", "delegate_meester", "consult_meester", "ask_user_question", "list_projects", "start_project", "fetch_repo", "fetch_diff", "update_project", "list_project_gezels", "add_gezel_to_project", "remove_gezel_from_project", "list_suggested_work", "enable_suggested_work", "disable_suggested_work", "list_tasks", "get_task", "create_task", "start_plan", "update_task", "set_outcomes", "verify_outcome", "add_verification_step", "spawn_task_instances", "list_task_children", "set_task_status", "activate_task", "assign_task", "add_task_step", "advance_task_step", "read_task_notes", "write_task_note", "search_history", "search_sessions", "how_do_i", "render_image", "generate_image", "describe_image", "read_image_metadata", "generate_video", "transcribe_audio", "synthesize_speech", "fetch_url", "web_search", "wikipedia_search", "grep_files", "find_files", "diff_files", "read_image_as_base64", "outline_file", "find_symbol", "read_symbol", "find_references", "map_repo", "search_code", "file_review", "list_file_issues", "get_file_issue", "set_file_issue_status", "security_scan", "security_overview", "scan_findings", "map_attack_surface", "list_dependencies", "trace_taint", "search_docs", "read_doc_as_markdown", "search_images", "find_similar_images", "describe_folder", "find_entity", "list_entity_mentions", "list_archive", "extract_archive", "run_git", "list_scripts", "run_installed_script", "get_script_run", "list_craftbooks", "suggest_craftbook", "invoke_craftbook", "import_skill", "craftbook_read", "craftbook_write", "craftbook_add_step", "set_step_deliverable", "craftbook_remove_step", "craftbook_reorder_steps", "craftbook_set_entry", "craftbook_update", "export_task_craftbook", "github_pr_list", "github_pr_view", "github_pr_files", "github_pr_file", "github_pr_diff", "github_pr_comments", "github_pr_comment", "github_pr_create", "github_workflow_runs", "github_check_status"];
22
22
  /**
23
23
  * Tools registered only when their feature or session-context gate is set
24
24
  * in the env. Keep contextual/compatibility tools here so inventory users
package/dist/index.js CHANGED
@@ -192,6 +192,7 @@ var ALWAYS_REGISTERED_TOOLS = [
192
192
  "github_pr_list",
193
193
  "github_pr_view",
194
194
  "github_pr_files",
195
+ "github_pr_file",
195
196
  "github_pr_diff",
196
197
  "github_pr_comments",
197
198
  "github_pr_comment",
package/dist/server.js CHANGED
@@ -776,6 +776,7 @@ var ALWAYS_REGISTERED_TOOLS = [
776
776
  "github_pr_list",
777
777
  "github_pr_view",
778
778
  "github_pr_files",
779
+ "github_pr_file",
779
780
  "github_pr_diff",
780
781
  "github_pr_comments",
781
782
  "github_pr_comment",
@@ -1247,6 +1248,7 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
1247
1248
  "github_pr_list",
1248
1249
  "github_pr_view",
1249
1250
  "github_pr_files",
1251
+ "github_pr_file",
1250
1252
  "github_pr_diff",
1251
1253
  "github_pr_comments",
1252
1254
  "github_workflow_runs",
@@ -1348,6 +1350,7 @@ var OPEN_WORLD_TOOLS = /* @__PURE__ */ new Set([
1348
1350
  "github_pr_list",
1349
1351
  "github_pr_view",
1350
1352
  "github_pr_files",
1353
+ "github_pr_file",
1351
1354
  "github_pr_diff",
1352
1355
  "github_pr_comments",
1353
1356
  "github_pr_comment",
@@ -3256,7 +3259,7 @@ ${listing}` : summary }
3256
3259
  );
3257
3260
  server.tool(
3258
3261
  "read_file",
3259
- "Read one workspace file, optionally only an inclusive line range. For files over ~200 lines, pass `startLine`/`endLine` from grep_files, outline_file, or an error instead of loading the whole file. Omit both range fields for the backward-compatible full read. Output uses `N\u2192` line gutters for precise edits; the gutter is display-only and is never part of the file. Pass `raw: true` for text without gutters.",
3262
+ "Read one project-workspace file, optionally only an inclusive line range. This tool never reads the separate artifacts drawer; use read_artifact for artifact inputs. For files over ~200 lines, pass `startLine`/`endLine` from grep_files, outline_file, or an error instead of loading the whole file. Omit both range fields for the backward-compatible full read. Output uses `N\u2192` line gutters for precise edits; the gutter is display-only and is never part of the file. Pass `raw: true` for text without gutters.",
3260
3263
  {
3261
3264
  path: z5.string().min(1).max(4096).describe("File path relative to the project root."),
3262
3265
  startLine: z5.number().int().min(1).max(1e7).optional().describe("1-based first line to return (inclusive). Defaults to 1."),
@@ -3301,6 +3304,11 @@ server.tool(
3301
3304
  const base = unwrapApiError(err);
3302
3305
  let text = `read_file "${path}": ${base}`;
3303
3306
  if (/not found|404|no such file/i.test(base)) {
3307
+ const artifactCollision = await artifactCollisionForWorkspacePath(path);
3308
+ if (artifactCollision) {
3309
+ text += `. A project artifact exists at "${artifactCollision}". The workspace and artifacts are separate drawers; call read_artifact({ path: ${JSON.stringify(artifactCollision)} }) instead of read_file. The artifact was not opened automatically.`;
3310
+ return { content: [{ type: "text", text }], isError: true };
3311
+ }
3304
3312
  try {
3305
3313
  const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
3306
3314
  const listing = await api.listProjectWorkspace(projectId, dir, false);
@@ -3570,7 +3578,12 @@ server.tool(
3570
3578
  ]
3571
3579
  };
3572
3580
  } catch (err) {
3573
- const message = err instanceof Error ? err.message : String(err);
3581
+ let message = unwrapApiError(err);
3582
+ if (/artifact not found/i.test(message) && source.includes("://")) {
3583
+ message += `
3584
+
3585
+ \`source\` must be a path inside the artifacts drawer, not a tool-returned URI like "${source}". Call \`list_artifacts\` to see the real paths, then retry with the one you saved (e.g. \`deliverables/d-day.pptx\`). Do not write the file by hand instead \u2014 \`write_file\` corrupts binaries.`;
3586
+ }
3574
3587
  return {
3575
3588
  content: [{ type: "text", text: message }],
3576
3589
  isError: true
@@ -3837,7 +3850,7 @@ server.tool(
3837
3850
  newProjectId = project.id;
3838
3851
  resolvedName = project.name;
3839
3852
  } catch (err) {
3840
- const message = err instanceof Error ? err.message : String(err);
3853
+ const message = unwrapApiError(err);
3841
3854
  return {
3842
3855
  content: [{ type: "text", text: `fetch_diff: createProject failed: ${message}` }],
3843
3856
  isError: true
@@ -3863,7 +3876,7 @@ server.tool(
3863
3876
  ]
3864
3877
  };
3865
3878
  } catch (err) {
3866
- const message = err instanceof Error ? err.message : String(err);
3879
+ const message = unwrapApiError(err);
3867
3880
  return {
3868
3881
  content: [
3869
3882
  {
@@ -4891,6 +4904,15 @@ async function workspaceCollisionForArtifactPath(cleanPath) {
4891
4904
  }
4892
4905
  return null;
4893
4906
  }
4907
+ async function artifactCollisionForWorkspacePath(path) {
4908
+ try {
4909
+ const cleanPath = normalizeArtifactPath(path);
4910
+ const result = await api.readProjectArtifactSlice(projectId, cleanPath, { head: 0 });
4911
+ return result.kind === "found" && !result.fuzzy ? result.path : null;
4912
+ } catch {
4913
+ return null;
4914
+ }
4915
+ }
4894
4916
  var WORKSPACE_DELIVERABLE_EXTENSIONS = /* @__PURE__ */ new Set([
4895
4917
  "html",
4896
4918
  "htm",
@@ -7460,7 +7482,7 @@ The runtime posted the card (id ${res.questionId}). The user sees it in chat, on
7460
7482
  ]
7461
7483
  };
7462
7484
  } catch (err) {
7463
- const message = err instanceof Error ? err.message : String(err);
7485
+ const message = unwrapApiError(err);
7464
7486
  return errorResult(
7465
7487
  `ask_user_question failed: ${message}. Retry the call with corrected arguments \u2014 \`question\` must be a non-empty string and \`choices\` (when used) must be a real JSON array like \`["A","B","C"]\` (not a stringified one). Do NOT fall back to asking the question in prose; the user's notification depends on this tool firing.`,
7466
7488
  { retryable: true }
@@ -9272,14 +9294,14 @@ ${pausedNote}`,
9272
9294
  );
9273
9295
  server.tool(
9274
9296
  "read_task_notes",
9275
- "Read the chronological feed of timestamped notes for a task (or a specific step). Each entry has an author (a gezel or the user) and was appended at a known time \u2014 newest first.",
9297
+ "Read the chronological feed of timestamped notes for a task (or a specific step). Omit stepId to read the whole task feed across every step. Each entry has an author (a gezel or the user) and was appended at a known time \u2014 newest first.",
9276
9298
  {
9277
9299
  ref: z5.string(),
9278
9300
  stepId: z5.string().optional()
9279
9301
  },
9280
9302
  async ({ ref, stepId }) => {
9281
9303
  const parsed = parseRef(ref);
9282
- const effectiveStep = stepId ?? (sessionStepId || void 0);
9304
+ const effectiveStep = stepId?.trim() || void 0;
9283
9305
  const { notes } = await api.listTaskNotes(parsed.projectId, parsed.num, effectiveStep);
9284
9306
  const summary = `Loaded ${notes.length} ${notes.length === 1 ? "note" : "notes"} for ${ref}${effectiveStep ? `/${effectiveStep}` : ""}.`;
9285
9307
  return okResult(
@@ -9535,7 +9557,7 @@ To embed this in HTML at \`workspace/<name>.html\`, use:
9535
9557
  ]
9536
9558
  };
9537
9559
  } catch (err) {
9538
- const msg = err instanceof Error ? err.message : String(err);
9560
+ const msg = unwrapApiError(err);
9539
9561
  return errorResult(
9540
9562
  `Render failed: ${msg}. Check that Chromium has finished installing (it downloads in the background on first boot).`,
9541
9563
  { retryable: true }
@@ -9834,7 +9856,7 @@ server.tool(
9834
9856
 
9835
9857
  ${body}` }] };
9836
9858
  } catch (err) {
9837
- const msg = err instanceof Error ? err.message : String(err);
9859
+ const msg = unwrapApiError(err);
9838
9860
  return {
9839
9861
  content: [{ type: "text", text: `fetch_url failed: ${msg}` }],
9840
9862
  isError: true
@@ -9857,7 +9879,7 @@ server.tool(
9857
9879
  const res = await api.toolWebSearch(projectId, args);
9858
9880
  return { content: [{ type: "text", text: formatWebSearchResponse(res) }] };
9859
9881
  } catch (err) {
9860
- const msg = err instanceof Error ? err.message : String(err);
9882
+ const msg = unwrapApiError(err);
9861
9883
  return {
9862
9884
  content: [{ type: "text", text: `web_search failed: ${msg}` }],
9863
9885
  isError: true
@@ -9880,7 +9902,7 @@ server.tool(
9880
9902
  const res = await api.toolWikipediaSearch(projectId, args);
9881
9903
  return { content: [{ type: "text", text: formatWebSearchResponse(res) }] };
9882
9904
  } catch (err) {
9883
- const msg = err instanceof Error ? err.message : String(err);
9905
+ const msg = unwrapApiError(err);
9884
9906
  return {
9885
9907
  content: [{ type: "text", text: `wikipedia_search failed: ${msg}` }],
9886
9908
  isError: true
@@ -9979,7 +10001,7 @@ ${res.files.join("\n") || "(none)"}${truncation}` }
9979
10001
  ${lines.join("\n") || "(no matches)"}${truncation}` }
9980
10002
  );
9981
10003
  } catch (err) {
9982
- const msg = err instanceof Error ? err.message : String(err);
10004
+ const msg = unwrapApiError(err);
9983
10005
  return errorResult(`grep_files failed: ${msg}`);
9984
10006
  }
9985
10007
  }
@@ -10010,7 +10032,7 @@ server.tool(
10010
10032
  ${res.files.join("\n") || "(none)"}` }
10011
10033
  );
10012
10034
  } catch (err) {
10013
- const msg = err instanceof Error ? err.message : String(err);
10035
+ const msg = unwrapApiError(err);
10014
10036
  return errorResult(`find_files failed: ${msg}`);
10015
10037
  }
10016
10038
  }
@@ -10045,7 +10067,7 @@ health ${res.review.health}/10 \u2014 ${res.review.healthReason} (${tail})`;
10045
10067
  return { content: [{ type: "text", text: `${head}${summary}${health}
10046
10068
  ${body}` }] };
10047
10069
  } catch (err) {
10048
- const msg = err instanceof Error ? err.message : String(err);
10070
+ const msg = unwrapApiError(err);
10049
10071
  return {
10050
10072
  content: [{ type: "text", text: `outline_file failed: ${msg}` }],
10051
10073
  isError: true
@@ -10100,7 +10122,7 @@ ${issues.join("\n")}` : "issues: none",
10100
10122
  ].join("\n");
10101
10123
  return { content: [{ type: "text", text }] };
10102
10124
  } catch (err) {
10103
- const msg = err instanceof Error ? err.message : String(err);
10125
+ const msg = unwrapApiError(err);
10104
10126
  return {
10105
10127
  content: [{ type: "text", text: `file_review failed: ${msg}` }],
10106
10128
  isError: true
@@ -10131,7 +10153,7 @@ server.tool(
10131
10153
  ]
10132
10154
  };
10133
10155
  } catch (err) {
10134
- const msg = err instanceof Error ? err.message : String(err);
10156
+ const msg = unwrapApiError(err);
10135
10157
  return {
10136
10158
  content: [{ type: "text", text: `get_file_issue failed: ${msg}` }],
10137
10159
  isError: true
@@ -10160,7 +10182,7 @@ server.tool(
10160
10182
  ]
10161
10183
  };
10162
10184
  } catch (err) {
10163
- const msg = err instanceof Error ? err.message : String(err);
10185
+ const msg = unwrapApiError(err);
10164
10186
  return {
10165
10187
  content: [{ type: "text", text: `set_file_issue_status failed: ${msg}` }],
10166
10188
  isError: true
@@ -10193,7 +10215,7 @@ ${lines.join("\n") || "(none \u2014 index may still be building)"}`
10193
10215
  ]
10194
10216
  };
10195
10217
  } catch (err) {
10196
- const msg = err instanceof Error ? err.message : String(err);
10218
+ const msg = unwrapApiError(err);
10197
10219
  return {
10198
10220
  content: [{ type: "text", text: `find_symbol failed: ${msg}` }],
10199
10221
  isError: true
@@ -10221,7 +10243,7 @@ server.tool(
10221
10243
  ---
10222
10244
  ${res.source ?? ""}` }] };
10223
10245
  } catch (err) {
10224
- const msg = err instanceof Error ? err.message : String(err);
10246
+ const msg = unwrapApiError(err);
10225
10247
  return {
10226
10248
  content: [{ type: "text", text: `read_symbol failed: ${msg}` }],
10227
10249
  isError: true
@@ -10249,7 +10271,7 @@ ${lines.join("\n") || "(no references)"}` }
10249
10271
  ]
10250
10272
  };
10251
10273
  } catch (err) {
10252
- const msg = err instanceof Error ? err.message : String(err);
10274
+ const msg = unwrapApiError(err);
10253
10275
  return {
10254
10276
  content: [{ type: "text", text: `find_references failed: ${msg}` }],
10255
10277
  isError: true
@@ -10290,7 +10312,7 @@ server.tool(
10290
10312
  ].join("\n");
10291
10313
  return { content: [{ type: "text", text }] };
10292
10314
  } catch (err) {
10293
- const msg = err instanceof Error ? err.message : String(err);
10315
+ const msg = unwrapApiError(err);
10294
10316
  return {
10295
10317
  content: [{ type: "text", text: `map_repo failed: ${msg}` }],
10296
10318
  isError: true
@@ -10330,7 +10352,7 @@ ${lines.join("\n") || "(no results \u2014 index may still be enriching; use grep
10330
10352
  }
10331
10353
  );
10332
10354
  } catch (err) {
10333
- const msg = err instanceof Error ? err.message : String(err);
10355
+ const msg = unwrapApiError(err);
10334
10356
  return errorResult(`search_code failed: ${msg}`);
10335
10357
  }
10336
10358
  }
@@ -10360,7 +10382,7 @@ server.tool(
10360
10382
  ].join("\n");
10361
10383
  return { content: [{ type: "text", text }] };
10362
10384
  } catch (err) {
10363
- const msg = err instanceof Error ? err.message : String(err);
10385
+ const msg = unwrapApiError(err);
10364
10386
  return {
10365
10387
  content: [{ type: "text", text: `security_scan failed: ${msg}` }],
10366
10388
  isError: true
@@ -10395,7 +10417,7 @@ ${themes || " (none recurring across \u22653 files)"}`
10395
10417
  ].join("\n");
10396
10418
  return { content: [{ type: "text", text }] };
10397
10419
  } catch (err) {
10398
- const msg = err instanceof Error ? err.message : String(err);
10420
+ const msg = unwrapApiError(err);
10399
10421
  return {
10400
10422
  content: [{ type: "text", text: `security_overview failed: ${msg}` }],
10401
10423
  isError: true
@@ -10432,7 +10454,7 @@ ${lines.join("\n") || "(none matched)"}` }
10432
10454
  ]
10433
10455
  };
10434
10456
  } catch (err) {
10435
- const msg = err instanceof Error ? err.message : String(err);
10457
+ const msg = unwrapApiError(err);
10436
10458
  return {
10437
10459
  content: [{ type: "text", text: `scan_findings failed: ${msg}` }],
10438
10460
  isError: true
@@ -10479,7 +10501,7 @@ ${lines.join("\n") || "(none matched)"}${reviewerLine}${tail}`
10479
10501
  ]
10480
10502
  };
10481
10503
  } catch (err) {
10482
- const msg = err instanceof Error ? err.message : String(err);
10504
+ const msg = unwrapApiError(err);
10483
10505
  return {
10484
10506
  content: [{ type: "text", text: `list_file_issues failed: ${msg}` }],
10485
10507
  isError: true
@@ -10509,7 +10531,7 @@ server.tool(
10509
10531
  ].join("\n");
10510
10532
  return { content: [{ type: "text", text }] };
10511
10533
  } catch (err) {
10512
- const msg = err instanceof Error ? err.message : String(err);
10534
+ const msg = unwrapApiError(err);
10513
10535
  return {
10514
10536
  content: [{ type: "text", text: `map_attack_surface failed: ${msg}` }],
10515
10537
  isError: true
@@ -10543,7 +10565,7 @@ server.tool(
10543
10565
  ${lines.join("\n") || "(none)"}` }]
10544
10566
  };
10545
10567
  } catch (err) {
10546
- const msg = err instanceof Error ? err.message : String(err);
10568
+ const msg = unwrapApiError(err);
10547
10569
  return {
10548
10570
  content: [{ type: "text", text: `list_dependencies failed: ${msg}` }],
10549
10571
  isError: true
@@ -10578,7 +10600,7 @@ ${fmt(res.sinks)}`
10578
10600
  ].join("\n");
10579
10601
  return { content: [{ type: "text", text }] };
10580
10602
  } catch (err) {
10581
- const msg = err instanceof Error ? err.message : String(err);
10603
+ const msg = unwrapApiError(err);
10582
10604
  return {
10583
10605
  content: [{ type: "text", text: `trace_taint failed: ${msg}` }],
10584
10606
  isError: true
@@ -10605,7 +10627,7 @@ server.tool(
10605
10627
  ${lines.join("\n") || "(none)"}` }]
10606
10628
  };
10607
10629
  } catch (err) {
10608
- const msg = err instanceof Error ? err.message : String(err);
10630
+ const msg = unwrapApiError(err);
10609
10631
  return {
10610
10632
  content: [{ type: "text", text: `search_images failed: ${msg}` }],
10611
10633
  isError: true
@@ -10644,7 +10666,7 @@ ${lines.join("\n") || "(none)"}`
10644
10666
  ]
10645
10667
  };
10646
10668
  } catch (err) {
10647
- const msg = err instanceof Error ? err.message : String(err);
10669
+ const msg = unwrapApiError(err);
10648
10670
  return {
10649
10671
  content: [{ type: "text", text: `find_similar_images failed: ${msg}` }],
10650
10672
  isError: true
@@ -10671,7 +10693,7 @@ server.tool(
10671
10693
  ].join("\n");
10672
10694
  return { content: [{ type: "text", text }] };
10673
10695
  } catch (err) {
10674
- const msg = err instanceof Error ? err.message : String(err);
10696
+ const msg = unwrapApiError(err);
10675
10697
  return {
10676
10698
  content: [{ type: "text", text: `describe_folder failed: ${msg}` }],
10677
10699
  isError: true
@@ -10701,7 +10723,7 @@ ${lines.join("\n") || "(none \u2014 index may have no structured metadata yet)"}
10701
10723
  ]
10702
10724
  };
10703
10725
  } catch (err) {
10704
- const msg = err instanceof Error ? err.message : String(err);
10726
+ const msg = unwrapApiError(err);
10705
10727
  return {
10706
10728
  content: [{ type: "text", text: `find_entity failed: ${msg}` }],
10707
10729
  isError: true
@@ -10734,7 +10756,7 @@ server.tool(
10734
10756
  return { content: [{ type: "text", text: `${head}
10735
10757
  ${lines.join("\n")}` }] };
10736
10758
  } catch (err) {
10737
- const msg = err instanceof Error ? err.message : String(err);
10759
+ const msg = unwrapApiError(err);
10738
10760
  return {
10739
10761
  content: [{ type: "text", text: `list_entity_mentions failed: ${msg}` }],
10740
10762
  isError: true
@@ -10761,7 +10783,7 @@ ${lines.join("\n") || "(no matches)"}` }
10761
10783
  ]
10762
10784
  };
10763
10785
  } catch (err) {
10764
- const msg = err instanceof Error ? err.message : String(err);
10786
+ const msg = unwrapApiError(err);
10765
10787
  return {
10766
10788
  content: [{ type: "text", text: `search_docs failed: ${msg}` }],
10767
10789
  isError: true
@@ -10789,7 +10811,7 @@ server.tool(
10789
10811
  ---
10790
10812
  ${res.markdown ?? ""}` }] };
10791
10813
  } catch (err) {
10792
- const msg = err instanceof Error ? err.message : String(err);
10814
+ const msg = unwrapApiError(err);
10793
10815
  return {
10794
10816
  content: [{ type: "text", text: `read_doc_as_markdown failed: ${msg}` }],
10795
10817
  isError: true
@@ -10826,7 +10848,7 @@ server.tool(
10826
10848
  }
10827
10849
  return { content: [{ type: "text", text: res.diff }] };
10828
10850
  } catch (err) {
10829
- const msg = err instanceof Error ? err.message : String(err);
10851
+ const msg = unwrapApiError(err);
10830
10852
  return {
10831
10853
  content: [{ type: "text", text: `diff_files failed: ${msg}` }],
10832
10854
  isError: true
@@ -10854,7 +10876,7 @@ server.tool(
10854
10876
  ]
10855
10877
  };
10856
10878
  } catch (err) {
10857
- const msg = err instanceof Error ? err.message : String(err);
10879
+ const msg = unwrapApiError(err);
10858
10880
  return {
10859
10881
  content: [{ type: "text", text: `read_image_as_base64 failed: ${msg}` }],
10860
10882
  isError: true
@@ -10903,7 +10925,7 @@ server.tool(
10903
10925
  }
10904
10926
  return { content: [{ type: "text", text: parts.join("\n") }] };
10905
10927
  } catch (err) {
10906
- const msg = err instanceof Error ? err.message : String(err);
10928
+ const msg = unwrapApiError(err);
10907
10929
  return {
10908
10930
  content: [{ type: "text", text: `describe_image failed: ${msg}` }],
10909
10931
  isError: true
@@ -10952,7 +10974,7 @@ server.tool(
10952
10974
  }
10953
10975
  return { content: [{ type: "text", text: lines.join("\n") }] };
10954
10976
  } catch (err) {
10955
- const msg = err instanceof Error ? err.message : String(err);
10977
+ const msg = unwrapApiError(err);
10956
10978
  return {
10957
10979
  content: [{ type: "text", text: `read_image_metadata failed: ${msg}` }],
10958
10980
  isError: true
@@ -10977,7 +10999,7 @@ server.tool(
10977
10999
  return { content: [{ type: "text", text: `${header}
10978
11000
  ${lines.join("\n")}` }] };
10979
11001
  } catch (err) {
10980
- const msg = err instanceof Error ? err.message : String(err);
11002
+ const msg = unwrapApiError(err);
10981
11003
  return {
10982
11004
  content: [{ type: "text", text: `list_archive failed: ${msg}` }],
10983
11005
  isError: true
@@ -11004,7 +11026,7 @@ server.tool(
11004
11026
  ]
11005
11027
  };
11006
11028
  } catch (err) {
11007
- const msg = err instanceof Error ? err.message : String(err);
11029
+ const msg = unwrapApiError(err);
11008
11030
  return {
11009
11031
  content: [{ type: "text", text: `extract_archive failed: ${msg}` }],
11010
11032
  isError: true
@@ -11058,7 +11080,7 @@ ${res.stderr}` : ""}`;
11058
11080
  { text }
11059
11081
  );
11060
11082
  } catch (err) {
11061
- const msg = err instanceof Error ? err.message : String(err);
11083
+ const msg = unwrapApiError(err);
11062
11084
  return errorResult(`run_git failed: ${msg}`);
11063
11085
  }
11064
11086
  }
@@ -11133,7 +11155,7 @@ server.tool(
11133
11155
  });
11134
11156
  return formatScriptRunResult(res);
11135
11157
  } catch (err) {
11136
- const msg = err instanceof Error ? err.message : String(err);
11158
+ const msg = unwrapApiError(err);
11137
11159
  return errorResult(`run_installed_script failed: ${msg}`);
11138
11160
  }
11139
11161
  }
@@ -11166,7 +11188,7 @@ server.tool(
11166
11188
  ${JSON.stringify(run, null, 2)}` }
11167
11189
  );
11168
11190
  } catch (err) {
11169
- const msg = err instanceof Error ? err.message : String(err);
11191
+ const msg = unwrapApiError(err);
11170
11192
  return errorResult(`get_script_run failed: ${msg}`);
11171
11193
  }
11172
11194
  }
@@ -11200,7 +11222,7 @@ server.tool(
11200
11222
  });
11201
11223
  return { content: [{ type: "text", text: lines.join("\n\n") }] };
11202
11224
  } catch (err) {
11203
- const msg = err instanceof Error ? err.message : String(err);
11225
+ const msg = unwrapApiError(err);
11204
11226
  return {
11205
11227
  content: [{ type: "text", text: `github_pr_list failed: ${msg}` }],
11206
11228
  isError: true
@@ -11231,7 +11253,7 @@ server.tool(
11231
11253
  ];
11232
11254
  return { content: [{ type: "text", text: lines.join("\n") }] };
11233
11255
  } catch (err) {
11234
- const msg = err instanceof Error ? err.message : String(err);
11256
+ const msg = unwrapApiError(err);
11235
11257
  return {
11236
11258
  content: [{ type: "text", text: `github_pr_view failed: ${msg}` }],
11237
11259
  isError: true
@@ -11241,28 +11263,59 @@ server.tool(
11241
11263
  );
11242
11264
  server.tool(
11243
11265
  "github_pr_files",
11244
- "List the files changed in a PR with per-file additions, deletions, and a truncated patch hunk. Use this when you want a structured per-file view; for the full unified diff use github_pr_diff.",
11266
+ "List a bounded page of files changed in a PR. Defaults to compact metadata only so filenames later in a large PR are never hidden behind early patch bodies. Follow `nextOffset` until `hasMore: false`; set includePatch only for a small page, or use github_pr_file for one path.",
11245
11267
  {
11246
11268
  project: z5.string().optional(),
11247
- number: z5.number().int().positive()
11269
+ number: z5.number().int().positive(),
11270
+ offset: z5.number().int().nonnegative().optional().describe("Zero-based file offset (default 0)."),
11271
+ limit: z5.number().int().min(1).max(200).optional().describe("Files per page (default 100)."),
11272
+ paths: z5.array(z5.string().min(1)).max(50).optional().describe("Optional exact changed paths to select."),
11273
+ includePatch: z5.boolean().optional().describe("Include bounded patches for this page. Defaults false.")
11248
11274
  },
11249
- async ({ project, number }) => {
11275
+ async ({ project, number, offset, limit, paths, includePatch }) => {
11250
11276
  const resolved = project ? await resolveProjectId(project) : projectId;
11251
11277
  try {
11252
- const res = await api.listProjectGitHubPullFiles(resolved, number);
11278
+ const res = await api.listProjectGitHubPullFiles(resolved, number, {
11279
+ ...offset !== void 0 ? { offset } : {},
11280
+ ...limit !== void 0 ? { limit } : {},
11281
+ ...paths ? { paths } : {},
11282
+ includePatch: includePatch === true
11283
+ });
11253
11284
  if (!res.files.length) {
11254
- return { content: [{ type: "text", text: "No file changes in this PR." }] };
11285
+ return {
11286
+ content: [
11287
+ {
11288
+ type: "text",
11289
+ text: paths?.length ? `No changed files matched: ${paths.join(", ")}` : "No file changes in this PR."
11290
+ }
11291
+ ]
11292
+ };
11255
11293
  }
11256
11294
  const blocks = res.files.map((f) => {
11257
11295
  const header = `${f.filename} \u2014 ${f.status} (+${f.additions} \u2212${f.deletions})`;
11258
- return f.patch ? `${header}
11296
+ if (!f.patch) return header;
11297
+ const truncation = f.patchTruncated ? `
11298
+ [patch truncated: returned ${f.patch.length} of ${f.patchChars ?? "?"} chars; call github_pr_diff with path="${f.filename}" and nextOffset until complete]` : "";
11299
+ return `${header}
11259
11300
  \`\`\`diff
11260
11301
  ${f.patch}
11261
- \`\`\`` : header;
11302
+ \`\`\`${truncation}`;
11262
11303
  });
11263
- return { content: [{ type: "text", text: blocks.join("\n\n") }] };
11304
+ const start = res.offset ?? offset ?? 0;
11305
+ const total = res.totalFiles ?? res.files.length;
11306
+ const end = start + res.files.length;
11307
+ const coverage = [
11308
+ `Coverage: files ${start + 1}-${end} of ${total}${res.allFiles !== void 0 && res.allFiles !== total ? ` selected from ${res.allFiles} PR files` : ""}.`,
11309
+ `Patches: ${res.includesPatch ? "included where available" : "omitted (metadata-only)"}.`,
11310
+ res.hasMore ? `hasMore: true; nextOffset: ${res.nextOffset ?? end}. Call github_pr_files again with that offset.` : "hasMore: false; this selection is complete."
11311
+ ].join("\n");
11312
+ return {
11313
+ content: [{ type: "text", text: `${coverage}
11314
+
11315
+ ${blocks.join("\n\n")}` }]
11316
+ };
11264
11317
  } catch (err) {
11265
- const msg = err instanceof Error ? err.message : String(err);
11318
+ const msg = unwrapApiError(err);
11266
11319
  return {
11267
11320
  content: [{ type: "text", text: `github_pr_files failed: ${msg}` }],
11268
11321
  isError: true
@@ -11270,20 +11323,81 @@ ${f.patch}
11270
11323
  }
11271
11324
  }
11272
11325
  );
11326
+ server.tool(
11327
+ "github_pr_file",
11328
+ "Fetch one changed path and its bounded patch. Use this after github_pr_files identifies a file; if the patch is truncated, continue with github_pr_diff({ number, path, offset: nextOffset }).",
11329
+ {
11330
+ project: z5.string().optional(),
11331
+ number: z5.number().int().positive(),
11332
+ path: z5.string().min(1).describe("Exact changed path from github_pr_files.")
11333
+ },
11334
+ async ({ project, number, path }) => {
11335
+ const resolved = project ? await resolveProjectId(project) : projectId;
11336
+ try {
11337
+ const res = await api.listProjectGitHubPullFiles(resolved, number, {
11338
+ paths: [path],
11339
+ limit: 1,
11340
+ includePatch: true
11341
+ });
11342
+ const file = res.files[0];
11343
+ if (!file) {
11344
+ return {
11345
+ content: [{ type: "text", text: `Changed path not found: ${path}` }],
11346
+ isError: true
11347
+ };
11348
+ }
11349
+ const header = `${file.filename} \u2014 ${file.status} (+${file.additions} \u2212${file.deletions})`;
11350
+ const patch = file.patch ? `
11351
+
11352
+ \`\`\`diff
11353
+ ${file.patch}
11354
+ \`\`\`` : "\n\n(No patch returned.)";
11355
+ const truncation = file.patchTruncated ? `
11356
+
11357
+ Patch truncated: returned ${file.patch?.length ?? 0} of ${file.patchChars ?? "?"} chars. Call github_pr_diff({ number: ${number}, path: ${JSON.stringify(file.filename)} }) and follow nextOffset.` : "";
11358
+ return { content: [{ type: "text", text: `${header}${patch}${truncation}` }] };
11359
+ } catch (err) {
11360
+ const msg = unwrapApiError(err);
11361
+ return {
11362
+ content: [{ type: "text", text: `github_pr_file failed: ${msg}` }],
11363
+ isError: true
11364
+ };
11365
+ }
11366
+ }
11367
+ );
11273
11368
  server.tool(
11274
11369
  "github_pr_diff",
11275
- "Fetch the full unified diff for a PR (truncated at ~64KB). Use this to feed the diff body to the model when you want it to reason about changes holistically; for per-file iteration use github_pr_files.",
11370
+ "Fetch one explicit character page of a PR diff, optionally scoped to an exact changed path. The result always reports totalChars, truncated, and nextOffset; continue until truncated is false. For large PR discovery, page github_pr_files first instead of assuming one diff call is complete.",
11276
11371
  {
11277
11372
  project: z5.string().optional(),
11278
- number: z5.number().int().positive()
11373
+ number: z5.number().int().positive(),
11374
+ path: z5.string().min(1).optional().describe("Optional exact changed path."),
11375
+ offset: z5.number().int().nonnegative().optional().describe("Character offset (default 0)."),
11376
+ limit: z5.number().int().min(1).max(6e4).optional().describe("Characters to return (default 48,000; max 60,000).")
11279
11377
  },
11280
- async ({ project, number }) => {
11378
+ async ({ project, number, path, offset, limit }) => {
11281
11379
  const resolved = project ? await resolveProjectId(project) : projectId;
11282
11380
  try {
11283
- const res = await api.getProjectGitHubPullDiff(resolved, number);
11284
- return { content: [{ type: "text", text: res.diff || "(empty diff)" }] };
11381
+ const res = await api.getProjectGitHubPullDiff(resolved, number, {
11382
+ ...path ? { path } : {},
11383
+ ...offset !== void 0 ? { offset } : {},
11384
+ ...limit !== void 0 ? { limit } : {}
11385
+ });
11386
+ const scope = res.path ? ` for ${res.path}` : "";
11387
+ const start = res.offset ?? offset ?? 0;
11388
+ const returned = res.returnedChars ?? res.diff.length;
11389
+ const total = res.totalChars ?? res.diff.length;
11390
+ const meta = [
11391
+ `Diff page${scope}: chars ${start}-${start + returned} of ${total}.`,
11392
+ res.truncated ? `truncated: true; nextOffset: ${res.nextOffset ?? start + returned}. Continue with the same path and that offset.` : "truncated: false; this diff selection is complete."
11393
+ ].join("\n");
11394
+ return {
11395
+ content: [{ type: "text", text: `${meta}
11396
+
11397
+ ${res.diff || "(empty diff)"}` }]
11398
+ };
11285
11399
  } catch (err) {
11286
- const msg = err instanceof Error ? err.message : String(err);
11400
+ const msg = unwrapApiError(err);
11287
11401
  return {
11288
11402
  content: [{ type: "text", text: `github_pr_diff failed: ${msg}` }],
11289
11403
  isError: true
@@ -11312,7 +11426,7 @@ ${c.body}`;
11312
11426
  });
11313
11427
  return { content: [{ type: "text", text: lines.join("\n\n---\n\n") }] };
11314
11428
  } catch (err) {
11315
- const msg = err instanceof Error ? err.message : String(err);
11429
+ const msg = unwrapApiError(err);
11316
11430
  return {
11317
11431
  content: [{ type: "text", text: `github_pr_comments failed: ${msg}` }],
11318
11432
  isError: true
@@ -11336,7 +11450,7 @@ server.tool(
11336
11450
  content: [{ type: "text", text: `Posted comment ${res.id} \u2014 ${res.url}` }]
11337
11451
  };
11338
11452
  } catch (err) {
11339
- const msg = err instanceof Error ? err.message : String(err);
11453
+ const msg = unwrapApiError(err);
11340
11454
  return {
11341
11455
  content: [{ type: "text", text: `github_pr_comment failed: ${msg}` }],
11342
11456
  isError: true
@@ -11369,7 +11483,7 @@ server.tool(
11369
11483
  content: [{ type: "text", text: `Opened PR #${res.number} \u2014 ${res.url}` }]
11370
11484
  };
11371
11485
  } catch (err) {
11372
- const msg = err instanceof Error ? err.message : String(err);
11486
+ const msg = unwrapApiError(err);
11373
11487
  return {
11374
11488
  content: [{ type: "text", text: `github_pr_create failed: ${msg}` }],
11375
11489
  isError: true
@@ -11400,7 +11514,7 @@ server.tool(
11400
11514
  );
11401
11515
  return { content: [{ type: "text", text: lines.join("\n\n") }] };
11402
11516
  } catch (err) {
11403
- const msg = err instanceof Error ? err.message : String(err);
11517
+ const msg = unwrapApiError(err);
11404
11518
  return {
11405
11519
  content: [{ type: "text", text: `github_workflow_runs failed: ${msg}` }],
11406
11520
  isError: true
@@ -11433,7 +11547,7 @@ No checks reported for ${ref}.` }]
11433
11547
  return { content: [{ type: "text", text: `${header}
11434
11548
  ${lines.join("\n")}` }] };
11435
11549
  } catch (err) {
11436
- const msg = err instanceof Error ? err.message : String(err);
11550
+ const msg = unwrapApiError(err);
11437
11551
  return {
11438
11552
  content: [{ type: "text", text: `github_check_status failed: ${msg}` }],
11439
11553
  isError: true
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "Gezel MCP server — gives agents access to memory, workspace, artifacts, and tools.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -55,11 +55,11 @@
55
55
  "!dist/**/*.map"
56
56
  ],
57
57
  "dependencies": {
58
+ "@bendyline/gezel": "1.0.3",
59
+ "@bendyline/gezel-client": "1.0.3",
58
60
  "@modelcontextprotocol/sdk": "^1.29.0",
59
61
  "typescript": "^6.0.3",
60
- "zod": "^4.4.3",
61
- "@bendyline/gezel-client": "1.0.1",
62
- "@bendyline/gezel": "1.0.1"
62
+ "zod": "^4.4.3"
63
63
  },
64
64
  "devDependencies": {
65
65
  "@types/node": "^24.13.3",