ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/AnyEvent-MCP/lib/AnyEvent/MCP.pm
Revision: 1.14
Committed: Sun Oct 11 01:08:53 2026 UTC (5 weeks, 3 days ago) by root
Branch: MAIN
Changes since 1.13: +116 -17 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3     AnyEvent::MCP - Model Context Protocol client/server support
4    
5     =head1 SYNOPSIS
6    
7 root 1.6 use AnyEvent::MCP::Server::Simple ();
8 root 1.1
9     mcp_tool ...
10 root 1.3 mcp_start;
11 root 1.1
12     or use the object interface directly:
13    
14 root 1.6 use AnyEvent::MCP::Server ();
15 root 1.1
16     my $server = AnyEvent::MCP::Server->new (...);
17    
18     =head1 DESCRIPTION
19    
20     AnyEvent::MCP provides event-driven Model Context Protocol client and server
21     support.
22    
23     The usual way to implement a small MCP server is
24     L<AnyEvent::MCP::Server::Simple>, which provides a function-based interface and
25     creates the underlying server objects when a transport such as stdio or HTTP is
26     started.
27    
28     The lower-level object interfaces are intended for applications that need to
29     manage MCP connections, servers or reusable tool registries directly.
30    
31     =head2 MODULES
32    
33 root 1.7 =over
34 root 1.1
35     =item L<AnyEvent::MCP::Server::Simple>
36    
37     Function-based interface for implementing ordinary MCP servers.
38    
39     =item L<AnyEvent::MCP::Server>
40    
41     Object-oriented MCP server interface.
42    
43     =item L<AnyEvent::MCP::Client>
44    
45     Object-oriented MCP client interface.
46    
47     =item L<AnyEvent::MCP::Server::Toolset>
48    
49     Reusable registry of MCP tool declarations.
50    
51     =item L<AnyEvent::MCP::Server::Permissions>
52    
53     Permission and capability handling for MCP servers.
54    
55     =back
56    
57 root 1.4 C<mcp-multibroker> combines downstream HTTP and stdio servers under tool-name
58     prefixes. It uses the same client, server and permission helper facilities,
59     including modern input forwarding and local permission prompts for legacy
60     callers. Run C<mcp-multibroker --help> for command-line syntax; its manual
61     describes authentication and configuration.
62    
63 root 1.9 The interfaces are still being designed. The walkthrough below explains the
64     installed programs; module-specific POD documents their Perl APIs.
65    
66     =head1 GETTING STARTED
67    
68     This distribution contains an MCP client/server library and several ready-to-use
69     programs. You do not need to write Perl to use them.
70    
71     =over
72    
73     =item C<mcp-fs>
74    
75     A filesystem and command server. Each operation runs in a Linux bubblewrap
76     sandbox with only the filesystem and other capabilities approved for that
77     operation. Read, write, search, patch, path operations and command execution
78     are exposed as MCP tools.
79    
80     =item C<mcp-multibroker>
81    
82     Combines several MCP servers behind one connection. Each downstream server has
83     a prefix, so a C<file-read> tool belonging to C<files> becomes
84     C<files.file-read>. Its clients may connect over HTTP or be launched over
85     stdio. The multibroker itself can serve HTTP or stdio.
86    
87     =item C<anyevent-mcp> and C<anyevent-mcp-askpermission>
88    
89     Manage shared credentials/rules and ask the local user for permission,
90     respectively. Normally the permission helper is started automatically.
91    
92     =back
93    
94     =head2 Start with one filesystem server
95    
96     Install this Perl distribution first. On Debian or Ubuntu, install the
97     runtime sandbox and optional graphical permission helper with:
98    
99     sudo apt install bubblewrap yad
100    
101     The executable is called C<bwrap>, although the package is C<bubblewrap>.
102     C<yad> provides graphical approval dialogs; without it, the default helper
103     tries C</dev/tty> and denies if no terminal is available. Unprivileged user
104     namespaces must be available. C<mcp-fs> also uses GNU C<find>, C<grep>,
105     C<patch> and C<sed>, and a compatible Perl interpreter. On a minimal
106     Debian installation, these can be installed with:
107    
108     sudo apt install findutils grep patch sed perl
109    
110     Tools whose required programs are missing are omitted at startup.
111    
112     Give the server one or more directories that you actually intend to make
113     available. For example:
114    
115 root 1.12 mcp-fs --name code --bind :31741 /home/alice/src/project
116 root 1.9
117 root 1.12 This starts an authenticated HTTP MCP server without printing its URL.
118 root 1.14 C<mcp-fs --name code --bind :31741 --print-url> obtains its URL without
119     opening another listener; both invocations must use the same overrides.
120 root 1.12 keep it private. The same token also works in an Authorization bearer
121     header. C<--bind :0> selects an ephemeral port, for which a URL cannot
122     be predicted. The permission-rule file is printed on stderr.
123 root 1.9
124     For a local MCP client that starts its servers as subprocesses, use stdio:
125    
126     mcp-fs --stdio /home/alice/src/project
127    
128     The MCP client, not a human terminal, should start this process: stdin and
129     stdout carry protocol messages. For a quick manual sandbox test without MCP
130     or permission prompting, run from the intended workdir:
131    
132     mcp-fs --exec-cmd workdir-read -- ls
133    
134     C<--exec-cmd> runs the supplied command with exactly the named capabilities,
135     without consulting saved permission rules. It is a local debugging facility.
136    
137     Within MCP, begin with the C<workdirs> tool to inspect the configured
138     workdirs and capabilities. Relative paths are resolved against the selected
139     workdir; access beyond the granted mounts needs additional permission.
140     Providing a workdir does not give arbitrary commands unrestricted host access.
141     See L<mcp-fs/CAPABILITIES> and L<mcp-fs/LIMITATIONS>.
142    
143     Once the client is connected, you can just ask the LLM to use the tools,
144     for example:
145    
146     Show me the available workdirs, find the TODO comments in my project,
147     and suggest the next task. Do not modify any files.
148    
149     The client can call C<workdirs> and C<grep> itself; you need not know the
150     MCP request format or write your own integration.
151    
152     =head2 Combine servers with mcp-multibroker
153    
154     Rather than configure each MCP client with every server, configure them
155     once behind the multibroker. For example, to expose two distinct filesystem
156     servers over one HTTP endpoint:
157    
158 root 1.14 mcp-multibroker code 'stdio:mcp-fs --name code /home/alice/src/project' \
159     notes 'stdio:mcp-fs --name notes /home/alice/notes'
160 root 1.9
161     Each C<stdio:> value is a shell command; quote it as one argument.
162     The multibroker starts the child with the correct stdio environment
163 root 1.14 and an alias equal to its prefix. The explicit C<--name> arguments
164     select separate C<mcp-fs> rule files; the routing alias by itself
165     does not change the filesystem server's name.
166 root 1.9
167 root 1.14 The multibroker's C<--print-url> prints its authenticated HTTP URL. A client sees
168 root 1.9 tools such as C<code.file-read>, C<code.file-patch> and
169     C<notes.file-read>. The additional C<discover-brokers>, C<list-tools>
170     and C<call-tool> tools support explicit discovery and dispatch.
171     The client normally can call the prefixed tools directly.
172    
173     If the LLM is still using an old tool list after a downstream server
174     becomes available or changes its tools, simply tell it:
175    
176     Call discover-brokers and list-tools again, then use the newly
177     discovered tools.
178    
179     C<discover-brokers> connects to reachable servers and retrieves their
180     instructions; C<list-tools> requests their current tool lists. C<call-tool>
181     can dispatch a newly discovered prefixed tool even when the client has not
182     refreshed its own direct tool list yet. If the client hides or caches the
183     broker's tools, reconnect or refresh the MCP connection in that client.
184     Changing the broker's configured prefix/URL pairs requires restarting
185     C<mcp-multibroker>; discovery cannot change its command-line configuration.
186    
187     The same broker can mix remote HTTP servers with local subprocesses.
188     For example, an installation might combine office and automation tools:
189    
190     mcp-multibroker \
191     office http://localhost:8766/mcp \
192     homeassistant http://homeassistant.local:8123/api/mcp \
193     --bearer TOKEN \
194     marco http://marco.example.net:31746/COOKIE/
195    
196     Or combine a custom application server, remote machines and a third-party
197     stdio server:
198    
199     mcp-multibroker \
200     agni 'stdio:/opt/agni/bin/agni-mcp' \
201     cerebro http://cerebro.example.net:31748/COOKIE/ \
202     chrome 'stdio:npx -y chrome-devtools-mcp@latest --no-usage-statistics'
203    
204     These are illustrative hostnames and redacted credentials, not usable
205     endpoints. C<--bearer> belongs immediately after the HTTP server it
206     authenticates. A cookie URL already carries its credential. Never publish
207     or check in either kind of secret. The broker does not impose the C<mcp-fs>
208     bubblewrap sandbox on other servers: those processes and services have their
209     own security boundaries. A shell wrapper can use C<exec mcp-multibroker>
210     to replace itself with the broker process.
211    
212     To start the multibroker itself over stdio, let the client set
213     C<PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio>, or use a command like:
214    
215     PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio \
216     mcp-multibroker code 'stdio:mcp-fs /home/alice/src/project'
217    
218     The broker can also connect to existing HTTP MCP servers:
219    
220     mcp-multibroker files 'stdio:mcp-fs /home/alice/src/project' \
221     remote https://example.org/mcp/ --bearer TOKEN
222    
223     The token is a credential; avoid exposing it in shell history or process
224     arguments in a real deployment. An HTTP client can instead use
225     C<[client PREFIX]> in the private global configuration. See
226     L<mcp-multibroker> and L</GLOBAL CONFIGURATION>.
227    
228     =head2 Connect an AI client
229    
230     These are examples for clients with MCP support. Paths are illustrative;
231     substitute your installed commands and real workdirs. Client interfaces
232     evolve independently of this module, so consult their documentation if an
233     option has changed.
234    
235     =head3 OpenAI Codex CLI
236    
237     Codex can start the broker locally over stdio:
238    
239     codex mcp add mytools --env PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio \
240     -- mcp-multibroker \
241     files 'stdio:mcp-fs /home/alice/src/project'
242     codex mcp list
243    
244     Use C</mcp> within Codex to inspect connections.
245     See L<Codex MCP documentation|https://learn.chatgpt.com/docs/extend/mcp>.
246    
247     =head3 Anthropic Claude Code
248    
249     Claude Code can start the same broker:
250    
251     claude mcp add --transport stdio --scope user mytools \
252     --env PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio -- \
253     mcp-multibroker files 'stdio:mcp-fs /home/alice/src/project'
254     claude mcp list
255    
256     Use C</mcp> within Claude Code for connection status. See
257     L<Claude Code MCP documentation|https://code.claude.com/docs/en/mcp>.
258    
259     =head3 Google Gemini CLI
260    
261     Add a local broker to C<~/.gemini/settings.json> (merge with any existing
262     settings):
263    
264     {
265     "mcpServers": {
266     "mytools": {
267     "command": "mcp-multibroker",
268     "args": [
269     "files", "stdio:mcp-fs /home/alice/src/project"
270     ],
271     "env": {
272     "PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL": "stdio"
273     }
274     }
275     }
276     }
277    
278     Use C</mcp> in Gemini CLI to inspect the connection.
279     See L<Gemini CLI MCP documentation|https://geminicli.com/docs/tools/mcp-server/>.
280    
281     =head3 ChatGPT web
282    
283     ChatGPT is a hosted client and cannot spawn a local stdio process or
284     connect directly to a local loopback server. Start C<mcp-multibroker> in
285     HTTP mode and connect it through ChatGPT's custom MCP plugin setup.
286     For a private local server, use an appropriately configured Secure MCP
287     Tunnel rather than making the machine publicly accessible. The connection
288     is subject to the client's plan, workspace and feature permissions.
289     See L<ChatGPT custom MCP servers|https://developers.openai.com/api/docs/guides/custom-mcp-server>
290     and L<Secure MCP Tunnel|https://developers.openai.com/blog/connect-private-mcp-servers-to-openai-products>.
291    
292 root 1.14 =head2 HTTP authentication: URL tokens and bearer headers
293    
294     The bundled HTTP servers require an unguessable token for every MCP POST.
295     A client can supply any accepted token in one of two ways:
296    
297     POST /TOKEN/ # credential-bearing URL
298     POST / # Authorization: Bearer TOKEN
299    
300     Those paths are for the bundled servers, whose HTTP endpoint is C</>.
301     For another endpoint path, C</TOKEN> prefixes that path. URL tokens are
302     B<not> HTTP cookies: the server does not depend on browser-managed login
303     state. HTTP Basic authentication is not supported. Neither is OAuth token
304     validation; a string that looks like a JWT is still just a static token here.
305    
306     Without explicit configuration, each named server derives one stable token
307     from the private global master secret. For several tokens, configure:
308    
309     [server code]
310     tokens = first-secret,second-secret
311    
312     or use repeated C<--token TOKEN> switches when starting the server.
313     The command-line list replaces the entire configured list, and either
314     replaces the derived default. All tokens authorize the same operations;
315     their order only decides which is printed by C<--print-url>. They are
316     not permission levels, and adding a second token does not create a
317     second user.
318    
319     For example, to retrieve the URL of a running configuration without
320     starting another server:
321    
322     mcp-fs --name code --bind :31741 --print-url
323    
324     Repeat any C<--bind> and C<--token> overrides used to start that server,
325     and run the command under the same user and configuration directory.
326     C<--print-url> exits without listening. Port zero cannot be predicted
327     in advance. Extract the token from the URL when a client requires an
328     Authorization header instead.
329    
330     Protect token-bearing URLs, configuration files, shell histories and process
331     arguments. Use TLS or an appropriate tunnel across untrusted networks.
332     An Origin allowlist is a browser restriction, not a credential; accepting
333     requests from a particular origin never grants access by itself. A CORS
334     preflight can answer without authentication, but an MCP POST still requires
335     its token. Localhost has many virtues; authentication isn't one of them.
336    
337     C<stdio> uses the parent client's process connection rather than HTTP,
338     so it has no URL or bearer-header authentication. That says nothing about
339     whether a tool operation is approved: the permission system below is a
340     separate decision. For custom servers, C<mcp_start> supplies the named
341     default token; the low-level L<AnyEvent::MCP::Server::HTTP> object requires
342     explicit C<tokens> (or authentication enforced by its embedding layer).
343     See L<AnyEvent::MCP::Server::Simple> for the function interface.
344    
345 root 1.9 =head2 Permissions and approval dialogs
346    
347     C<mcp-fs> does not treat a connected model as fully trusted. Each tool
348     asks for the authority it needs; you can allow or deny the request once,
349     or save a rule for subsequent matching requests. Its default prompting
350     mode is C<--ask helper>, using C<anyevent-mcp-askpermission> on the
351     server's machine (YAD or C</dev/tty>). Closing the prompt denies once.
352    
353 root 1.14 C<mcp-fs> asks for an B<action> such as C<inspect>, C<read>,
354     C<write>, C<manage> or C<exec>. This is authorization to perform a kind of
355     operation, not a synonym for the MCP tool name: C<file-read> and C<grep>
356     both request C<read>. Independently, the worker needs B<sandbox grants>,
357     such as C<workdir-read>, C<workdir-write>, C<network> or C<world-write>.
358     The permission engine decides which grants are allowed; the worker's
359     bubblewrap sandbox must enforce that decision. Approving C<read> does not
360     approve C<write>. The authentication token gets a client to the door,
361     not through every door inside.
362    
363     For example, C<mcp-fs --name code> reads its rules from
364     C<$XDG_CONFIG_HOME/anyevent-mcp/rules-fs-code.ini>, or the corresponding
365     C<$HOME/.config> path. The following ordered rules allow reading within
366     one directory tree while requiring explicit approval for everything else
367     except execution, which is denied:
368    
369     [rule]
370     decision=allow
371     action=read
372     subject=^/home/alice/src/project/
373     sandbox-grants=workdir-read
374    
375     [rule]
376     decision=deny
377     action=exec
378    
379     Rules are tried B<in order>, stopping at the first match. Action and
380     subject match literally unless the matcher starts with C<^>, in which
381     case it is a Perl regular expression. A missing subject matches all
382     subjects. Allow rules must specify C<sandbox-grants>, and only authorize
383     requests whose needed grants are covered, including implied grants.
384     For example, C<workdir-write> implies C<workdir-read>, but C<network>
385     remains a separate grant. An explicit C<ask> rule can force a prompt;
386     otherwise a request not covered by any rule is prompted automatically.
387    
388     When prompted, choose allow or deny, once or always. Permanent choices
389     are appended as rules using an offered scope such as the exact path,
390     containing directory or workdir. Broader scopes are not inferred from
391     good intentions. A worker that needs several paths checks each, and
392     its effective sandbox grants are restricted to those allowed for all
393     of them. The accepted rule file is reread for subsequent checks without
394     restarting the server. Editing it changes policy, not the token.
395    
396 root 1.9 For a client that supports the newer MCP form-elicitation protocol, try:
397    
398     mcp-fs --ask auto --stdio /home/alice/src/project
399    
400     C<--ask auto> uses MCP elicitation when the client advertises the necessary
401     support, otherwise the local helper. C<--ask mcp> requires elicitation and
402     fails if it is unavailable; it does not silently fall back. Not all MCP
403     clients or versions support the required input/continuation flow, even if
404 root 1.14 they support ordinary tool calls. Use client-side approval only if that
405     client is a trusted authority to grant access; otherwise keep the prompt
406     on the server machine. For an ordinary stdio broker configuration, put
407     the chosen option in the child command:
408 root 1.9
409     mcp-multibroker files \
410 root 1.14 'stdio:mcp-fs --name files --ask auto /home/alice/src/project'
411 root 1.9
412 root 1.14 Use C<--name NAME> to choose the filesystem server's rules file,
413     independently of the multibroker's routing prefix. Rule files must be
414     private and owned by the server user. They can be edited directly, or
415     managed with C<anyevent-mcp rules FILE>. Review persistent rules rather
416     than granting C<world-write> casually. For worker sandbox details see
417     L<mcp-fs/SANDBOX GRANTS>; for the programming interface and rule syntax
418     see L<AnyEvent::MCP::Server::Permissions>.
419 root 1.9
420     =head2 Further documentation
421    
422     perldoc mcp-fs
423     perldoc mcp-multibroker
424     perldoc anyevent-mcp
425     perldoc AnyEvent::MCP::Server::Simple
426     perldoc AnyEvent::MCP::Server::Permissions
427    
428     The programs describe their own command-line options. If a client reports
429     no tools, first check that the selected program starts and that its required
430     utilities are detected. Stdio servers must not print diagnostics or banners
431     to stdout. For HTTP, check that the client can reach the configured URL and
432     has the correct authentication credentials.
433 root 1.1
434 root 1.2 =head1 GLOBAL CONFIGURATION
435    
436     The shared per-user configuration is C<$XDG_CONFIG_HOME/anyevent-mcp/global.ini>,
437     or C<$HOME/.config/anyevent-mcp/global.ini> when XDG_CONFIG_HOME is unset.
438     L<AnyEvent::MCP::Config> loads and holds it; loading this module does not access
439     configuration files.
440    
441     The file is UTF-8 and uses sections with single-line C<key = value> pairs.
442     Values are unquoted strings. Blank lines and whole-line comments beginning
443     with C<#> or C<;> are ignored; inline comment characters remain part of the
444     value. Later occurrences of a key replace earlier ones in the same section.
445    
446     [global]
447     secret = ...128 hexadecimal digits...
448    
449     [server example]
450 root 1.11 bind = 127.0.0.1:31740
451 root 1.13 tokens = first-token,second-token
452 root 1.2
453     [mcp-fs]
454     utility = /path/to/utility
455    
456     Section names are unrestricted. Application-specific sections, including
457     exports, utility paths and user settings, are documented by their applications.
458    
459     C<[global]> holds C<secret>, a 64-byte master key encoded as 128 hexadecimal
460     digits. The file must be owned by the current user, with no group or other
461     permissions. A missing secret is generated automatically on first configuration
462     access and saved when possible. Existing secrets are never replaced implicitly.
463     An invalid secret is an error.
464    
465     If saving fails, Config warns and retains the secret in memory. Credentials
466     then remain stable only for that process; other processes cannot derive the
467     same credentials. If randomness is unavailable, supply a securely generated
468     secret in the file.
469    
470 root 1.13 C<[server NAME]> holds named-server settings.
471 root 1.11 HTTP-capable executables use C<--name NAME> to select these settings, with
472     the executable basename as the default name. Names consist of an ASCII
473     letter or underscore followed by ASCII letters, digits, underscores or
474     hyphens. Their C<--bind ADDRESS[:PORT]> overrides the configured C<bind>.
475     The default bind address is IPv4 loopback with a port derived from the name
476     and master secret in the range 16384..32767; C<:0> requests an ephemeral
477 root 1.12 port. C<--print-url> prints the URL using the first accepted token without
478     listening. Named server settings also include C<path>, C<url_host>,
479     C<url_scheme> and C<tokens>. C<tokens> is a comma-separated list of
480     URL-safe strings. Repeated C<--token TOKEN> options override this list.
481     All accepted tokens work in the URL path or Authorization bearer header.
482     Without configured tokens, one server-specific token is derived.
483 root 1.11
484 root 1.12 C<mcp_start> resolves named settings and requires the selected token for
485     HTTP requests. Explicit tokens replace the derived default.
486 root 1.11 The low-level HTTP transport does not resolve configuration itself.
487     Stdio startup does not access global HTTP configuration. Browser origins
488     are permitted by default, but must still pass MCP authentication.
489 root 1.3
490 root 1.12 C<[client NAME]> supplies HTTP client defaults: C<url>, C<bearer> and
491     C<timeout>. Clients consult it only when explicitly given a C<name>.
492     An unnamed client or HTTP server does not read global configuration.
493 root 1.3 Explicit constructor arguments take precedence over named defaults.
494    
495     =head1 ENVIRONMENT
496    
497     Project-specific environment variables use the C<PERL_ANYEVENT_MCP_> prefix.
498     C<PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio> selects stdio in Simple.
499 root 1.11 C<PERL_ANYEVENT_MCP_MULTIBROKER_ALIAS> names a multibroker routing prefix;
500     it does not change the service-instance name.
501 root 1.3 C<PERL_ANYEVENT_MCP_PERMISSION_HELPER> selects the external asking executable.
502     Standard C<HOME> and C<XDG_CONFIG_HOME> keep their standard names.
503 root 1.2
504     =head1 FUNCTIONS
505    
506 root 1.6 =over
507    
508 root 1.10 =item $class = AnyEvent::MCP::json_class
509    
510     Returns C<JSON::XS> if available, otherwise C<JSON::PP>. The caller
511     configures a new coder instance as needed.
512    
513 root 1.8 =item $bytes = AnyEvent::MCP::utf8enc $text
514    
515     Return a UTF-8 byte string for C<$text>, leaving the argument unchanged.
516    
517     =item $text = AnyEvent::MCP::utf8dec $bytes
518    
519     Decode a UTF-8 byte string into characters, dying on invalid UTF-8.
520     The argument is left unchanged. For intentional in-place conversions,
521     use Perl's C<utf8::encode> or C<utf8::decode> directly.
522    
523 root 1.6 =item $bytes = AnyEvent::MCP::random_bytes $length
524 root 1.2
525     Returns exactly C<$length> random bytes. Tries C</dev/urandom>, then an external
526     C<openssl rand> command. No additional random-number module is required.
527     Dies if neither source supplies the requested bytes successfully.
528     C<$length> must be a nonnegative integer; zero returns an empty string.
529    
530 root 1.6 =back
531    
532     =head2 PATCH UTILITIES
533    
534 root 1.7 Since applying patches to files is a common task for MCP servers, the
535 root 1.6 following utility functions can be used to ease that job. Together, they
536 root 1.7 define a common patch format (unified diff or a simplified version of it,
537     with fewer requirements to make it easier for the LLM to generate), helpers
538 root 1.6 to apply the patch and a helper to verify if the patch was applied
539     with sufficient precision.
540    
541 root 1.7 Use C<apply_udiff> to normalize, apply and validate a patch in one operation.
542     It writes a separate output file; the caller checks freshness and metadata
543     and commits the result.
544    
545     For an application-specific applier, the workflow is:
546 root 1.6
547     =over
548    
549     =item 1. AnyEvent::MCP::normalize_udiff
550    
551 root 1.7 Returns a unified diff for GNU patch and the permitted hunk offsets.
552    
553     =item 2. Apply the normalized diff
554 root 1.6
555 root 1.7 Run GNU patch with fuzz zero and capture its verbose output.
556 root 1.6
557 root 1.7 =item 3. AnyEvent::MCP::check_patch_output
558    
559     Checks the process status and output against the permitted offsets.
560     C<parse_patch_output> is available separately when only parsing is needed.
561 root 1.5
562 root 1.6 =back
563    
564 root 1.5 =head3 Input format
565    
566 root 1.6 The patch format accepted by normalize_udiff is an extension to the
567     (essentially undocumented) unified diff format.
568    
569 root 1.5 In a hunk header, only the old start C<-N> matters. It is the old-file line
570     of the first hunk body line, including context, not necessarily the first
571     changed line. Counts and the new-file position are ignored and recomputed.
572     Both ordinary headers and the abbreviated form are accepted:
573    
574     @@ -42,99 +123,99 @@
575     @@ -42 @@
576    
577     Optional text after the closing C<@@> is preserved. File headers and other
578     text before the first hunk are preserved; a diff must describe one file.
579    
580     Hunk body lines use the usual prefixes: a space for unchanged context,
581     C<-> for removed lines and C<+> for added lines. The
582     C<\ No newline at end of file> marker is preserved and counts neither side.
583     Trailing empty lines outside the final hunk are discarded.
584    
585 root 1.7 Pure insertion is permitted only at the beginning, using old start C<0>.
586     For example, C<@@ -0 @@> with one added line becomes C<@@ -0,0 +1,1 @@>.
587     An empty old-side range names the line before the insertion: C<-0,0>
588     means before line 1, whereas C<-1,0> would mean after line 1 and is rejected
589     here. Nonempty ranges use one-based line numbers.
590    
591 root 1.5 An insertion elsewhere needs old-side context. Empty hunks are rejected.
592     New positions include the cumulative line-count changes of preceding hunks.
593    
594     =head3 Applying the result
595    
596 root 1.6 The C<normalize_udiff> function does not apply the patch, check file
597     contents or guard against concurrent edits. The caller must supply those
598     checks, if required.
599 root 1.5
600     Context must match exactly: apply with fuzz zero. For each hunk,
601     C<$max_offset> permits relocation by at most the number of distinct old-side
602     lines minus one, or zero for a pure insertion. Repeated old-side lines do
603     not increase this allowance. The applier must enforce these limits; an
604     unrestricted search for matching context can select the wrong occurrence.
605    
606     For live Vim buffers, also require the expected changedtick to match.
607     File-based users need an equivalent check before replacing the file.
608    
609 root 1.6 To work around GNU patch's handling of asymmetric context, the
610     first context line of each hunk is rewritten as an identity
611     removal/addition. The line contents and old/new line counts are
612     unchanged. This is normalization for the patch applier, not a relaxation
613     of context matching.
614 root 1.5
615 root 1.6 =over
616    
617     =item ($diff, $max_offset) = AnyEvent::MCP::normalize_udiff $diff
618    
619     Normalizes a relaxed, single-file unified diff into ordinary unified diff
620     syntax. Returns the normalized C<$diff> and an array reference C<$max_offset>
621     containing the permitted whole-hunk relocation for each hunk, in order.
622     Dies on malformed hunks or when no hunks are found.
623    
624     Here is a suitable description for the diff format, e.g. in a tool
625     definition:
626    
627     Apply a unified diff to one regular file. Hunk counts are recomputed,
628     fuzz is disabled, whole-hunk relocation is limited per hunk by distinct
629     old-side lines. Pure insertion is allowed only at the beginning;
630     elsewhere include old-side context.
631    
632     =item $cv = AnyEvent::MCP::apply_udiff $input, $output, $diff
633    
634     Asynchronously applies the relaxed C<$diff> to the input file C<$input>,
635     writing a separate output file C<$output>. C<$diff> must contain bytes;
636     callers working with characters must encode them for the file themselves.
637    
638     Normalizes the diff, runs GNU patch using C<AnyEvent::Util::run_cmd>, and
639     validates its verbose output with C<check_patch_output>. The command uses
640     batch/forward mode, binary mode and fuzz zero. No shell is involved.
641    
642     C<$output> must not exist. It is reserved with mode 0600; patch runs in its
643     directory so incidental temporary files stay there. Input and output paths
644     are made absolute before starting the command. These must be trusted paths
645     in a directory controlled by the caller.
646    
647     Returns a condition variable. Its C<recv> returns the validated hunk array
648     reference, or throws on command/application failure. Setup failures throw
649     synchronously. Failed or partial output is removed. C<$input> is unchanged.
650    
651     The caller owns committing the successful output and removing it when no
652     longer needed. Freshness checks, metadata preservation, atomic replacement
653     and application-specific permissions also belong to the caller.
654    
655     For your reference, the exact options used are:
656    
657     --verbose --batch --forward --binary --fuzz=0
658     --no-backup-if-mismatch
659     --reject-file=- --output=... -- <inputfile>
660    
661     =item $parsed = AnyEvent::MCP::parse_patch_output $output
662 root 1.5
663     Parses C<LC_ALL=C> GNU patch C<--verbose> output without judging whether
664     the application is acceptable. C<$parsed> has two fields:
665    
666 root 1.6 =over
667 root 1.5
668     =item hunks => [$hunk...]
669    
670     Hunk records in output order. Each record contains C<hunk> (the one-based
671     number), C<success>, C<line> (the reported application line), C<fuzz> and
672     the signed C<offset>. Omitted fuzz and offset are zero. Failed and ignored
673     hunks have false C<success>.
674    
675     =item unparsed => [$line...]
676    
677     Lines not recognized as hunk results or GNU patch's verbose framing.
678     The parser preserves them for callers to interpret or reject.
679    
680     =back
681    
682     Use verbose output: ordinary patch output omits exact-position successes,
683     so it cannot account for every hunk.
684    
685 root 1.6 =item $hunks = AnyEvent::MCP::check_patch_output $status, $output, [$max_offset...]
686 root 1.5
687     Parses C<$output> and validates a complete application. C<$status> is the
688     raw process wait status, as returned by C<waitpid> or
689     C<AnyEvent::Util::run_cmd>, not just the exit code.
690    
691     Requires status zero, no unrecognized output, exactly the expected hunks
692     in numbered order, successful application, fuzz zero and each signed offset
693     within its corresponding absolute limit. C<[$max_offset...]> is the array
694     reference returned by C<normalize_udiff>. At least one hunk is required.
695    
696     Returns the parsed hunk array reference on success; otherwise dies with a
697     diagnostic. This is also suitable for callers running patch inside their
698     own sandbox.
699    
700 root 1.6 =back
701 root 1.5
702 root 1.1 =cut
703    
704     package AnyEvent::MCP;
705    
706     use common::sense;
707     use Digest::SHA ();
708    
709     our $VERSION = '0.0';
710    
711 root 1.10 sub json_class {
712     our $JSON_CLASS ||= eval { require JSON::XS; "JSON::XS" }
713     || do { require JSON::PP; "JSON::PP" };
714     }
715    
716 root 1.8 sub utf8enc($) {
717     my $text = shift;
718    
719     utf8::encode $text;
720     $text
721     }
722    
723     sub utf8dec($) {
724     my $bytes = shift;
725    
726     utf8::decode $bytes
727     or die "invalid UTF-8\n";
728     $bytes
729     }
730    
731 root 1.2 sub random_bytes($) {
732     my ($length) = @_;
733    
734     die "Invalid random byte count\n"
735     unless defined $length && $length =~ /\A[0-9]+\z/;
736     return "" unless $length;
737    
738     my $bytes = "";
739    
740     if (open my $fh, "<", "/dev/urandom") {
741     binmode $fh;
742     while (length $bytes < $length) {
743     read ($fh, $bytes, $length - length ($bytes), length $bytes)
744     or last;
745     }
746     close $fh;
747    
748     return $bytes if length $bytes == $length;
749     }
750    
751     if (open my $fh, "-|", "openssl", "rand", $length) {
752     binmode $fh;
753     local $/;
754     $bytes = <$fh>;
755     my $success = close $fh;
756    
757     return $bytes
758     if $success && defined $bytes && length $bytes == $length;
759     }
760    
761     die "Cannot obtain $length random bytes from /dev/urandom or openssl rand\n";
762     }
763    
764 root 1.1 sub hkdf_sha512_expand($$$) {
765     my ($prk, $info, $l) = @_;
766    
767 root 1.2 64 == length $prk
768     or die "hkdf_sha512_expand: prk length mist be 64 octets";
769    
770 root 1.1 my $t = "";
771     my $okm = "";
772     my $i = 0;
773    
774     do {
775     $t = Digest::SHA::hmac_sha512 $t . $info . chr ++$i, $prk;
776     $okm .= $t;
777     } while $l > length $okm;
778    
779     substr $okm, 0, $l
780     }
781    
782 root 1.5 sub normalize_udiff {
783     my $diff = shift;
784     my @line = split /\n/, $diff, -1;
785     my $delta = 0;
786     my $hunks = 0;
787     my @max_offset;
788    
789     pop @line while @line and !length $line[-1];
790    
791     for (my $i = 0; $i < @line; ++$i) {
792     next unless $line[$i] =~ /^@@ /;
793    
794     $line[$i] =~ /^@@ -(\d+)(?:,\d+)?(?: \+\d+(?:,\d+)?)? @@(.*)$/
795     or die "normalize_udiff: bad hunk header '$line[$i]'\n";
796    
797     my ($old_start, $suffix) = ($1, $2);
798     my ($old_count, $new_count) = (0, 0);
799     my %old_line;
800     my $j = $i + 1;
801    
802     # GNU patch mishandles hunks with more prefix than suffix context.
803     # Make the first context line an identity change without losing it.
804     # see https://unix.stackexchange.com/questions/414542/does-patch-work-with-asymmetric-context
805     splice @line, $i + 1, 1, "-$1", "+$1"
806     if $line[$i + 1] =~ /^ (.*)\z/;
807    
808     for (; $j < @line; ++$j) {
809     last if $line[$j] =~ /^@@ /;
810    
811     my $tag = substr $line[$j], 0, 1;
812    
813     if ($tag eq " ") {
814     ++$old_count;
815     ++$new_count;
816     $old_line{substr $line[$j], 1} = 1;
817     } elsif ($tag eq "-") {
818     ++$old_count;
819     $old_line{substr $line[$j], 1} = 1;
820     } elsif ($tag eq "+") {
821     ++$new_count;
822     } elsif ($line[$j] eq "\\ No newline at end of file") {
823     # Marker belongs to the preceding body line and counts neither side.
824     } else {
825     die "normalize_udiff: bad hunk line '$line[$j]'\n";
826     }
827     }
828    
829     $old_count or $new_count
830     or die "normalize_udiff: empty hunk at old line $old_start\n";
831    
832     $old_count or !$old_start
833     or die "normalize_udiff: hunk " . ($hunks + 1)
834     . " needs old-side context for insertion after old line $old_start\n";
835    
836     my $new_start = $old_start + $delta;
837     ++$new_start unless $old_count;
838     --$new_start unless $new_count;
839    
840     $new_start >= 0
841     or die "normalize_udiff: invalid new line $new_start\n";
842    
843     $line[$i] = sprintf "@@ -%d,%d +%d,%d @@%s",
844     $old_start, $old_count, $new_start, $new_count, $suffix;
845    
846     $delta += $new_count - $old_count;
847     ++$hunks;
848     my $max_offset = keys %old_line;
849     --$max_offset
850     if $max_offset;
851     push @max_offset, $max_offset;
852     $i = $j - 1;
853     }
854    
855     $hunks
856     or die "normalize_udiff: no hunks\n";
857    
858     (join ("\n", @line, ""), \@max_offset)
859     }
860    
861     sub parse_patch_output {
862     my ($output) = @_;
863     my (@hunks, @unparsed);
864    
865     for (split /\n/, $output) {
866     if (/^Hunk #(\d+) (succeeded|FAILED|ignored) at (-?\d+)(?: with fuzz (\d+))?(?: \(offset (-?\d+) lines?\))?\.\z/) {
867     push @hunks, {
868     hunk => 0 + $1,
869     success => $2 eq "succeeded",
870     line => 0 + $3,
871     fuzz => 0 + $4,
872     offset => 0 + $5,
873     };
874     } elsif (!length
875     || /^Hmm\.\.\. +Looks like a unified diff to me\.\.\.\z/
876     || /^The text leading up to this was:\z/
877     || /^-+\z/ || /^\|/
878     || /^patching file / || /^checking file /
879     || /^Using Plan [AB]\.\.\.\z/ || /^done\z/) {
880     # GNU patch --verbose framing, not hunk results.
881     } else {
882     push @unparsed, $_;
883     }
884     }
885    
886     { hunks => \@hunks, unparsed => \@unparsed }
887     }
888    
889     sub check_patch_output {
890     my ($status, $output, $max_offset) = @_;
891     my $parsed = parse_patch_output $output;
892     my $hunks = $parsed->{hunks};
893    
894     die "patch failed (wait status $status):\n$output"
895     if $status;
896     die "patch: unrecognized output:\n" . (join "\n", @{$parsed->{unparsed}}) . "\n"
897     if @{$parsed->{unparsed}};
898     die "patch: expected " . @$max_offset . " hunks, got " . @$hunks . "\n"
899     unless @$hunks == @$max_offset && @$hunks;
900    
901     for my $i (0 .. $#$hunks) {
902     my $hunk = $hunks->[$i];
903    
904     die "patch: unexpected hunk number $hunk->{hunk}\n"
905     unless $hunk->{hunk} == $i + 1;
906     die "patch: hunk $hunk->{hunk} failed\n"
907     unless $hunk->{success};
908     die "patch: hunk $hunk->{hunk} used fuzz $hunk->{fuzz}\n"
909     if $hunk->{fuzz};
910     die "patch: hunk $hunk->{hunk} offset $hunk->{offset} exceeds $max_offset->[$i]\n"
911     if abs $hunk->{offset} > $max_offset->[$i];
912     }
913    
914     $hunks
915     }
916    
917     sub apply_udiff {
918     my ($input, $output, $diff) = @_;
919     my ($normalized, $max_offset) = normalize_udiff $diff;
920    
921     require AnyEvent::Util;
922     require File::Spec;
923     require File::Basename;
924     require Fcntl;
925    
926     $input = File::Spec->rel2abs ($input);
927     $output = File::Spec->rel2abs ($output);
928     my $directory = File::Basename::dirname ($output);
929    
930     sysopen my $fh, $output, Fcntl::O_WRONLY () | Fcntl::O_CREAT () | Fcntl::O_EXCL (), 0600
931     or die "$output: $!\n";
932     close $fh or do { my $error = $!; unlink $output; die "$output: $error\n" };
933    
934     my $cv = AE::cv ();
935     my $log;
936     my $process = eval {
937     AnyEvent::Util::run_cmd ([
938     "patch", "--verbose", "--batch", "--forward", "--binary", "--fuzz=0",
939     "--no-backup-if-mismatch", "--reject-file=-", "--output=$output", "--", $input,
940     ],
941     "<" => \$normalized,
942     ">" => \$log,
943     close_all => 1,
944     on_prepare => sub {
945     $ENV{LC_ALL} = "C";
946     chdir $directory or die "$directory: $!\n";
947     defined POSIX::dup2 (1, 2) or die "dup2: $!\n";
948     },
949     );
950     };
951    
952     if ($@) {
953     my $error = $@;
954     unlink $output;
955     die $error;
956     }
957    
958     $process->cb (sub {
959     my $hunks;
960     eval { $hunks = check_patch_output $_[0]->recv, $log, $max_offset; 1 } or do {
961     my $error = $@;
962     unlink $output;
963     $cv->croak ($error);
964     return;
965     };
966    
967     $cv->send ($hunks);
968     });
969    
970     $cv
971     }
972    
973 root 1.1 sub _clean_text($) {
974     my ($text) = @_;
975    
976     my ($prefix) = (join "\n", grep /\S/, split /\n/, $text)
977     =~ /\A([ \t]*)[^\n]*(?:\n\1[^\n]*)*\z/;
978    
979     $text =~ s/^\Q$prefix\E//mg;
980     $text =~ s/\A\s+//;
981     $text =~ s/\s+\z//;
982     $text
983     }
984    
985     package AnyEvent::MCP::Base;
986    
987     sub new {
988     my ($class, %kv) = @_;
989     bless \%kv, $class
990     }
991    
992     sub event {
993     my ($self, $event, @args) = @_;
994     ($self->{"on_$event"} or return)->($self, @args)
995     }
996    
997     =head1 SEE ALSO
998    
999     L<AnyEvent>, L<https://modelcontextprotocol.io/>
1000    
1001     =head1 AUTHOR
1002    
1003     The main author of this module is OpenAI ChatGPT.
1004    
1005     Additional guidance received by:
1006    
1007     Marc Lehmann <schmorp@schmorp.de>
1008     http://home.schmorp.de/
1009    
1010     =cut
1011    
1012     1
1013