ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MCP/README
Revision: 1.7
Committed: Thu Oct 22 11:38:56 2026 UTC (3 weeks, 5 days ago) by root
Branch: MAIN
CVS Tags: rel-0_65, rel-0_62
Changes since 1.6: +10 -6 lines
Log Message:
0.62

File Contents

# User Rev Content
1 root 1.2 NAME
2     AnyEvent::MCP::Intro - using MCP servers, clients and permissions
3    
4     DESCRIPTION
5     You can use the servers in this distribution without writing any Perl.
6     This walkthrough starts with one filesystem server, connects it to an
7     MCP client, and makes a useful request. Once that works, it explains
8     persistent configuration, permissions and combining several servers.
9    
10     If you want to write a small server yourself, continue with "TUTORIAL"
11     in AnyEvent::MCP::Server::Simple. Applications needing their own
12     connection management or dispatch can use the modules described in
13     "MODULES" in AnyEvent::MCP.
14    
15     The examples use "/home/alice/src/project" as an existing project
16     directory. Replace it with your own absolute path. Commands shown here
17     are commands for you to run; requests addressed to the LLM are shown
18     separately.
19    
20     INSTALLATION
21     Install the Perl distribution and the external programs used by the
22     servers. Installing one does not install the other.
23    
24     For mcp-fs, install Linux bubblewrap and the filesystem utilities. On
25     Debian or Ubuntu, for example:
26    
27     sudo apt install bubblewrap findutils grep patch sed perl yad
28    
29     "yad" is optional: it supplies graphical permission dialogs. Without a
30     usable YAD dialog, the helper tries "/dev/tty"; if neither is available,
31     it denies the request. Bubblewrap's executable is "bwrap". The machine
32     must allow the unprivileged user namespaces it needs.
33    
34     mcp-fs detects its utilities at startup and omits tools whose utilities
35     are unavailable or unsuitable. It requires bubblewrap by default. See
36     "TRUSTED CONFIGURATION" in mcp-fs for explicit utility paths and
37     "LIMITATIONS" in mcp-fs for the sandbox's limits.
38    
39     If you have an unpacked distribution or source checkout, run these
40     commands in its top-level directory:
41    
42     perl Makefile.PL
43     make
44     make test
45     make install
46    
47     "perl Makefile.PL" reports missing Perl dependencies. Install those with
48     your usual package manager or CPAN client before continuing. For
49     example, the main non-core dependencies can be installed with:
50    
51 root 1.3 cpan AnyEvent AnyEvent::HTTP AnyEvent::WebSocket::Server \
52     AnyEvent::WebSocket::Message common::sense JSON::XS
53 root 1.2
54     Use the same Perl installation for dependency installation, building and
55     running the servers. A module installed for the system Perl might not be
56     available to a Perl installed under "/opt". "make install" needs write
57     access to the selected Perl's installation directories; use an
58     appropriate local Perl installation or run that final step with the
59     required privileges.
60    
61     Installation puts "mcp-fs", "mcp-multibroker", "mcp-vim",
62     "mcp-webbrowser", "mcp-ask-user", "anyevent-mcp" and
63     "anyevent-mcp-askpermission" in the selected executable directory. Make
64     that directory available in the environment of your MCP client, or
65     configure absolute executable paths. A desktop application need not have
66     the same "PATH" as your shell.
67    
68     To try an uninstalled source tree after installing its dependencies, you
69     can run a program with the source library path:
70    
71     perl -Ilib bin/mcp-fs --stdio --name code /home/alice/src/project
72    
73     Do this from the distribution directory. When configuring a client to
74     start such a command, account for the client's working directory or use
75     absolute paths to Perl, "lib" and the script. An installed executable
76     avoids that extra setup.
77    
78 root 1.3 PICK A SERVER
79     For a local MCP client, configure it to launch the server that provides
80     the tools you want:
81 root 1.2
82 root 1.3 mcp-fs --stdio /home/alice/src/project
83     mcp-vim --stdio
84 root 1.2 mcp-webbrowser --stdio
85 root 1.3 mcp-ask-user --stdio
86    
87     "--stdio" means the MCP client launches the process. Do not start a
88     separate copy in a terminal. For HTTP clients, use a running server and
89     its "--print-url" instead, as explained below.
90    
91     "mcp-fs" reads, searches and changes files and runs commands in a
92     sandbox. The first walkthrough below uses this server.
93    
94     "mcp-vim" reads and edits live Vim buffers. Install the companion Vim
95     plugin and connect the editor to its listener; see "Add a live Vim
96     editor" and "VIM PLUGIN INSTALLATION" in mcp-vim.
97    
98     "mcp-webbrowser" works with explicitly approved browser tabs. Install
99     its companion userscript and connect each tab you want to expose; see
100     "CONNECTED BROWSER PAGES".
101 root 1.2
102 root 1.3 "mcp-ask-user" lets the assistant ask you questions through a local YAD
103     or terminal dialog, or through the client's native form UI; see "Ask the
104     client's human a question".
105 root 1.2
106 root 1.4 To offer several servers over one MCP connection, use "mcp-multibroker".
107     It combines these servers with each other or with third-party MCP
108     servers, whether started locally over stdio or reached over HTTP. Their
109     tools appear under separate name prefixes; see "COMBINING SERVERS" and
110     mcp-multibroker for the full command syntax.
111 root 1.2
112     YOUR FIRST FILESYSTEM SERVER
113     Start with one project and one connection. You do not need a
114     multibroker, a hand-written configuration file or saved permission rules
115     yet.
116    
117     Choose stdio or HTTP
118     Use stdio when your MCP client runs on the same machine and can launch a
119     server process. Configure the client to start the following command:
120    
121     mcp-fs --stdio --name code /home/alice/src/project
122    
123     The client starts this process and uses its stdin/stdout for MCP. You do
124     not start a second copy in a terminal, and there is no listener URL or
125     HTTP token to configure. Diagnostics go to stderr.
126    
127     Clients that take a command and an argument array need these values:
128    
129     command: mcp-fs
130     arguments: --stdio, --name, code, /home/alice/src/project
131    
132     These describe separate arguments, not one shell command string. Use an
133     absolute executable path if the client cannot find "mcp-fs". See "CLIENT
134     EXAMPLES" for examples of particular clients.
135    
136     Use HTTP when the client connects to an already-running server, or when
137     it cannot launch a local process. Start this in a terminal on the server
138     machine and leave it running:
139    
140     mcp-fs --name code --bind :31741 /home/alice/src/project
141    
142     In another terminal, obtain the matching connection URL:
143    
144     mcp-fs --name code --bind :31741 --print-url
145    
146     The second command prints a credential-bearing URL and exits without
147     opening a listener. Configure that URL in the client. The default
148     address is IPv4 loopback, so this example is reachable from the same
149     machine only. A hosted client needs a suitable tunnel or reachable
150     endpoint; its own "localhost" is not your computer.
151    
152     Repeat the same name and listener overrides when printing the URL. Both
153     commands must use the same user and configuration directory. Port zero
154     chooses an ephemeral port, which "--print-url" cannot predict; use an
155     explicit port for this walkthrough.
156    
157     The HTTP server generates and saves its private master secret when
158     needed. You can initialize it explicitly with "anyevent-mcp init", but
159     that command is unnecessary when configuration already exists and will
160     refuse to replace it. Keep the printed URL private: possession of its
161     token authenticates a client.
162    
163     Make a useful request
164     Once your client reports that the server is connected, ask the LLM:
165    
166     Show me the configured workdirs. List the top-level files in the
167 root 1.3 project, then read its README if it has one. Do not modify files
168     or run commands.
169 root 1.2
170     "workdirs" returns the configured paths, sandbox grants, trusted mounts
171     and runtime paths. Listing names requests "inspect" permission; reading
172     contents requests "read" permission. Expect a permission prompt when
173     there is no saved rule allowing the operation.
174    
175     Choose "Allow once" for the first operation. The worker then runs with
176     the requested sandbox grants. A denial is a tool failure that the LLM
177     should report, rather than an empty file or a disconnected server.
178    
179     For a slightly larger task, ask:
180    
181     Find TODO comments in this project and explain the three that look
182     most useful to address next. Do not modify files or run commands.
183    
184     This can use "find", "grep" and "read-lines". You need not write MCP
185     requests yourself. If a client offers its own tool-approval prompt, that
186     is an additional client policy; it does not replace mcp-fs's
187     permissions.
188    
189 root 1.3 Give the server a purpose
190     To explain why an instance exists, provide a short purpose:
191    
192     mcp-fs --stdio --name memory \
193     --custom-instructions 'Use this server to retrieve and store persistent memory.' \
194     /home/alice/memory
195    
196     For persistent configuration, use "custom_instructions" in the global
197     configuration's "[program mcp-fs]" or "[instance memory]" section.
198     Instance settings override program settings; the command line overrides
199     both. This purpose appears first in the advertised MCP instructions so a
200     model can decide whether to discover the server's tools.
201    
202     Servers using "AnyEvent::MCP::Server::Simple" also expose the instance
203     purpose and complete operating instructions as a "meta-instructions"
204     tool description. Calling that tool returns the complete text when a
205     client truncates descriptions. Clients that understand MCP server
206     instructions still receive a short purpose or routing hint at discovery
207     time, followed by an automatic pointer to the full instructions in the
208     tool description.
209    
210 root 1.2 Understand the workdir
211     The directory passed at startup tells mcp-fs which workdir to expose. It
212     does not grant permission for every operation in that directory. Each
213     operation still requests its action and sandbox grants.
214    
215     With one workdir, tools can omit the "workdir" argument. With several:
216    
217     mcp-fs --stdio --name code /home/alice/src/project /home/alice/notes
218    
219     tools select one using a persistent positive integer ID, a numeric
220     string or an exact configured/resolved path returned by "workdirs". The
221     "workdirs" and "resolved_workdirs" objects use these IDs as keys.
222     Relative tool paths are relative to that selection. Permission rules
223     continue to use the configured path, not its numeric ID.
224    
225     IDs are shared across filesystem servers in
226     "$XDG_CONFIG_HOME/anyevent-mcp/fs-workdir-ids.json", or under
227     "$HOME/.config" by default. They identify resolved absolute paths and
228     survive restarts and argument reordering. Startup resolves IDs once and
229     reserves new allocations under the lock. A timer runs immediately and
230     every 5.25 days to reread the registry and refresh the server's fixed
231     assignments. Other entries expire after seven days and their IDs may be
232     reused. Restart servers after manually changing the registry.
233    
234     "workdir-read" exposes the selected workdir read-only. "workdir-write"
235     makes it writable and implies read access. A path in another configured
236     workdir requires all-workdirs authority; a path elsewhere requires
237     suitable home/world or shared-tmp authority. A symlink cannot make an
238     unmounted target appear inside the sandbox.
239    
240     Prefer separate, non-overlapping workdirs. Overlapping mounts have
241     unspecified access effects. See "SANDBOX GRANTS" in mcp-fs before
242     granting access beyond the selected workdir.
243    
244     Inspect version-control changes
245     For a Git, SVN, CVS or Mercurial working copy, ask the LLM to use
246     "vcs-diff" and "vcs-status", with "backend" set to "git", "svn", "cvs"
247     or "hg". "workdirs" reports the available clients. These tools accept
248     filenames and construct the command themselves; no shell pipeline or
249     arbitrary VCS options need to be approved.
250    
251     For example:
252    
253     Show the CVS diff for this project, limited to 200 lines.
254     Then show its status, keeping stdout lines matching "File:|Status:".
255    
256     These operations have their own permission actions. They request read
257 root 1.3 access to the selected workdir. CVS additionally requests the
258     "ssh-agent" grant, which includes network access, the agent socket and
259     "known_hosts", but not general home-directory access. Read permission
260     for ordinary file tools does not automatically authorize a VCS
261     operation.
262 root 1.2
263     For arbitrary "exec" commands, the same output options are available:
264     "grep" filters stdout using PCRE, "max_lines" limits matching stdout
265     lines, and "max_bytes" bounds returned bytes per stream. Prefer these
266     options to a shell wrapper that mixes execution and output processing.
267     Stderr is unfiltered, and exit status still describes the original
268     command.
269    
270     Defaults return at most 2000 stdout lines and 64 KiB per stream. Raw
271     capture has a separate 1 MiB limit per stream. A true
272     "capture_truncated" means output was omitted before filtering or
273     collection ended on timeout, so absent matches do not prove the omitted
274     output had none. See "Command output" in mcp-fs for all result flags and
275     limits.
276    
277     CONFIGURING YOUR SETUP
278     There are three different things to configure: how the client connects,
279     how the server runs, and which operations the user allows. Changing one
280     does not necessarily change the other two.
281    
282     Where each setting belongs
283     Directories to expose
284     Pass workdirs on the mcp-fs startup command. For a stdio server,
285     that command belongs in the client's server configuration. For an
286     HTTP server, it belongs in the command used to run the service.
287    
288     Connection transport
289     The client launches a command for stdio or connects to a URL for
290     HTTP. "--stdio" selects the former for mcp-fs and the multibroker.
291    
292     Listener address, port and tokens
293     Use "[instance NAME]" in the global configuration or command-line
294     "--bind" and "--token" overrides.
295    
296     Trusted mounts and utility paths
297     For mcp-fs, use "[program NAME]" defaults and "[instance NAME]"
298     overrides in the global configuration.
299    
300     Allowed operations and sandbox grants
301     Use the permission rules file, normally created through approval
302     dialogs. This file is separate from the global configuration.
303    
304     Location of permission prompts
305     Use "--ask helper", "--ask tty", "--ask yad", "--ask auto" or "--ask
306     mcp", or set "PERL_ANYEVENT_MCP_PERMISSION_ASK" in the server's
307     environment.
308    
309     Combined server connections
310     Put prefix/server pairs on the multibroker startup command. HTTP
311     child credentials can also use "[client PREFIX]" in the global
312     configuration.
313    
314     One complete named configuration
315     The global file is "$XDG_CONFIG_HOME/anyevent-mcp/global.ini", falling
316     back to "$HOME/.config/anyevent-mcp/global.ini". Settings are UTF-8 "key
317     = value" lines; values are unquoted. Whole-line "#" and ";" comments are
318     allowed. See "GLOBAL CONFIGURATION" in AnyEvent::MCP for the complete
319     format.
320    
321     Start with the existing file, preserving its "[global]" secret. If you
322 root 1.3 have no file yet, "anyevent-mcp init" creates it privately. Add this
323     section:
324 root 1.2
325     [instance code]
326     bind = 127.0.0.1:31741
327    
328     Now start:
329    
330     mcp-fs --name code /home/alice/src/project
331    
332     and retrieve its URL with:
333    
334     mcp-fs --name code --print-url
335    
336     Both use "[instance code]". No explicit token is needed: the server
337     derives one from its name and the existing master secret.
338    
339     For this setup:
340    
341     instance settings: [instance code]
342     selected workdir: /home/alice/src/project
343     permission file: ~/.config/anyevent-mcp/rules/fs-code.ini
344     rule-manager profile: fs-code
345    
346     The permission pathname above assumes the default configuration
347     directory. "anyevent-mcp manage-rules fs-code" opens the graphical rule
348     manager; "anyevent-mcp edit-rules fs-code" opens the file in your
349     editor.
350    
351 root 1.3 Settings shared by all mcp-fs instances go in "[program mcp-fs]".
352     Instance settings override program settings.
353    
354 root 1.6 File ownership and permissions are under the user's control. The global
355     configuration contains a master authentication secret, so take care when
356     sharing it. "--config FILE" on "anyevent-mcp init" selects that
357     command's output file; it does not make the servers use an arbitrary
358     alternate file. Use the same "HOME"/"XDG_CONFIG_HOME" environment when
359     running the server and its management commands.
360 root 1.2
361     Names, prefixes and profiles
362     "--name code" selects instance settings, derived HTTP credentials and
363     mcp-fs's "rules/fs-code.ini". Without "--name", mcp-fs uses "default",
364     giving profile "fs-default". Two processes with the same program, name
365     and configuration share credentials and rules, even if their workdirs
366     differ.
367    
368     A multibroker prefix, such as "files", only routes tools: "grep" becomes
369     "files.grep". It does not rename the child server or select its rules.
370     For example:
371    
372     mcp-multibroker files \
373     'stdio:mcp-fs --name code /home/alice/src/project'
374    
375     The tools are "files.*", but the child still uses instance "code" and
376     rule-manager profile "fs-code". The multibroker's own "--name" selects
377     its upstream listener settings.
378    
379     Configuration changes and restarts
380     Command-line listener options override the named global settings. For
381     mcp-fs trusted settings, an instance entry overrides the corresponding
382     program entry; an empty instance mount value suppresses the inherited
383     mount.
384    
385     Workdirs, mounts, utility paths, listener settings and tokens are read
386     at startup. Change the file or startup command, then restart the
387     affected server. The multibroker also needs restarting to change its
388     prefix/server pairs; refreshing discovery does not change those pairs.
389    
390     Permission rules are reread on permission checks, so editing them does
391     not require a restart. A client's displayed tool list can still be
392     cached. After restarting a child, refresh tool discovery or reconnect
393     the client as described in "COMBINING SERVERS".
394    
395     PERMISSIONS IN PRACTICE
396     HTTP authentication establishes that the client may connect. Permission
397     checks decide whether a tool may perform an operation. A correct token
398     therefore does not prevent permission prompts.
399    
400     What the prompt means
401     The prompt describes an action, paths or command, a reason and sandbox
402     grants. For filesystem tools, the actions are:
403    
404     inspect stat, list, find
405     read file-read, read-lines, grep
406     write file-write, file-patch
407     manage path-op
408     exec arbitrary command execution
409     vcs-diff working-copy differences
410     vcs-status working-copy status
411    
412     The action and grants are independent. Allowing "read" does not allow
413     "write", even if a worker grant permits both kinds of filesystem access.
414     "exec" runs arbitrary commands; it is not a classification of supposedly
415     safe command prefixes.
416    
417     Choose allow/deny once, or always. Closing the dialog denies once. An
418     optional denial reason is returned with the error; it is not added to
419     successful tool results. An always choice opens a rule editor. Choose an
420     indefinite lifetime (the default), 900 seconds or 16 hours. Finite
421     lifetimes are stored as "expires" Unix timestamps. Expired rules
422     disappear on every read; the next ordinary save removes them from disk.
423     Expiry affects future permission checks, not operations already
424     authorized. Filesystem allow rules can select grants and the selected
425     workdir when the authority depends on it. Deny rules can also select an
426     exact affected path. Exec offers persistent command/argv subjects.
427    
428     For exec, "View stdin..." lets you inspect supplied input without
429     closing the approval dialog. Filesystem and Vim patch tools similarly
430     offer "View patch...", including the target file or editor and buffer.
431     Longer text is shown as an explicitly incomplete preview. These are YAD
432     button labels; other interfaces can show the details inline. That input
433     is display-only: an exec allow rule does not constrain future stdin.
434     Allowing an interpreter command can therefore allow a different script
435     on its next invocation.
436    
437     A worker accessing several paths requests their combined sandbox
438     authority once. If the chosen grants are insufficient, it fails before
439     starting.
440    
441     Save a useful read-only policy
442     After trying individual operations, you might want the LLM to inspect
443     and read the project without asking each time, while keeping changes
444     subject to approval. Put these rules in "rules/fs-code.ini", or create
445     equivalent allow rules through the prompt:
446    
447     [rule]
448     decision=allow
449     action=inspect
450     workdir=/home/alice/src/project
451     sandbox-grants=workdir-read
452    
453     [rule]
454     decision=allow
455     action=read
456     workdir=/home/alice/src/project
457     sandbox-grants=workdir-read
458    
459     [rule]
460     decision=deny
461     action=exec
462    
463     Use the exact workdir spelling passed at server startup. Absolute
464 root 1.6 startup paths make this easier. Rule-file permissions follow the usual
465     Unix filesystem rules; any user who can edit the file can change the
466     server's approval policy.
467    
468     Without matching rules, write and manage operations still ask. The final
469     rule denies command execution outright; omit it if you want execution to
470     ask instead.
471 root 1.2
472     Rules run in order, stopping at the first match. An allow rule matches
473     only when its grants cover the request, including implications.
474     "workdir-write" implies "workdir-read"; "network" remains independent.
475     Action and subject match exactly unless beginning with "^", which
476     selects a Perl regular expression. Workdir matching is always exact. An
477     explicit "ask" rule can override later allow rules.
478    
479     These allow rules authorize sandbox access to the selected workdir. They
480     cannot confine authority to one file or a subtree inside it. Filesystem
481     operations do not offer persistent path subjects. An exact "path"
482     matcher is available for deny rules only. Trusted runtime and configured
483     mounts remain baseline access independently of these grants. See
484     "TRUSTED CONFIGURATION" in mcp-fs.
485    
486     Change or remove saved rules
487     Use:
488    
489     anyevent-mcp manage-rules fs-code
490     anyevent-mcp edit-rules fs-code
491    
492     The first command lets you delete and reorder rules in YAD. The second
493     uses $VISUAL, $EDITOR, "sensible-editor" or "vi". An earlier deny or ask
494     rule can explain why adding a later allow rule does not change the
495     result.
496    
497     For a custom application with another rule pathname, use:
498    
499     anyevent-mcp manage-rules-file /path/to/rules.ini
500     anyevent-mcp edit-rules-file /path/to/rules.ini
501    
502     A failed attempt to save a permanent rule is an error, not a successful
503 root 1.6 permanent approval. The file mode is preserved when saved through these
504     commands. For full syntax and programming interfaces, see
505 root 1.2 AnyEvent::MCP::Server::Permissions.
506    
507     Choose where to ask
508     The default "helper" mode runs "anyevent-mcp-askpermission" on the
509     server machine. It tries YAD, then "/dev/tty", then denies if neither
510     can be used. The helper inherits the server's display environment.
511     "--ask tty" and "--ask yad" instead force the built-in terminal or YAD
512     interface. They ignore custom helper settings and never try another
513     interface. These modes work for permission prompts and ordinary forms,
514     including forms handled by a multibroker.
515     "PERL_ANYEVENT_MCP_PERMISSION_HELPER" selects a different executable.
516    
517     For a modern client supporting MCP form elicitation, you can instead
518     use:
519    
520     mcp-fs --stdio --name code --ask auto /home/alice/src/project
521    
522     "auto" uses the client's form support when advertised for that request,
523     otherwise the local helper. "mcp" requires that support and fails when
524     unavailable. It does not silently fall back. Use client-side permission
525     approval only when that client is a trusted authority to grant access.
526    
527     To set the default for servers using the shared permission engine:
528    
529     PERL_ANYEVENT_MCP_PERMISSION_ASK=auto \
530     mcp-fs --stdio --name code /home/alice/src/project
531    
532     An explicit application "ask" setting or "--ask" overrides the
533     environment. For spawned stdio children, "mcp-multibroker --ask auto"
534     passes this default to them. It cannot change the environment of an
535     independently running HTTP server.
536    
537     The multibroker can handle form elicitation locally for both stdio and
538     HTTP children. "--ask helper" selects local dialogs even if the upstream
539     client advertises native forms; "--ask mcp" forwards forms upstream, and
540     "auto" uses native forms when advertised. If a client claims support but
541     silently declines questions, use "helper". A decline never causes a
542     fallback prompt.
543    
544     Standalone "mcp-ask-user" also supports these modes and defaults to the
545     local helper. A question is different from an approval: answering it
546     does not grant a filesystem worker any authority.
547    
548     COMBINING SERVERS
549 root 1.4 Once the first connection works, "mcp-multibroker" lets you give the
550     client one connection for several MCP servers. It works with the servers
551     in this distribution and with third-party MCP servers, including ones
552     written in other languages. Each downstream server can be a local
553     subprocess communicating over stdio or an existing HTTP endpoint; you
554     can mix both in one broker. The broker discovers their tools and
555     forwards calls to the appropriate server without changing how that
556     server implements its tools.
557    
558     For example, combine two filesystem instances:
559 root 1.2
560     mcp-multibroker --name tools --bind :31740 \
561     code 'stdio:mcp-fs --name code /home/alice/src/project' \
562     notes 'stdio:mcp-fs --name notes /home/alice/notes'
563    
564     Quote each "stdio:" shell command as one argument. The broker supplies
565     the child's stdio environment and starts ordinary children lazily, on
566     first use. The explicit child names give them separate permission
567     profiles "fs-code" and "fs-notes".
568    
569     Obtain the upstream HTTP URL with:
570    
571     mcp-multibroker --name tools --bind :31740 --print-url
572    
573     Configure this URL in place of the client's old direct connection. The
574     client can now see "code.grep", "code.read-lines", "notes.find" and
575     other prefixed tools. It does not need a separate connection to each
576     child.
577    
578     For a client launching the multibroker locally, configure:
579    
580     mcp-multibroker --stdio --name tools \
581     code 'stdio:mcp-fs --name code /home/alice/src/project' \
582     notes 'stdio:mcp-fs --name notes /home/alice/notes'
583    
584     "--stdio" selects the upstream connection. The child commands still use
585     "stdio:"; that selects each downstream connection independently. No
586     upstream HTTP URL is needed in this case.
587    
588 root 1.4 The same setup can include Vim, browser pages, a third-party stdio
589     server or a remote HTTP service. See "Add an HTTP child" for an example
590     mixing local and remote servers, and "DOWNSTREAM SERVERS" in
591     mcp-multibroker for the complete syntax, including direct argv
592     execution, credentials and per-child options.
593    
594 root 1.2 Discover and refresh tools
595     Ask the LLM:
596    
597     Call discover-brokers and list-tools, then show me which servers
598     are available and what each is for.
599    
600 root 1.3 "discover-brokers" returns advertised instructions (which may be short),
601     no instructions, or an error for each configured server. "list-tools"
602     requests current tool definitions, including any prefixed
603     "meta-instructions" tools and their full instruction descriptions;
604     unreachable servers are omitted. A reachable server can still fail
605     later.
606 root 1.2
607     If the client still has an old direct tool list, "call-tool" can invoke
608     an exact prefixed name found by "list-tools". Refresh the client's MCP
609     connection if it continues to hide newly available tools.
610    
611     Discovery queries configured servers and currently registered reverse
612     connections. Changing the static downstream command still requires a
613     restart.
614    
615     Let a server connect to the multibroker
616     To add independently started servers without editing the multibroker
617     command, keep its HTTP/extension listener active alongside stdio:
618    
619     mcp-multibroker --stdio --listen --bind 127.0.0.1:31740
620     mcp-multibroker --bind 127.0.0.1:31740 --print-url
621    
622     Append an alias to the returned credential-bearing URL:
623    
624     mcp-fs --connect http://127.0.0.1:31740/TOKEN/files /home/alice/project
625    
626     The filesystem server initiates the TCP connection but remains the MCP
627     server. The multibroker authenticates the same token used for HTTP,
628     registers the alias and discovers the tools. A configured or connected
629     alias cannot be replaced. After disconnecting, the server retries once
630     per second for sixty attempts. Pending calls fail and are never
631     replayed. Remote registration does not grant the multibroker
632     spawned-child shutdown authority.
633    
634     The hello is a raw JSON line, followed by ordinary MCP JSONL on the same
635     socket; the HTTP-shaped URL is an address and credential, not an HTTP
636     request. The bundled connector supports plain "http://" endpoints. An
637     HTTP listener is already active by default when the upstream connection
638     is HTTP.
639    
640     Add an HTTP child
641 root 1.4 A broker can mix spawned stdio servers and existing HTTP endpoints,
642     including independently implemented third-party servers:
643 root 1.2
644     mcp-multibroker --stdio \
645     code 'stdio:mcp-fs --name code /home/alice/src/project' \
646     remote https://example.org/mcp/ --bearer TOKEN
647    
648     "--bearer" immediately after the HTTP pair belongs to that child.
649     "--token" before all pairs configures the multibroker's own HTTP
650     listener. They authenticate different connections.
651    
652     To avoid putting a child's bearer token in the startup command, add:
653    
654     [client remote]
655     bearer = TOKEN
656     timeout = 300
657    
658     to the private global configuration, and omit "--bearer" from the
659     command. The prefix "remote" selects these client defaults. The
660     command-line URL still chooses the endpoint. Use the actual credential
661     accepted by that server, not the literal placeholder "TOKEN".
662    
663     A token already present in a child's URL needs no separate bearer
664     option. The bundled servers use static URL-safe tokens; they do not
665     validate OAuth access tokens or implement HTTP Basic authentication. Use
666     TLS or an appropriate tunnel when credentials cross untrusted networks.
667    
668     The multibroker does not put every child inside the mcp-fs sandbox. Each
669     process or remote service has its own authority and enforcement.
670    
671     Add a live Vim editor
672     Install the Vim plugin using "VIM PLUGIN INSTALLATION" in mcp-vim. It is
673     included in the source distribution but is not installed by Perl's "make
674     install".
675    
676 root 1.3 Without a multibroker, configure the MCP client to launch:
677    
678     mcp-vim --stdio --name editor
679    
680     Even in stdio mode, mcp-vim listens separately for editor connections.
681     If using a multibroker, start its child eagerly so Vim can connect
682     before the first MCP tool call:
683 root 1.2
684     mcp-multibroker --stdio \
685     code 'stdio:mcp-fs --name code /home/alice/src/project' \
686     vim 'stdio:mcp-vim --name editor' --eager
687    
688 root 1.3 In another terminal, obtain the editor broker's URL prefix:
689 root 1.2
690     mcp-vim --name editor --print-url
691    
692     Append the desired target name in Vim:
693    
694     :Mcp http://HOST:PORT/TOKEN/my-editor
695    
696     Use the actual printed prefix in place of "http://HOST:PORT/TOKEN/". Ask
697 root 1.3 the LLM to call "targets", then "state" before reading or editing
698     buffers ("vim.targets" and "vim.state" through the multibroker). These
699     tools see live, possibly unsaved buffers. Edits require a current
700     changedtick and do not save files to disk.
701 root 1.2
702     To pass arguments directly, use "PREFIX --- PROGRAM ARG... ---":
703    
704     mcp-multibroker --stdio \
705     vim --- mcp-vim --name editor --bind :: --- --eager \
706     code --- mcp-fs --name code '/home/alice/project with spaces' ---
707    
708     Only the invoking shell processes quoting. The broker passes all
709     arguments between the delimiters unchanged, including empty arguments
710     and child options. Use "stdio:COMMAND" for shell syntax or a literal
711     "---" child argument. An empty command or missing closing delimiter is
712     an error.
713    
714     "--eager" belongs immediately after its stdio URL or closing "---". An
715     eager connection failure is logged; the broker does not continuously
716     restart the child. Later tool use can try connecting again.
717    
718     Ask the client's human a question
719 root 1.3 To let the assistant ask you questions, configure its MCP client to
720     launch:
721    
722     mcp-ask-user --stdio
723    
724     Or add the question server to a multibroker:
725 root 1.2
726     mcp-multibroker --stdio \
727     code 'stdio:mcp-fs --name code /home/alice/src/project' \
728     questions 'stdio:mcp-ask-user'
729    
730 root 1.3 The LLM can call "ask-user" ("questions.ask-user" through the
731     multibroker) with a question, up to three suggested answers and room for
732     free text. For example, tell it to use that tool if choosing among
733     several possible tasks needs your input. For several fields or other
734     value types, "ask-form" ("questions.ask-form" through the multibroker)
735     accepts "message" and "requestedSchema" directly and returns the
736     standard elicitation response. Both tools use the same configured
737     presentation mode. Decline and cancel are distinct results; neither
738     supplies an answer.
739 root 1.2
740     By default the multibroker displays questions locally, using YAD or a
741     terminal. Add "--ask mcp" before the broker entries to use the client's
742     native forms, or "--ask auto" to select by advertised capability. This
743     also works with "mcp-ask-user" started separately: give that server
744     "--ask mcp" so it delegates presentation to its connecting multibroker.
745    
746     "anyevent-mcp-form-elicitation" is the standalone form renderer. It
747     reads standard MCP form parameters as UTF-8 JSON on stdin and writes an
748     accept/decline/cancel response as JSON on stdout.
749     "PERL_ANYEVENT_MCP_ELICITATION_HELPER" selects a replacement executable.
750     See anyevent-mcp-form-elicitation for supported fields and mcp-ask-user
751     for question arguments and result fields.
752    
753 root 1.3 CONNECTED BROWSER PAGES
754     "mcp-webbrowser" is the browser-page counterpart to "mcp-vim". It
755     exposes only tabs explicitly allowed by the browser user. Configure your
756     MCP client to launch:
757    
758     mcp-webbrowser --stdio
759    
760     The broker keeps its own HTTP/WebSocket listener active even in stdio
761     mode; the userscript connects to that listener, not to MCP's stdio
762     stream. In a separate terminal, obtain its URL:
763    
764     mcp-webbrowser --print-url
765    
766     Use the same instance name and configuration as the broker. Keep this
767     credential-bearing URL private. Install the companion userscript from
768     "webbrowser/mcp-webbrowser.user.js" in the source distribution or from
769     <https://dist.schmorp.de/mcp-webbrowser/1/mcp-webbrowser.user.js>.
770     Chromium with ScriptCat has been tested. On a tab you want to expose,
771     choose Allow MCP access to this tab from the userscript menu and enter
772     the printed URL when prompted. Other tabs remain unexposed.
773    
774 root 1.5 The broker supplies "tabs", "execute" and "add-element" tools,
775 root 1.3 permission prompts, cancellation and execution timeouts. See "USERSCRIPT
776     INSTALLATION AND USE" in mcp-webbrowser for setup, compatibility and the
777     current ScriptCat discarded-tab limitation.
778    
779     If the multibroker launches the browser broker, keep that child running
780     from startup so browser tabs can connect:
781    
782     mcp-multibroker --stdio browser --- mcp-webbrowser --- --eager
783    
784 root 1.2 HTTP TOKENS AND SERVER IDENTITY
785     For the ordinary bundled HTTP endpoints, a client can present an
786     accepted token in either of these ways:
787    
788     POST /TOKEN/
789     POST / Authorization: Bearer TOKEN
790    
791     URL tokens are path components, not browser cookies. For another
792 root 1.7 configured endpoint, "/TOKEN" prefixes that endpoint path. The HTTP
793     server also accepts "/TOKEN" and the corresponding bare path without the
794     final slash when the endpoint is configured with one. This works around
795     clients (observed with Claude) that drop the final slash from a
796     configured URL. All accepted tokens authenticate the same operations;
797     they are not separate users or permission levels. Permissions still
798     govern the tool operation.
799 root 1.2
800     By default, the master secret and server name determine one stable token
801     and a port in 16384..32767. Changing a server's name changes its derived
802     credentials and default port. Changing or losing the master secret
803     changes all derived credentials. Keep an existing "[global]" secret when
804     editing other configuration.
805    
806     To configure explicit tokens:
807    
808     [instance code]
809     tokens = first-secret,second-secret
810    
811     Replace those placeholders with actual unguessable URL-safe tokens.
812     Repeated "--token" options replace the whole configured list and the
813     derived default. The first token appears in "--print-url"; all are
814     accepted. mcp-vim also accepts its token set for Vim and browser
815     WebSocket connections.
816    
817     If "--print-url" disagrees with the client's URL, compare the name,
818     command-line overrides, user and configuration environment with the
819     running process. The command resolves configuration; it does not ask the
820     running server which URL it uses. A changed file needs a server restart.
821    
822     An Origin allowlist restricts browser origins; it does not authenticate
823     clients. A CORS preflight can succeed without a token, while the MCP
824     POST still requires one. See "AUTHENTICATION" in
825     AnyEvent::MCP::Server::HTTP for the low-level server interface.
826    
827     CLIENT EXAMPLES
828     Client settings and command syntax evolve independently of this
829     distribution. These examples show the connection choices; consult the
830     linked client documentation if its interface differs. Replace
831     illustrative paths and credentials with your own.
832    
833     OpenAI Codex CLI
834     For the first direct filesystem connection:
835    
836     codex mcp add code -- \
837     mcp-fs --stdio --name code /home/alice/src/project
838     codex mcp list
839    
840     For a multibroker connection:
841    
842     codex mcp add mytools -- \
843     mcp-multibroker --stdio \
844     code 'stdio:mcp-fs --name code /home/alice/src/project'
845    
846     Use "/mcp" within Codex to inspect connections. See Codex MCP
847     documentation <https://learn.chatgpt.com/docs/extend/mcp>.
848    
849     Anthropic Claude Code
850     For the direct connection:
851    
852     claude mcp add --transport stdio --scope user code -- \
853     mcp-fs --stdio --name code /home/alice/src/project
854     claude mcp list
855    
856     Replace the launched command with the multibroker command above when you
857     want several servers. Use "/mcp" for connection status. See Claude Code
858     MCP documentation <https://code.claude.com/docs/en/mcp>.
859    
860     Google Gemini CLI
861     Merge a direct server entry into "~/.gemini/settings.json":
862    
863     {
864     "mcpServers": {
865     "code": {
866     "command": "mcp-fs",
867     "args": [
868     "--stdio", "--name", "code", "/home/alice/src/project"
869     ]
870     }
871     }
872     }
873    
874     For a combined connection, use "mcp-multibroker" as the command and its
875     "--stdio" and prefix/server pairs as the argument array. Use "/mcp" to
876     inspect the connection. See Gemini CLI MCP documentation
877     <https://geminicli.com/docs/tools/mcp-server/>.
878    
879     Hosted clients, including ChatGPT web
880     A hosted client cannot spawn your local stdio command or reach your
881 root 1.5 machine's loopback address directly. A Secure MCP Tunnel runs locally,
882     connects out to OpenAI, and forwards MCP requests to a local stdio
883     command or HTTP URL. No public listener or inbound firewall port is
884     needed.
885    
886     First create a tunnel in OpenAI Platform tunnel settings and obtain its
887     "tunnel_..." ID and a runtime API key. Arrange for
888     "CONTROL_PLANE_API_KEY" to be set securely in the tunnel client's
889     environment; do not put a real key in a script, command line or example.
890     Associate the tunnel with the ChatGPT workspace where you want to use
891     it.
892    
893     For stdio, put the server startup command in a small executable wrapper,
894     for example "/home/alice/bin/my-mcp":
895    
896     #!/bin/sh
897     exec mcp-multibroker --stdio \
898     code --- mcp-fs --name code /home/alice/src/project --- \
899     questions --- mcp-ask-user ---
900    
901     With a tunnel installation providing "tunnel-client-runtime", run:
902    
903     tunnel-client-runtime run \
904     --log.format=struct-text \
905     --log.level=warn \
906     --control-plane.tunnel-id=tunnel_... \
907     --mcp.connection-max-ttl=120s \
908     --mcp.command=/home/alice/bin/my-mcp
909    
910     The tunnel starts the wrapper as its stdio MCP server. Do not start a
911     separate copy yourself. Make the wrapper executable and ensure its
912     programs and Perl modules are on the tunnel process's "PATH".
913 root 1.2
914 root 1.5 For HTTP, instead start the server or multibroker separately:
915    
916     mcp-multibroker --name tools --bind 127.0.0.1:16586 \
917     code 'stdio:mcp-fs --name code /home/alice/src/project'
918    
919     Obtain the matching credential-bearing URL:
920    
921     mcp-multibroker --name tools --bind 127.0.0.1:16586 --print-url
922    
923     Then point the tunnel runtime at that URL, rather than a command:
924    
925     tunnel-client-runtime run \
926     --log.format=struct-text \
927     --log.level=warn \
928     --control-plane.tunnel-id=tunnel_... \
929     --mcp.connection-max-ttl=120s \
930     --mcp.server-url=http://127.0.0.1:16586/TOKEN/
931    
932     Replace "TOKEN" with the actual URL path printed above, and keep it
933     private. In this mode, the multibroker must remain running separately;
934     the tunnel only connects to it. Both modes require the tunnel runtime to
935     remain active while the hosted client uses the server. Use one of
936     "--mcp.command" and "--mcp.server-url", not both.
937    
938     In ChatGPT, add a custom MCP server using a Tunnel connection and select
939     the tunnel ID. Creation and visibility depend on the Platform and
940     ChatGPT workspace permissions. The tunnel client's CLI and supported
941     configuration forms can vary between releases; the examples above use
942     the direct runtime CLI rather than its optional profile setup. See
943 root 1.2 Secure MCP Tunnel
944 root 1.5 <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels> for
945     obtaining a tunnel, runtime, credentials and connecting it to ChatGPT.
946 root 1.2
947     TROUBLESHOOTING
948     The server does not start
949     Read stderr or the client's server log. Missing Perl modules, a missing
950     workdir, unsuitable utilities or an unavailable bubblewrap executable
951     can fail startup. Confirm that the client launches the same executable
952     and arguments you intended, with the expected "PATH" and Perl
953     installation.
954    
955     For a local sandbox check, run from the project directory:
956    
957     mcp-fs --exec-cmd workdir-read -- ls
958    
959     This runs "ls" with the named grants and trusted baseline mounts,
960     without MCP or saved permission rules. A failure here can identify a
961     bubblewrap or runtime problem. It does not test the client connection or
962     approval UI. "--sandbox none" disables isolation and changes worker
963     authority; it is not a fix that preserves the same permission boundary.
964    
965     The client cannot connect
966     For stdio, configure a command the client launches, rather than a URL. A
967     separately running stdio process is not the client's connection. Do not
968     put banners or diagnostics on stdout.
969    
970     For HTTP, leave the server running and check its address and port.
971     "--print-url" exits without starting it. Loopback binds accept local
972     connections only; hosted or remote clients need the appropriate route or
973     tunnel. An occupied port causes a listener error, so check the server
974     log.
975    
976     Authentication fails
977     Obtain the URL with the same name, bind/token overrides and
978 root 1.7 configuration environment as the running process. Use the complete path;
979     the final slash is optional for endpoints whose configured path ends in
980     one. A clean URL needs an accepted bearer token.
981 root 1.2
982     A multibroker child credential is not necessarily the upstream
983     listener's credential. "--bearer" after a child pair and "--token"
984     before the pairs configure different sides of the connection.
985    
986     If the server warns that it cannot save the master secret, another
987 root 1.6 process may derive a different token. Check write access to the global
988     configuration. Do not replace an existing secret simply to add a
989     setting.
990 root 1.2
991     Connected, but there are no tools
992     Inspect the server's stderr for omitted utilities. mcp-fs's "workdirs"
993     tool reports configuration even when a utility-dependent tool is absent.
994     For a multibroker, call "discover-brokers" to see individual connection
995     errors, then "list-tools" to refresh definitions.
996    
997     A third-party child might require initialization or features this client
998     implementation does not support. See AnyEvent::MCP::Client and its
999     transport documentation for limitations.
1000    
1001     There is no approval dialog
1002     First check whether the tool was denied by a saved rule or is waiting
1003     for the client's own approval. An allowed operation needs no server
1004     prompt.
1005    
1006     The default helper runs on the server machine. A background service may
1007     have neither a usable display nor "/dev/tty", even though your
1008     interactive shell has both. Supply the appropriate display environment,
1009     a usable helper, or "--ask auto" with a modern client supporting form
1010     elicitation. "--ask mcp" reports an error if that support is absent.
1011    
1012     Setting an asking mode cannot make an unsupported client display a form.
1013     Check stderr and the tool error instead of assuming a missing dialog is
1014     an approval.
1015    
1016     It asks again after I chose allow
1017     Allow-once covers one tool invocation, including its permission retries.
1018     The next invocation asks again. Use allow-always to save a rule.
1019    
1020     Inspect the saved rule's action, workdir and grants. Listing names and
1021     reading contents are different actions. A rule for one exact workdir
1022     spelling will not match a differently spelled startup argument. A
1023     request for extra authority, such as networking, does not match a
1024     workdir-read-only allow rule. Earlier ask or deny rules take precedence.
1025    
1026     Confirm that the prompt's permanent rule was successfully saved and that
1027     you are editing the rules for the actual child name, not merely its
1028     multibroker prefix.
1029    
1030     The worker cannot see a directory or executable
1031     The worker sees granted mounts and trusted baseline mounts, not
1032     everything the server process can see. Check "workdirs" for the selected
1033     path, mounts and runtime paths. A symlink target outside those mounts is
1034     unavailable.
1035    
1036 root 1.3 The ordinary sandbox runtime includes "/usr", "/bin" and system
1037     libraries, but not "/opt". For tools or libraries under "/opt", add this
1038     to "[program mcp-fs]" in the private global configuration:
1039    
1040     mount.opt = ro:/opt
1041    
1042     This assumes "/opt" exists. Restart mcp-fs after changing trusted
1043     mounts. If your worker Perl is "/opt/bin/perl", you can also set
1044     "executable.perl = /opt/bin/perl" in that program section. Supply the
1045     actual executable path: selecting it does not itself mount the
1046     executable or its dependencies inside the worker.
1047    
1048     A trusted mount supplies baseline access to every worker using it; a
1049 root 1.2 writable mount likewise supplies baseline write authority.
1050    
1051     An arbitrary command might also need its user's configuration or
1052     repository credentials under HOME, or network access. Request the
1053     corresponding grants when needed; do not assume "workdir-read" includes
1054     them. For example, CVS over SSH can use "workdir-read" and "ssh-agent".
1055     The latter includes network access, the agent socket and
1056     "~/.ssh/known_hosts", without exposing private key files or the rest of
1057     HOME. The broker must inherit "SSH_AUTH_SOCK" from your environment.
1058     User-configured helpers outside the runtime mounts need an explicit
1059     trusted mount. An explicit exec grant array replaces the default rather
1060     than adding to it.
1061    
1062     My configuration change seems to be ignored
1063     Check which file and section the process actually selects. Global
1064     settings use the server user's "HOME"/"XDG_CONFIG_HOME". Instance names,
1065     program basenames and multibroker prefixes serve different purposes.
1066    
1067     Restart after changing startup settings, mounts or utilities. Permission
1068     rules need no restart, but their order still matters. Refresh discovery
1069     after a child restart; reconnect a client that retains an old tool list.
1070     "--print-url" reads the current configuration, which can differ from an
1071     older running process.
1072    
1073     The command failed, but the MCP request succeeded
1074     "exec" reports exit status, signal or timeout as a normal tool result. A
1075     successful MCP exchange is not a successful Unix command. Conversely, a
1076     transport failure does not prove a command did nothing: it may have
1077     completed before the connection was lost. Calls are not automatically
1078     replayed after a transport failure.
1079    
1080     TESTING
1081     The default test level is 0. It checks protocol behaviour, permissions,
1082     validation and ordinary process operation, including worker cancellation
1083     and reaping. Watchdogs allow slow machines time to finish; they do not
1084     make successful tests wait for the whole timeout.
1085    
1086     prove -Ilib t
1087    
1088     Set "PERL_ANYEVENT_MCP_TESTS" to 1 to include the extended tests:
1089    
1090     PERL_ANYEVENT_MCP_TESTS=1 prove -Ilib t
1091    
1092     Level 1 adds GNU find/grep/sed/patch operations, real Vim scripting,
1093     browser transfer integration, short idle-lifetime tests, a helper
1094     descendant holding a pipe open, and tests which deliberately wait for a
1095     command timeout or cancel a form helper across several processes. Run
1096     this level before releases. Values greater than 1 currently select the
1097     same tests as level 1.
1098    
1099     Missing GNU utilities or required Vim functions cause explicit skips
1100     even at level 1. The permission and form UI tests use a YAD stand-in:
1101     neither level requires YAD, X11 or an interactive display. The
1102     filesystem tests use a bubblewrap stand-in and check arguments and
1103     worker behaviour; they do not test kernel isolation. The browser tests
1104     use simulated peers.
1105    
1106     WHERE TO GO NEXT
1107     For available tools and server-specific options:
1108    
1109     perldoc mcp-fs
1110     perldoc mcp-multibroker
1111     perldoc mcp-vim
1112     perldoc mcp-ask-user
1113     perldoc anyevent-mcp
1114    
1115     For a complete first Perl server, options, replies, permission checks
1116     and asynchronous work, see "TUTORIAL" in AnyEvent::MCP::Server::Simple.
1117     For the module map and shared configuration reference, see
1118     AnyEvent::MCP. For permission rule details, see
1119     AnyEvent::MCP::Server::Permissions.
1120    
1121     SEE ALSO
1122     AnyEvent::MCP, AnyEvent::MCP::Server::Simple, mcp-fs, mcp-multibroker,
1123     mcp-vim, mcp-ask-user, AnyEvent::MCP::Server::Permissions
1124