topos.mcp.security

Path-safety helpers for the Topos MCP server.

The server refuses to read files outside FILE_ACCESS_ROOT. Resolution order:

  1. TOPOS_MCP_FILE_ROOT env var, if set.

  2. The nearest ancestor of cwd that contains .git or pyproject.toml (auto-detect project root).

  3. Fail closed: tools return an error explaining how to configure the root.

This avoids the silent fallback to cwd that made the old default fail open when launched from some MCP clients.

exception topos.mcp.security.FileRootNotConfiguredError[source]

Bases: RuntimeError

Raised when no file-access root could be determined.

topos.mcp.security.resolve_file_root()[source]

Determine the canonical file-access root, caching the result.

Call reset_file_root_cache() after mutating TOPOS_MCP_FILE_ROOT during tests.

topos.mcp.security.reset_file_root_cache()[source]

Clear the cached root; useful in tests.

topos.mcp.security.is_within_root(path, root=None)[source]

Return True if path is equal to or a descendant of the root.

topos.mcp.security.read_safe_utf8_file(filepath)[source]

Read a UTF-8 file if it is within the configured root.

Returns (source, None) on success or (None, {"error": "..."}) when the file cannot be read safely.

topos.mcp.security.resolve_within_root(filepath)[source]

Resolve a path and check it’s inside the root, without reading it.