NAME
AnyEvent::MCP::Workdirs - persistent filesystem workdir IDs
DESCRIPTION
The registry assigns small positive integers to pathname strings. mcp-fs supplies logical absolute pathnames without following symlinks; relative local workdir arguments are made absolute lexically. The same logical pathname on two hosts gets the same ID even if its symlink resolves to a different physical directory. IDs compress pathnames, not host identities or permissions. The registry is shared by instances using the same file. Permission-rule identities remain independent of these selectors.
It is used by mcp-fs so assistants can refer to a workdir by a short, stable-while-retained number instead of repeating its pathname. It is not a filesystem authorization mechanism: the selected workdir and the permission engine still determine what an operation may access. Applications that do not expose workdirs do not need this module.
use AnyEvent::MCP::Workdirs;
my $registry = AnyEvent::MCP::Workdirs->new (
file => $registry_file, paths => [$resolved_project_path],
);
my $id = $registry->{ids}[0];
$registry->refresh; # repeat periodically while the server runs
See "SANDBOX GRANTS" in mcp-fs for how the server interprets these IDs, and "SMALL UTILITIES" in AnyEvent::MCP for the locked state-file operations.
METHODS
- $registry = AnyEvent::MCP::Workdirs->new (file => $file, paths => [$path...], expiry => $seconds)
-
Resolve IDs for the supplied pathnames, reserving new allocations under the file lock.
expirydefaults to seven days.idscontains the assigned IDs in path order and stays fixed for this object's lifetime. The caller refreshes immediately and periodically while its server is running. - $registry->refresh
-
Lock and reread the JSON registry, overwrite this server's assigned IDs with their paths and the current
last_use, expire old entries afterexpiryseconds, and atomically replace the file. This never resolves or reallocates the server's IDs. Startup allocations reuse the smallest available positive IDs; configured paths retain their previous IDs if nobody reused them.Entries are
ID => [workdir, last_use]. The JSON uses UTF-8 with pretty printing. Manual changes require restarting filesystem servers using the registry.