@bendyline/gezel-mcp 0.1.0 → 1.0.1

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", "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_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
@@ -75,6 +75,21 @@ declare const CONDITIONALLY_REGISTERED_TOOLS: {
75
75
  readonly envValue: "1";
76
76
  readonly modelFacing: true;
77
77
  };
78
+ readonly draft_post: {
79
+ readonly envVar: "GEZEL_SOCIAL_ENABLED";
80
+ readonly envValue: "1";
81
+ readonly modelFacing: true;
82
+ };
83
+ readonly queue_post: {
84
+ readonly envVar: "GEZEL_SOCIAL_ENABLED";
85
+ readonly envValue: "1";
86
+ readonly modelFacing: true;
87
+ };
88
+ readonly publish_post: {
89
+ readonly envVar: "GEZEL_SOCIAL_ENABLED";
90
+ readonly envValue: "1";
91
+ readonly modelFacing: true;
92
+ };
78
93
  readonly draft_connector_action: {
79
94
  readonly envVar: "GEZEL_CONNECTORS_ENABLED";
80
95
  readonly envValue: "1";
package/dist/index.js CHANGED
@@ -145,6 +145,8 @@ var ALWAYS_REGISTERED_TOOLS = [
145
145
  "search_code",
146
146
  "file_review",
147
147
  "list_file_issues",
148
+ "get_file_issue",
149
+ "set_file_issue_status",
148
150
  // Security intelligence (static security analysis over the index)
149
151
  "security_scan",
150
152
  "security_overview",
@@ -240,6 +242,11 @@ var CONDITIONALLY_REGISTERED_TOOLS = {
240
242
  draft_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
241
243
  queue_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
242
244
  send_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
245
+ // Social post write tools — registered only for projects with a social-type
246
+ // connector binding (the chat manager sets GEZEL_SOCIAL_ENABLED).
247
+ draft_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
248
+ queue_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
249
+ publish_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
243
250
  // Generic connector writes are draft-only and appear only for projects
244
251
  // with at least one connector binding.
245
252
  draft_connector_action: {
@@ -17,6 +17,7 @@ async function loadBuiltinToolContracts() {
17
17
  "GEZEL_SCRIPT_TOOLS",
18
18
  "GEZEL_CRAFTBOOK_ID",
19
19
  "GEZEL_MAIL_ENABLED",
20
+ "GEZEL_SOCIAL_ENABLED",
20
21
  "GEZEL_CONNECTORS_ENABLED",
21
22
  "GEZEL_PERMISSION_PROMPT"
22
23
  ];
@@ -30,6 +31,7 @@ async function loadBuiltinToolContracts() {
30
31
  delete process.env.GEZEL_SCRIPT_TOOLS;
31
32
  process.env.GEZEL_CRAFTBOOK_ID = "schema-lint-craftbook";
32
33
  process.env.GEZEL_MAIL_ENABLED = "1";
34
+ process.env.GEZEL_SOCIAL_ENABLED = "1";
33
35
  process.env.GEZEL_CONNECTORS_ENABLED = "1";
34
36
  process.env.GEZEL_PERMISSION_PROMPT = "1";
35
37
  try {
package/dist/server.js CHANGED
@@ -10,6 +10,8 @@ import {
10
10
  GEZEL_VERSION,
11
11
  ModelTierSchema,
12
12
  NewCraftbookStepSchema,
13
+ NpmPackageNameSchema,
14
+ NpmRegistryVersionSchema,
13
15
  ProviderNameSchema,
14
16
  StepGateUnionSchema,
15
17
  TaskRefSchema,
@@ -21,7 +23,9 @@ import {
21
23
  craftbookDocFormatFromEnv,
22
24
  deliverableStep,
23
25
  expandStepDeliverable,
26
+ formatReviewProvenance,
24
27
  inferDeliverableKind,
28
+ isReservedShadowArtifactPath,
25
29
  isTrustedConstrainedToolset,
26
30
  pickRandomNameWithGender,
27
31
  removeStepAndCleanEdges,
@@ -465,6 +469,19 @@ function unavailableToolsForPlatform(platform, options = {}) {
465
469
  return DENY_NET_TOOLS;
466
470
  }
467
471
 
472
+ // src/question-prompt.ts
473
+ function composeQuestionPrompt(parts) {
474
+ const unique = [];
475
+ for (const value of [parts.question, parts.prompt, parts.description]) {
476
+ const trimmed = value?.trim();
477
+ if (trimmed && !unique.includes(trimmed)) unique.push(trimmed);
478
+ }
479
+ return unique.join("\n\n");
480
+ }
481
+ function resolveQuestionTaskRef(explicitTaskRef, sessionTaskRef2) {
482
+ return explicitTaskRef ?? (sessionTaskRef2.trim() || void 0);
483
+ }
484
+
468
485
  // src/reanchor.ts
469
486
  var REANCHOR_CONTEXT_LINES = 4;
470
487
  var REANCHOR_MAX_CHARS = 1400;
@@ -712,6 +729,8 @@ var ALWAYS_REGISTERED_TOOLS = [
712
729
  "search_code",
713
730
  "file_review",
714
731
  "list_file_issues",
732
+ "get_file_issue",
733
+ "set_file_issue_status",
715
734
  // Security intelligence (static security analysis over the index)
716
735
  "security_scan",
717
736
  "security_overview",
@@ -807,6 +826,11 @@ var CONDITIONALLY_REGISTERED_TOOLS = {
807
826
  draft_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
808
827
  queue_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
809
828
  send_email: { envVar: "GEZEL_MAIL_ENABLED", envValue: "1", modelFacing: true },
829
+ // Social post write tools — registered only for projects with a social-type
830
+ // connector binding (the chat manager sets GEZEL_SOCIAL_ENABLED).
831
+ draft_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
832
+ queue_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
833
+ publish_post: { envVar: "GEZEL_SOCIAL_ENABLED", envValue: "1", modelFacing: true },
810
834
  // Generic connector writes are draft-only and appear only for projects
811
835
  // with at least one connector binding.
812
836
  draft_connector_action: {
@@ -1124,6 +1148,9 @@ var TOOL_OUTPUT_SCHEMAS = {
1124
1148
  draft_email: ActionToolOutputSchema,
1125
1149
  queue_email: ActionToolOutputSchema,
1126
1150
  send_email: ActionToolOutputSchema,
1151
+ draft_post: ActionToolOutputSchema,
1152
+ queue_post: ActionToolOutputSchema,
1153
+ publish_post: ActionToolOutputSchema,
1127
1154
  draft_connector_action: ActionToolOutputSchema
1128
1155
  };
1129
1156
  function outputSchemaForTool(name) {
@@ -1198,6 +1225,7 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
1198
1225
  "search_code",
1199
1226
  "file_review",
1200
1227
  "list_file_issues",
1228
+ "get_file_issue",
1201
1229
  "security_overview",
1202
1230
  "scan_findings",
1203
1231
  "map_attack_surface",
@@ -1275,6 +1303,8 @@ var NON_DESTRUCTIVE_MUTATIONS = /* @__PURE__ */ new Set([
1275
1303
  "github_pr_create",
1276
1304
  "draft_email",
1277
1305
  "queue_email",
1306
+ "draft_post",
1307
+ "queue_post",
1278
1308
  "draft_connector_action",
1279
1309
  "request_tool_permission"
1280
1310
  ]);
@@ -1327,6 +1357,9 @@ var OPEN_WORLD_TOOLS = /* @__PURE__ */ new Set([
1327
1357
  "draft_email",
1328
1358
  "queue_email",
1329
1359
  "send_email",
1360
+ "draft_post",
1361
+ "queue_post",
1362
+ "publish_post",
1330
1363
  "draft_connector_action",
1331
1364
  "request_tool_permission"
1332
1365
  ]);
@@ -3012,6 +3045,147 @@ function registerEmailTools() {
3012
3045
  if (process.env.GEZEL_MAIL_ENABLED === "1") {
3013
3046
  registerEmailTools();
3014
3047
  }
3048
+ var SOCIAL_TYPE_PREFIXES = ["bluesky-", "x-", "instagram-", "linkedin-"];
3049
+ async function resolveSocialBinding(accountId) {
3050
+ const { ok, data } = await connectorActionApi("", "GET");
3051
+ if (!ok) throw new Error(String(data.error ?? "failed to list connector bindings"));
3052
+ const bindings = data.bindings ?? [];
3053
+ const social = bindings.filter(
3054
+ (b) => typeof b.type === "string" && SOCIAL_TYPE_PREFIXES.some((prefix) => b.type.startsWith(prefix))
3055
+ );
3056
+ if (accountId) {
3057
+ const match = social.find((b) => b.id === accountId)?.id;
3058
+ if (!match) throw new Error(`social connector binding "${accountId}" was not found`);
3059
+ return match;
3060
+ }
3061
+ return social[0]?.id ?? null;
3062
+ }
3063
+ function registerSocialTools() {
3064
+ server.tool(
3065
+ "draft_post",
3066
+ "Compose a social post draft and save it for review. This does NOT publish \u2014 it stages a publish action under the social connector's corpus. Use queue_post to stage it for approval and publish_post to publish. Works with any connected social account: Bluesky, X, and LinkedIn publish directly once the user enables publishing on the connection; Instagram additionally requires a publicly hosted https image URL (Meta's servers fetch the media). Every publish clears the user's consent gate.",
3067
+ {
3068
+ text: z5.string().describe("The post text (Bluesky limit: 300 characters)"),
3069
+ replyToUri: z5.string().optional().describe("at:// URI of the post being replied to, to thread the reply"),
3070
+ langs: z5.array(z5.string()).optional().describe('BCP-47 language codes for the post, e.g. ["en"]'),
3071
+ images: z5.array(
3072
+ z5.object({
3073
+ path: z5.string().describe(
3074
+ "Project-relative image path, resolved against the project's artifacts directory first, then its workspace"
3075
+ ),
3076
+ alt: z5.string().optional().describe("Alt text describing the image for accessibility")
3077
+ })
3078
+ ).max(4).optional().describe(
3079
+ "Up to 4 images to embed (png/jpg/jpeg/webp/gif, at most 1,000,000 bytes each; paths resolve against project artifacts first, then the workspace). ALWAYS write meaningful alt text for every image \u2014 never leave it blank."
3080
+ ),
3081
+ accountId: z5.string().optional().describe("Which social connector binding to post from (defaults to the first)")
3082
+ },
3083
+ async (args) => {
3084
+ try {
3085
+ const bindingId = await resolveSocialBinding(args.accountId);
3086
+ if (!bindingId) return errorResult("This project has no linked social connector.");
3087
+ const { accountId: _drop, ...input } = args;
3088
+ const { ok, data } = await connectorActionApi(
3089
+ `${encodeURIComponent(bindingId)}/actions`,
3090
+ "POST",
3091
+ { action: "publish", input }
3092
+ );
3093
+ if (!ok) return errorResult(String(data.error ?? "Post draft failed."));
3094
+ const draftId = typeof data.draftId === "string" ? data.draftId : void 0;
3095
+ const relPath = typeof data.relPath === "string" ? data.relPath : void 0;
3096
+ const summary = `Draft saved${draftId ? ` (id: ${draftId})` : ""}${relPath ? ` at ${relPath}` : ""}. Review it, then call queue_post then publish_post.`;
3097
+ return okResult(
3098
+ ActionToolOutputSchema,
3099
+ {
3100
+ summary,
3101
+ status: "drafted",
3102
+ ...draftId ? { draftId } : {},
3103
+ ...relPath ? { relPath } : {}
3104
+ },
3105
+ { text: summary }
3106
+ );
3107
+ } catch (err) {
3108
+ return errorResult(`draft_post failed: ${unwrapApiError(err)}`);
3109
+ }
3110
+ }
3111
+ );
3112
+ server.tool(
3113
+ "queue_post",
3114
+ "Stage a saved post draft for publishing by moving it to the outbox. Does not publish.",
3115
+ { draftId: z5.string().describe("The draft id returned by draft_post") },
3116
+ async ({ draftId }) => {
3117
+ try {
3118
+ const { ok, data } = await connectorActionApi(
3119
+ `actions/${encodeURIComponent(draftId)}/queue`,
3120
+ "POST"
3121
+ );
3122
+ if (!ok) return errorResult(String(data.error ?? "Post queue failed."));
3123
+ const relPath = typeof data.relPath === "string" ? data.relPath : void 0;
3124
+ const summary = `Queued draft ${draftId}${relPath ? ` (${relPath})` : ""}.`;
3125
+ return okResult(
3126
+ ActionToolOutputSchema,
3127
+ {
3128
+ summary,
3129
+ status: "queued",
3130
+ draftId,
3131
+ ...relPath ? { relPath } : {}
3132
+ },
3133
+ { text: summary }
3134
+ );
3135
+ } catch (err) {
3136
+ return errorResult(`queue_post failed: ${unwrapApiError(err)}`);
3137
+ }
3138
+ }
3139
+ );
3140
+ server.tool(
3141
+ "publish_post",
3142
+ "Publish a drafted/queued social post. The daemon enforces per-binding publish consent (publishing must be enabled on the connector, and each publish clears the social-publish consent scope) and will NOT publish during night shift (the post is staged for daytime approval instead).",
3143
+ { draftId: z5.string().describe("The draft id to publish") },
3144
+ async ({ draftId }) => {
3145
+ try {
3146
+ const { ok, data } = await connectorActionApi(
3147
+ `actions/${encodeURIComponent(draftId)}/commit`,
3148
+ "POST"
3149
+ );
3150
+ if (!ok) {
3151
+ const message = String(data.error ?? "Post publish failed.");
3152
+ const hint = /publishing is disabled/i.test(message) ? "Ask the user to enable 'Allow publishing' on the connector's settings." : void 0;
3153
+ return errorResult(message, { ...hint ? { hint } : {} });
3154
+ }
3155
+ if (data.status === "queued-night-shift") {
3156
+ const relPath = typeof data.relPath === "string" ? data.relPath : void 0;
3157
+ const summary2 = `Night shift is active \u2014 not publishing unattended. The post is staged in the outbox${relPath ? ` (${relPath})` : ""} and will require explicit approval.`;
3158
+ return okResult(
3159
+ ActionToolOutputSchema,
3160
+ {
3161
+ summary: summary2,
3162
+ status: "queued-night-shift",
3163
+ draftId,
3164
+ ...relPath ? { relPath } : {}
3165
+ },
3166
+ { text: summary2 }
3167
+ );
3168
+ }
3169
+ const result = data.result ?? {};
3170
+ const summary = `Published.${result.permalink ? ` ${result.permalink}` : result.uri ? ` ${result.uri}` : ""}`;
3171
+ return okResult(
3172
+ ActionToolOutputSchema,
3173
+ {
3174
+ summary,
3175
+ status: "published",
3176
+ draftId
3177
+ },
3178
+ { text: summary }
3179
+ );
3180
+ } catch (err) {
3181
+ return errorResult(`publish_post failed: ${unwrapApiError(err)}`);
3182
+ }
3183
+ }
3184
+ );
3185
+ }
3186
+ if (process.env.GEZEL_SOCIAL_ENABLED === "1") {
3187
+ registerSocialTools();
3188
+ }
3015
3189
  if (process.env.GEZEL_SCRIPT_TOOLS) {
3016
3190
  registerScriptTools(server, parseScriptToolSpecs(process.env.GEZEL_SCRIPT_TOOLS), {
3017
3191
  api,
@@ -4205,8 +4379,10 @@ server.tool(
4205
4379
  {
4206
4380
  packages: z5.array(
4207
4381
  z5.object({
4208
- package: z5.string().describe('Package name (e.g. "zod", "@types/node").'),
4209
- version: z5.string().optional().describe('Semver range or exact version (e.g. "^3", "3.22.4"). Defaults to "latest".')
4382
+ package: NpmPackageNameSchema.describe('Package name (e.g. "zod", "@types/node").'),
4383
+ version: NpmRegistryVersionSchema.optional().describe(
4384
+ 'Semver range or exact version (e.g. "^3", "3.22.4"). Defaults to "latest".'
4385
+ )
4210
4386
  })
4211
4387
  ).min(1).describe(
4212
4388
  "Every package you want installed, in ONE call. Combine as many as you can \u2014 batching is cheap on our side and saves the user a click per package. Only call this tool a second time if you discover a new dependency after already running code."
@@ -4291,7 +4467,7 @@ ${lines.join("\n")}` : `${summary} Add some, or use \`run_npx\` for a locally in
4291
4467
  );
4292
4468
  server.tool(
4293
4469
  "run_package_script",
4294
- "Run a `package.json` script (equivalent to `npm run <script>` / `pnpm run <script>`). Use this to build, test, lint, typecheck \u2014 anything the project already has wired up. NOT for the named project scripts `list_scripts` shows (craftbook-installed probes/ops) \u2014 run those via `run_installed_script`. Call `list_package_scripts` first if you don't know what's available. First-time invocations of a given script trigger a user approval prompt; once approved the decision sticks. SECURITY: unlike `run_nodejs_script`, package commands are not an isolation boundary. They run as the user's OS account and may spawn processes, use the network, and read or modify files outside the project. The approval dialog shows this warning and the exact command body.",
4470
+ "Run a `package.json` script (equivalent to `npm run <script>` / `pnpm run <script>`). Use this to build, test, lint, typecheck \u2014 anything the project already has wired up. NOT for the named project scripts `list_scripts` shows (craftbook-installed probes/ops) \u2014 run those via `run_installed_script`. Call `list_package_scripts` first if you don't know what's available. First-time invocations of a given script trigger a user approval prompt; the approval remains valid only while the exact invocation and identifiable local input files are unchanged. SECURITY: unlike `run_nodejs_script`, package commands are not an isolation boundary. They run as the user's OS account and may spawn processes, use the network, and read or modify files outside the project. The approval dialog shows this warning and the exact command body.",
4295
4471
  {
4296
4472
  script: z5.string().describe('Script name \u2014 a key of `package.json#scripts` (e.g. "build").'),
4297
4473
  args: coerceStringArray(
@@ -4316,7 +4492,7 @@ server.tool(
4316
4492
  );
4317
4493
  server.tool(
4318
4494
  "run_npx",
4319
- "Run a binary that a project dependency already provides (equivalent to `npx <bin> [args]`). The binary must exist in the workspace's `node_modules/.bin` or be a declared dep \u2014 unknown binaries are rejected, no auto-download. NOT for the named project scripts `list_scripts` shows \u2014 run those via `run_installed_script`. First-time invocations of a given binary trigger a user approval prompt; once approved the decision sticks. SECURITY: this is a package command, not an isolation boundary. It runs as the user's OS account and may spawn processes, use the network, and read or modify files outside the project. The approval dialog shows this warning.",
4495
+ "Run a binary that a project dependency already provides (equivalent to `npx <bin> [args]`). The binary must exist in the workspace's `node_modules/.bin` or be a declared dep \u2014 unknown binaries are rejected, no auto-download. NOT for the named project scripts `list_scripts` shows \u2014 run those via `run_installed_script`. First-time invocations of a given binary trigger a user approval prompt; the approval remains valid only while the exact invocation and identifiable local input files are unchanged. SECURITY: this is a package command, not an isolation boundary. It runs as the user's OS account and may spawn processes, use the network, and read or modify files outside the project. The approval dialog shows this warning.",
4320
4496
  {
4321
4497
  bin: z5.string().describe('Binary name (e.g. "tsc", "vitest"). Bare name, not a path.'),
4322
4498
  args: coerceStringArray(z5.array(z5.string()).optional().describe("Args passed to the binary.")),
@@ -5135,6 +5311,17 @@ server.tool(
5135
5311
  },
5136
5312
  async ({ path, content, force }) => {
5137
5313
  const clean = normalizeArtifactPath(path);
5314
+ if (isReservedShadowArtifactPath(clean)) {
5315
+ return {
5316
+ content: [
5317
+ {
5318
+ type: "text",
5319
+ text: "artifacts/shadow/ is gezel's derived shadow-file cache (converted documents, image descriptions, transcripts), regenerated automatically by indexing \u2014 anything written there would be overwritten or swept. Write your artifact elsewhere, e.g. at the artifacts root or under reports/."
5320
+ }
5321
+ ],
5322
+ isError: true
5323
+ };
5324
+ }
5138
5325
  if (isProtectedConnectorArtifactPath(clean)) {
5139
5326
  return {
5140
5327
  content: [
@@ -7188,8 +7375,10 @@ server.tool(
7188
7375
  // Common slip-ups some models reach for when they see an
7189
7376
  // "ask-a-question" tool — accept them so a naming mistake doesn't
7190
7377
  // surface as "technical error" to the user.
7191
- prompt: z5.string().optional().describe("Alias for `question`."),
7192
- description: z5.string().optional().describe("Alias for `question`."),
7378
+ prompt: z5.string().optional().describe(
7379
+ "Alias for `question`; when both are supplied, this explanatory text is preserved."
7380
+ ),
7381
+ description: z5.string().optional().describe("Alias for `question`; distinct text is preserved below the question."),
7193
7382
  choices: coerceJsonArray(
7194
7383
  z5.array(z5.string()).max(20).optional().describe(
7195
7384
  'Preset answer choices. **Always pass these when the answer is bounded** (pick a color, pick yes/no, pick one of three options). Omit only for genuinely open-ended questions. Must be an actual JSON array `["a","b"]`, not a stringified array.'
@@ -7198,7 +7387,7 @@ server.tool(
7198
7387
  allowWriteIn: z5.boolean().optional().describe("Allow free-text alongside the choices. Default true."),
7199
7388
  multiSelect: z5.boolean().optional().describe("Let the user pick more than one choice. Default false."),
7200
7389
  taskRef: TaskRefSchema.optional().describe(
7201
- 'Approval-flow context: a task this question is about, in `projectId/num` form. The UI renders the task header above the prompt with an "Open task" link.'
7390
+ 'Approval-flow context: a task this question is about, in `projectId/num` form. The current task is attached automatically in task sessions; pass this only to override it. The UI renders the task header above the prompt with an "Open task" link.'
7202
7391
  ),
7203
7392
  documentPath: z5.string().optional().describe(
7204
7393
  "Approval-flow context: a file this question is about. Accepts any of: a path under the global documents library; a path under the current project's `documents/` folder (pass just the relative path \u2014 the UI prepends the project prefix); or a path under the project's `artifacts/` folder. The server resolves in that order \u2014 you don't need to know which bucket the file lives in. The UI renders a collapsed preview + \"Open \u2026\" link with the kind chip matching what actually resolved."
@@ -7214,7 +7403,7 @@ server.tool(
7214
7403
  taskRef,
7215
7404
  documentPath
7216
7405
  }) => {
7217
- const body = (question ?? prompt ?? description ?? "").trim();
7406
+ const body = composeQuestionPrompt({ question, prompt, description });
7218
7407
  if (!body) {
7219
7408
  return {
7220
7409
  content: [
@@ -7236,6 +7425,7 @@ server.tool(
7236
7425
  };
7237
7426
  }
7238
7427
  try {
7428
+ const effectiveTaskRef = resolveQuestionTaskRef(taskRef, sessionTaskRef);
7239
7429
  const res = await api.askUserQuestion({
7240
7430
  projectId,
7241
7431
  gezelId,
@@ -7244,7 +7434,7 @@ server.tool(
7244
7434
  ...choices ? { choices } : {},
7245
7435
  ...allowWriteIn !== void 0 ? { allowWriteIn } : {},
7246
7436
  ...multiSelect !== void 0 ? { multiSelect } : {},
7247
- ...taskRef ? { taskRef } : {},
7437
+ ...effectiveTaskRef ? { taskRef: effectiveTaskRef } : {},
7248
7438
  ...documentPath ? { documentPath } : {}
7249
7439
  });
7250
7440
  if (res.deduped) {
@@ -9873,22 +10063,40 @@ server.tool(
9873
10063
  try {
9874
10064
  const res = await api.toolFileReview(projectId, args);
9875
10065
  if (!res.found || !res.review) {
9876
- const why = res.pending ? "the boekwachter has not reviewed this file yet (it studies files when idle or during Night Shift)" : "file is not in the index";
10066
+ if (res.trackedIssues?.length) {
10067
+ const tracked = res.trackedIssues.map(
10068
+ (issue) => `${issue.ref} [${issue.status}]${issue.stale ? " [needs recheck]" : ""} ${issue.category} \u2014 ${issue.message}${issue.line ? ` (${issue.stale ? "previously " : ""}L${issue.line})` : ""}${issue.taskRef ? ` \u2014 task ${issue.taskRef}` : ""}`
10069
+ );
10070
+ return {
10071
+ content: [
10072
+ {
10073
+ type: "text",
10074
+ text: `${res.path} has no current review, but its durable tracked issues remain:
10075
+ ${tracked.join("\n")}`
10076
+ }
10077
+ ]
10078
+ };
10079
+ }
10080
+ const why = res.eligible === false ? "this file type is not reviewed (no rubric covers its kind \u2014 e.g. data files, caches, media)" : res.pending ? "the boekwachter has not reviewed this file yet (it studies files when idle or during Night Shift)" : "file is not in the index";
9877
10081
  return {
9878
10082
  content: [{ type: "text", text: `file_review: no review \u2014 ${why}.` }]
9879
10083
  };
9880
10084
  }
9881
10085
  const r = res.review;
9882
- const issues = r.issues.map(
10086
+ const issues = res.trackedIssues?.length ? res.trackedIssues.map(
10087
+ (i) => `${i.ref} [${i.status}]${i.stale ? " [needs recheck]" : ""} [${i.severity}] ${i.category} \u2014 ${i.message}${i.line ? ` (${i.stale ? "previously " : ""}L${i.line})` : ""}${i.taskRef ? ` \u2014 task ${i.taskRef}` : ""}`
10088
+ ) : r.issues.map(
9883
10089
  (i) => `[${i.severity}] ${i.category} \u2014 ${i.message}${i.line ? ` (L${i.line})` : ""}`
9884
10090
  );
10091
+ const provenance = formatReviewProvenance(r);
9885
10092
  const text = [
9886
10093
  `${res.path} \u2014 health ${r.health}/10 \u2014 ${r.healthReason}`,
9887
10094
  "",
9888
10095
  r.notesMd,
9889
10096
  "",
9890
10097
  issues.length ? `issues:
9891
- ${issues.join("\n")}` : "issues: none"
10098
+ ${issues.join("\n")}` : "issues: none",
10099
+ ...provenance ? ["", provenance] : []
9892
10100
  ].join("\n");
9893
10101
  return { content: [{ type: "text", text }] };
9894
10102
  } catch (err) {
@@ -9900,6 +10108,66 @@ ${issues.join("\n")}` : "issues: none"
9900
10108
  }
9901
10109
  }
9902
10110
  );
10111
+ server.tool(
10112
+ "get_file_issue",
10113
+ "Retrieve the durable metadata for one Boekwachter issue by its BW reference: path, previous/current line state, lifecycle, read state, and linked task. Use this when a prompt or task mentions BW-N.",
10114
+ {
10115
+ ref: z5.string().regex(/^BW-[1-9]\d*$/).describe("Project-scoped reference, e.g. BW-17.")
10116
+ },
10117
+ async (args) => {
10118
+ try {
10119
+ const { issue } = await api.getBoekwachterIssue(projectId, args);
10120
+ const location = issue.line ? `${issue.path}:${issue.line}${issue.stale ? " (previous anchor; needs recheck)" : ""}` : issue.path;
10121
+ return {
10122
+ content: [
10123
+ {
10124
+ type: "text",
10125
+ text: [
10126
+ `${issue.ref} \u2014 ${issue.status} \u2014 ${location}`,
10127
+ `[${issue.severity}] ${issue.category} \u2014 ${issue.message}`,
10128
+ `read: ${issue.seen ? "yes" : "no"}${issue.taskRef ? ` \u2014 task: ${issue.taskRef}` : ""}`
10129
+ ].join("\n")
10130
+ }
10131
+ ]
10132
+ };
10133
+ } catch (err) {
10134
+ const msg = err instanceof Error ? err.message : String(err);
10135
+ return {
10136
+ content: [{ type: "text", text: `get_file_issue failed: ${msg}` }],
10137
+ isError: true
10138
+ };
10139
+ }
10140
+ }
10141
+ );
10142
+ server.tool(
10143
+ "set_file_issue_status",
10144
+ "Update a tracked Boekwachter issue by BW reference. Read/unread is independent of lifecycle. Use dismissed + not_an_issue only after verifying that the review lead is invalid; task completion normally resolves issues automatically.",
10145
+ {
10146
+ ref: z5.string().regex(/^BW-[1-9]\d*$/).describe("Project-scoped reference, e.g. BW-17."),
10147
+ status: z5.enum(["open", "in_progress", "resolved", "dismissed"]).optional(),
10148
+ seen: z5.boolean().optional().describe("true marks read; false marks unread."),
10149
+ dismissalReason: z5.enum(["not_an_issue", "duplicate", "wont_fix"]).optional()
10150
+ },
10151
+ async (args) => {
10152
+ try {
10153
+ const { issue } = await api.updateBoekwachterIssue(projectId, args);
10154
+ return {
10155
+ content: [
10156
+ {
10157
+ type: "text",
10158
+ text: `${issue.ref} is ${issue.status} and ${issue.seen ? "read" : "unread"}${issue.taskRef ? ` (task ${issue.taskRef})` : ""}.`
10159
+ }
10160
+ ]
10161
+ };
10162
+ } catch (err) {
10163
+ const msg = err instanceof Error ? err.message : String(err);
10164
+ return {
10165
+ content: [{ type: "text", text: `set_file_issue_status failed: ${msg}` }],
10166
+ isError: true
10167
+ };
10168
+ }
10169
+ }
10170
+ );
9903
10171
  server.tool(
9904
10172
  "find_symbol",
9905
10173
  "Find where a function/class/type is DEFINED across the workspace (go-to-definition). Returns path + lineStart/lineEnd; follow with read_symbol or read_file({path,startLine:lineStart,endLine:lineEnd}). Use this instead of grepping for a definition.",
@@ -10179,27 +10447,34 @@ server.tool(
10179
10447
  severity: z5.enum(["info", "minor", "major"]).optional(),
10180
10448
  category: z5.string().optional().describe("e.g. bug, smell, error-handling, grammar, clarity."),
10181
10449
  path: z5.string().optional().describe("Restrict to a path prefix."),
10450
+ status: z5.enum(["open", "in_progress", "resolved", "dismissed"]).optional(),
10451
+ includeClosed: z5.boolean().optional().describe("Include resolved and dismissed history."),
10182
10452
  maxResults: z5.number().int().positive().max(1e3).optional()
10183
10453
  },
10184
10454
  async (args) => {
10185
10455
  try {
10186
10456
  const res = await api.toolListFileIssues(projectId, args);
10187
- if (!res.indexed) {
10457
+ if (!res.indexed && res.counts.total === 0) {
10188
10458
  return {
10189
10459
  content: [{ type: "text", text: "list_file_issues: index not built yet." }]
10190
10460
  };
10191
10461
  }
10192
10462
  const head = `${res.counts.total} issue${res.counts.total === 1 ? "" : "s"} across ${res.reviewedFiles}/${res.eligibleFiles} reviewed files${res.truncated ? " (truncated)" : ""}`;
10193
10463
  const lines = res.issues.map(
10194
- (i) => `${i.path}${i.line ? `:${i.line}` : ""} [${i.severity}] ${i.category} \u2014 ${i.message}`
10464
+ (i) => `${i.ref} ${i.path}${i.line ? `:${i.line}${i.stale ? " (previous)" : ""}` : ""} [${i.status}]${i.stale ? " [needs recheck]" : ""} [${i.severity}] ${i.category} \u2014 ${i.message}${i.taskRef ? ` \u2014 task ${i.taskRef}` : ""}`
10195
10465
  );
10196
10466
  const tail = res.reviewedFiles < res.eligibleFiles ? "\n(review sweep still in progress \u2014 coverage grows when the machine is idle or during Night Shift)" : "";
10467
+ const reviewers = (res.reviewers ?? []).filter((r) => r.model).map(
10468
+ (r) => `${r.model}${r.provider ? ` (${r.provider})` : ""}${r.gezelName ? ` \xB7 ${r.gezelName}` : ""} \xD7${r.files} file${r.files === 1 ? "" : "s"}`
10469
+ );
10470
+ const reviewerLine = reviewers.length ? `
10471
+ Reviewed by ${reviewers.join(", ")}` : "";
10197
10472
  return {
10198
10473
  content: [
10199
10474
  {
10200
10475
  type: "text",
10201
10476
  text: `${head}
10202
- ${lines.join("\n") || "(none matched)"}${tail}`
10477
+ ${lines.join("\n") || "(none matched)"}${reviewerLine}${tail}`
10203
10478
  }
10204
10479
  ]
10205
10480
  };
@@ -10712,7 +10987,7 @@ ${lines.join("\n")}` }] };
10712
10987
  );
10713
10988
  server.tool(
10714
10989
  "extract_archive",
10715
- "Extract a `.zip`, `.tar`, or `.tar.gz` archive into a directory inside the project workspace. Destination is created if it does not exist. Requires the workspace to be writable (internal workspace or `project.allowGezelWrites` on external).",
10990
+ "Extract a `.zip`, `.tar`, or `.tar.gz` archive into a directory inside the project workspace. Destination is created if it does not exist. Requires Gezel-managed workspace writes to be allowed.",
10716
10991
  {
10717
10992
  path: z5.string().min(1),
10718
10993
  outputPath: z5.string().min(1)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "0.1.0",
3
+ "version": "1.0.1",
4
4
  "description": "Gezel MCP server — gives agents access to memory, workspace, artifacts, and tools.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -58,8 +58,8 @@
58
58
  "@modelcontextprotocol/sdk": "^1.29.0",
59
59
  "typescript": "^6.0.3",
60
60
  "zod": "^4.4.3",
61
- "@bendyline/gezel-client": "0.1.0",
62
- "@bendyline/gezel": "0.1.0"
61
+ "@bendyline/gezel-client": "1.0.1",
62
+ "@bendyline/gezel": "1.0.1"
63
63
  },
64
64
  "devDependencies": {
65
65
  "@types/node": "^24.13.3",