NAME

AnyEvent::MCP::Workdirs - persistent filesystem workdir IDs

DESCRIPTION

The registry assigns small positive integers to resolved absolute workdir paths. It is shared by filesystem server 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 AnyEvent::MCP::File for the locked state-file operations.

METHODS

$registry = AnyEvent::MCP::Workdirs->new (file => $file, paths => [$path...], expiry => $seconds)

Resolve IDs for the supplied resolved paths, 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.