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. expiry defaults to seven days. ids contains 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 after expiry seconds, 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.