@bendyline/gezel-mcp 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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/index.d.ts CHANGED
@@ -1,293 +1,5 @@
1
- export { BranchPrioritizedPulls, PullWithHeadRef, prioritizePullsForCurrentBranch } from '@bendyline/gezel';
2
-
3
- /**
4
- * Frozen inventory of every MCP tool the gezel-mcp server registers.
5
- *
6
- * This list is the contract between gezels (their prompts, especially the
7
- * Meester's, teach specific tool names), the OpenAI provider's `mcp-bridge`
8
- * (which translates these into OpenAI function-tool shape), and the on-disk
9
- * gezel state the tools mutate.
10
- *
11
- * Adding a tool? Append its name here and `inventory.test.ts` will pass.
12
- * Renaming or removing a tool? Update this list in the same change so the
13
- * test doesn't lie about the surface.
14
- *
15
- * Tools grouped only as a reading aid — the order doesn't matter to the
16
- * test; the test compares as a set.
17
- *
18
- * Project-type script tools (`GEZEL_SCRIPT_TOOLS`, see script-tools.ts)
19
- * are deliberately NOT listed: they're per-project dynamic registrations
20
- * whose names come from the applied type's manifest, not from this frozen
21
- * contract. Registration guards them against colliding with these names.
22
- */
23
- 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", "read_artifacts", "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_ai_app", "import_ai_app", "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", "manage_task", "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", "wikimedia_image_search", "wikipedia_read", "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"];
24
- /**
25
- * Tools registered only when their feature or session-context gate is set
26
- * in the env. Keep contextual/compatibility tools here so inventory users
27
- * can distinguish them from the ordinary model-facing surface.
28
- */
29
- declare const CONDITIONALLY_REGISTERED_TOOLS: {
30
- readonly create_gezel_from_gilde: {
31
- readonly envVar: "GEZEL_MCP_LEGACY_TOOLS";
32
- readonly envValue: "1";
33
- readonly modelFacing: false;
34
- };
35
- readonly start_job: {
36
- readonly envVar: "GEZEL_MCP_LEGACY_TOOLS";
37
- readonly envValue: "1";
38
- readonly modelFacing: false;
39
- };
40
- readonly list_project_local_gezels: {
41
- readonly envVar: "GEZEL_MCP_LEGACY_TOOLS";
42
- readonly envValue: "1";
43
- readonly modelFacing: false;
44
- };
45
- readonly craftbook_create: {
46
- readonly envVar: "GEZEL_MCP_LEGACY_TOOLS";
47
- readonly envValue: "1";
48
- readonly modelFacing: false;
49
- };
50
- readonly craftbook_replace: {
51
- readonly envVar: "GEZEL_MCP_LEGACY_TOOLS";
52
- readonly envValue: "1";
53
- readonly modelFacing: false;
54
- };
55
- readonly craftbook_update_step: {
56
- readonly envVar: "GEZEL_CRAFTBOOK_STEP_EDITING";
57
- readonly envValue: "1";
58
- readonly modelFacing: true;
59
- };
60
- readonly request_tool_permission: {
61
- readonly envVar: "GEZEL_PERMISSION_PROMPT";
62
- readonly envValue: "1";
63
- readonly modelFacing: false;
64
- };
65
- readonly list_tables: {
66
- readonly envVar: "GEZEL_TABLES_ENABLED";
67
- readonly envValue: "1";
68
- readonly modelFacing: true;
69
- };
70
- readonly describe_table: {
71
- readonly envVar: "GEZEL_TABLES_ENABLED";
72
- readonly envValue: "1";
73
- readonly modelFacing: true;
74
- };
75
- readonly query_table: {
76
- readonly envVar: "GEZEL_TABLES_ENABLED";
77
- readonly envValue: "1";
78
- readonly modelFacing: true;
79
- };
80
- readonly draft_email: {
81
- readonly envVar: "GEZEL_MAIL_ENABLED";
82
- readonly envValue: "1";
83
- readonly modelFacing: true;
84
- };
85
- readonly queue_email: {
86
- readonly envVar: "GEZEL_MAIL_ENABLED";
87
- readonly envValue: "1";
88
- readonly modelFacing: true;
89
- };
90
- readonly send_email: {
91
- readonly envVar: "GEZEL_MAIL_ENABLED";
92
- readonly envValue: "1";
93
- readonly modelFacing: true;
94
- };
95
- readonly draft_post: {
96
- readonly envVar: "GEZEL_SOCIAL_ENABLED";
97
- readonly envValue: "1";
98
- readonly modelFacing: true;
99
- };
100
- readonly queue_post: {
101
- readonly envVar: "GEZEL_SOCIAL_ENABLED";
102
- readonly envValue: "1";
103
- readonly modelFacing: true;
104
- };
105
- readonly publish_post: {
106
- readonly envVar: "GEZEL_SOCIAL_ENABLED";
107
- readonly envValue: "1";
108
- readonly modelFacing: true;
109
- };
110
- readonly draft_connector_action: {
111
- readonly envVar: "GEZEL_CONNECTORS_ENABLED";
112
- readonly envValue: "1";
113
- readonly modelFacing: true;
114
- };
115
- };
116
- type AlwaysRegisteredToolName = (typeof ALWAYS_REGISTERED_TOOLS)[number];
117
- type ConditionallyRegisteredToolName = keyof typeof CONDITIONALLY_REGISTERED_TOOLS;
118
- /**
119
- * Legacy spelling → canonical name for every tool renamed in the
120
- * snake_case standardization. The old names never appear in `tools/list`
121
- * (zero prompt cost) but stay callable forever: pinned gilde role
122
- * templates teach some of them in prose, and lower-capability models
123
- * guess them from training priors. Dispatch-time resolution lives in
124
- * server.ts (stdio callers) and mcp-bridge.ts (bridged providers).
125
- *
126
- * `GEZEL_MCP_TOOL_NAMING=legacy` flips registration back to these
127
- * spellings — an A/B lever for the naming experiment, not a supported
128
- * production mode.
129
- */
130
- declare const RENAMED_TOOLS: {
131
- readonly readdir: "list_dir";
132
- readonly readFile: "read_file";
133
- readonly read_multiple_files: "read_files";
134
- readonly writeFile: "write_file";
135
- readonly appendToFile: "append_to_file";
136
- readonly replaceInFile: "replace_in_file";
137
- readonly replaceLines: "replace_lines";
138
- readonly applyPatch: "apply_patch";
139
- readonly insertAtMarker: "insert_at_marker";
140
- readonly rm: "delete_path";
141
- readonly mkdir: "make_dir";
142
- readonly draftEmail: "draft_email";
143
- readonly queueEmail: "queue_email";
144
- readonly sendEmail: "send_email";
145
- readonly search_files: "grep_files";
146
- readonly run_script: "run_installed_script";
147
- };
148
- type LegacyToolName = keyof typeof RENAMED_TOOLS;
149
- /**
150
- * Removed, foreign-agent, or UI/client spellings that must never be taught as
151
- * model-callable MCP tools. Unlike RENAMED_TOOLS these are not dispatch
152
- * aliases; the registry keeps them only so every model-facing linter shares
153
- * the same tombstones and replacement guidance.
154
- */
155
- declare const TOOL_NAME_TOMBSTONES: {
156
- readonly update_task_step: {
157
- readonly replacement: undefined;
158
- readonly reason: "no such MCP tool";
159
- };
160
- readonly commitProjectGit: {
161
- readonly replacement: undefined;
162
- readonly reason: "UI/client method, not an MCP tool";
163
- };
164
- readonly pushProjectGit: {
165
- readonly replacement: undefined;
166
- readonly reason: "UI/client method, not an MCP tool";
167
- };
168
- readonly listAudioVoices: {
169
- readonly replacement: undefined;
170
- readonly reason: "UI/client method, not an MCP tool";
171
- };
172
- readonly create_project: {
173
- readonly replacement: "start_project";
174
- readonly reason: "removed project-creation tool";
175
- };
176
- readonly inspect_git_workdir: {
177
- readonly replacement: "run_git";
178
- readonly reason: "foreign coding-agent tool";
179
- };
180
- readonly ensureGezel: {
181
- readonly replacement: "ensure_gezel";
182
- readonly reason: "client method, not an MCP tool";
183
- };
184
- readonly pushProjectGithub: {
185
- readonly replacement: undefined;
186
- readonly reason: "client method, not an MCP tool";
187
- };
188
- readonly AskUserQuestion: {
189
- readonly replacement: "ask_user_question";
190
- readonly reason: "foreign coding-agent tool";
191
- };
192
- readonly WebSearch: {
193
- readonly replacement: "web_search";
194
- readonly reason: "foreign coding-agent tool";
195
- };
196
- readonly Grep: {
197
- readonly replacement: "grep_files";
198
- readonly reason: "foreign coding-agent tool";
199
- };
200
- readonly Read: {
201
- readonly replacement: "read_file";
202
- readonly reason: "foreign coding-agent tool";
203
- };
204
- readonly Edit: {
205
- readonly replacement: "replace_in_file";
206
- readonly reason: "foreign coding-agent tool";
207
- };
208
- readonly Agent: {
209
- readonly replacement: "message_gezel";
210
- readonly reason: "foreign coding-agent tool";
211
- };
212
- readonly Bash: {
213
- readonly replacement: undefined;
214
- readonly reason: "foreign shell tool; no unrestricted shell is exposed";
215
- };
216
- readonly ExitPlanMode: {
217
- readonly replacement: undefined;
218
- readonly reason: "foreign coding-agent control tool";
219
- };
220
- };
221
- type ToolNameTombstone = keyof typeof TOOL_NAME_TOMBSTONES;
222
- type CanonicalToolName = AlwaysRegisteredToolName | ConditionallyRegisteredToolName;
223
- interface ToolRegistrationGate {
224
- readonly envVar: string;
225
- /** `*` means any non-empty value enables the registration. */
226
- readonly envValue: string;
227
- }
228
- /**
229
- * Linter- and registration-friendly metadata for one canonical built-in.
230
- *
231
- * `aliases` are hidden callable spellings: they normally do not appear in
232
- * `tools/list`, though the legacy naming experiment may advertise one in
233
- * place of the canonical name. `advertisedByDefault` describes the ordinary
234
- * environment before platform/provider/role filters are applied.
235
- */
236
- interface CanonicalToolRegistryEntry {
237
- readonly canonicalName: CanonicalToolName;
238
- readonly registration: 'always' | 'conditional';
239
- readonly gate?: ToolRegistrationGate;
240
- readonly aliases: readonly LegacyToolName[];
241
- readonly advertisedByDefault: boolean;
242
- readonly modelFacing: boolean;
243
- }
244
- /** Canonical built-in names, with conditional names included exactly once. */
245
- declare const CANONICAL_TOOL_NAMES: readonly CanonicalToolName[];
246
- /** Hidden callable compatibility spellings, never canonical names. */
247
- declare const LEGACY_TOOL_NAMES: readonly LegacyToolName[];
248
- /**
249
- * Single canonical registry for built-in tool-name consumers such as prompt
250
- * linters. It unifies ordinary and contextual registrations with every
251
- * hidden alias, so consumers do not need to recreate joins between the
252
- * compatibility exports above.
253
- */
254
- declare const TOOL_REGISTRY: Readonly<Record<CanonicalToolName, CanonicalToolRegistryEntry>>;
255
- /**
256
- * Every name reserved by a built-in, including hidden aliases. Dynamic
257
- * project script tools must not claim any of these spellings because alias
258
- * dispatch could otherwise route a call to the wrong handler.
259
- */
260
- declare const BUILTIN_TOOL_NAMES: readonly (CanonicalToolName | LegacyToolName)[];
261
- /**
262
- * Every spelling a dynamic tool must not claim. Tombstones are not callable,
263
- * but reserving their namespace prevents a project script from reintroducing
264
- * a removed/foreign name that model-facing prompts are required to reject.
265
- */
266
- declare const RESERVED_TOOL_NAMES: readonly (CanonicalToolName | LegacyToolName | ToolNameTombstone)[];
267
- /** Canonical name → legacy spelling (inverse of {@link RENAMED_TOOLS}). */
268
- declare const LEGACY_SPELLING_BY_CANONICAL: Readonly<Record<string, string>>;
269
- /** Normalized key used by forgiving dispatch and dynamic-name reservation. */
270
- declare function normalizeToolNameSpelling(name: string): string;
271
- /**
272
- * Resolve any spelling of a built-in tool name to its canonical form.
273
- * Unknown names (third-party toolset tools, project script tools) pass
274
- * through unchanged — this maps only the frozen rename table plus
275
- * case/punctuation variants of it, never fuzzy near-misses.
276
- */
277
- declare function canonicalToolName(name: string): string;
278
- /**
279
- * Resolve a requested tool name to whatever spelling is live in
280
- * `knownNames`. Exact hits win; then the frozen rename table in both
281
- * directions (so `writeFile` resolves when `write_file` is live, and
282
- * `write_file` resolves in the legacy A/B arm where `writeFile` is
283
- * live); then a case/punctuation-insensitive match against the live
284
- * names — `WriteFile`, `write-file`, and `read_dir` all land. Never
285
- * fuzzy: names that don't resolve return unchanged so "tool not found"
286
- * errors stay honest. Both the stdio server's dispatch and the
287
- * service's McpBridge route through this, which is what lets every
288
- * name-keyed gate downstream assume a single spelling.
289
- */
290
- declare function resolveToolNameSpelling(requested: string, knownNames: ReadonlySet<string>): string;
1
+ export { ALWAYS_REGISTERED_TOOLS, AlwaysRegisteredToolName, BUILTIN_TOOL_NAMES, CANONICAL_TOOL_NAMES, CONDITIONALLY_REGISTERED_TOOLS, CanonicalToolName, CanonicalToolRegistryEntry, ConditionallyRegisteredToolName, LEGACY_SPELLING_BY_CANONICAL, LEGACY_TOOL_NAMES, RESERVED_TOOL_NAMES, TOOL_NAME_TOMBSTONES, TOOL_REGISTRY, ToolNameTombstone, ToolRegistrationGate, normalizeToolNameSpelling, resolveToolNameSpelling } from '@bendyline/gezel/local-loop';
2
+ export { BranchPrioritizedPulls, LegacyToolName, PullWithHeadRef, RENAMED_TOOLS, canonicalToolName, prioritizePullsForCurrentBranch } from '@bendyline/gezel';
291
3
 
292
4
  /**
293
5
  * Structured file validation for the `validate` MCP tool.
@@ -393,4 +105,4 @@ declare function unavailableToolsForPlatform(platform: NodeJS.Platform, options?
393
105
  networkAllowed?: boolean;
394
106
  }): readonly string[];
395
107
 
396
- export { ALWAYS_REGISTERED_TOOLS, type AlwaysRegisteredToolName, BUILTIN_TOOL_NAMES, CANONICAL_TOOL_NAMES, CONDITIONALLY_REGISTERED_TOOLS, type CanonicalToolName, type CanonicalToolRegistryEntry, type ConditionallyRegisteredToolName, type FileContent, LEGACY_SPELLING_BY_CANONICAL, LEGACY_TOOL_NAMES, type LegacyToolName, RENAMED_TOOLS, RESERVED_TOOL_NAMES, SCRIPT_NETWORK_ALLOWED_ENV, TOOL_NAME_TOMBSTONES, TOOL_REGISTRY, type ToolNameTombstone, type ToolRegistrationGate, type ValidateCheck, type ValidateResult, canUseLinuxSystemdDenyNet, canonicalToolName, formatValidateResult, normalizeToolNameSpelling, resolveToolNameSpelling, unavailableToolsForPlatform, validateFile };
108
+ export { type FileContent, SCRIPT_NETWORK_ALLOWED_ENV, type ValidateCheck, type ValidateResult, canUseLinuxSystemdDenyNet, formatValidateResult, unavailableToolsForPlatform, validateFile };