open_repository
Open a repository to load its latest snapshot or scan source code for analysis and querying.
Instructions
Open a repository, loading latest snapshot or scanning source as needed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | ||
| language | No | auto | |
| rescan | No | ||
| run_preanalysis | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Main business logic for the open_repository tool. Creates an engine handle via the registry, checks for a latest snapshot, and either loads it or scans the repository (optionally running preanalysis), then returns session info, summary, and snapshot details.
def open_repository( self, repo_path: str, language: str = "auto", rescan: bool = False, run_preanalysis: bool = True, ) -> dict[str, Any]: handle = self.registry.open_repository(repo_path, language=language) latest_snapshot = self._latest_snapshot_info(handle.repo_path) should_scan = rescan or latest_snapshot is None if latest_snapshot is not None: handle.last_snapshot_path = latest_snapshot["snapshot_dir"] handle.snapshot_metadata = latest_snapshot["metadata"] metadata_language = latest_snapshot["metadata"].get("language") if metadata_language and language == "auto": handle.language = metadata_language if not should_scan: handle.engine = self._load_snapshot_engine(latest_snapshot["snapshot_dir"]) handle.last_scan_at = self._snapshot_created_at(latest_snapshot["metadata"]) handle.preanalysis_ran = bool(latest_snapshot["metadata"].get("preanalysis_ran")) handle.applied_augmentations = list(latest_snapshot["metadata"].get("augmentations") or []) if should_scan: scan_result = self._scan_handle(handle, language=handle.language, run_preanalysis=run_preanalysis) snapshot_result = self.save_snapshot(session_id=handle.session_id) return { "session": self._handle_to_dict(handle), "summary": scan_result["summary"], "preanalysis": scan_result["preanalysis"], "snapshot_dir": snapshot_result["snapshot_dir"], } return { "session": self._handle_to_dict(handle), "latest_snapshot": latest_snapshot, } - Low-level registry method that creates a new EngineHandle with a session_id, resolves the path, and registers it as the default session.
def open_repository(self, repo_path: str | Path, language: str = "auto") -> EngineHandle: path = Path(repo_path).resolve() session_id = uuid4().hex handle = EngineHandle( session_id=session_id, repo_path=path, language=language, created_at=datetime.now(UTC), ) self._sessions[session_id] = handle self._default_session_id = session_id return handle - src/trailmark_mcp/mcp_app.py:21-34 (registration)MCP tool registration via @mcp.tool() decorator. Defines the FastMCP tool named 'open_repository' with parameters repo_path, language, rescan, and run_preanalysis, delegating to app_runtime.open_repository().
@mcp.tool() def open_repository( repo_path: str, language: str = "auto", rescan: bool = False, run_preanalysis: bool = True, ) -> dict[str, Any]: """Open a repository, loading latest snapshot or scanning source as needed.""" return app_runtime.open_repository( repo_path, language=language, rescan=rescan, run_preanalysis=run_preanalysis, ) - Tool spec definition in TOOL_SPECS catalog. Declares parameter types and defaults: repo_path (string, required), language (string, default 'auto'), rescan (boolean, default False), run_preanalysis (boolean, default True).
ToolSpec( name="open_repository", category="lifecycle", description="Open a repository, loading the latest snapshot when present or scanning source when needed.", parameters={ "repo_path": _param("string", required=True), "language": _param("string", default="auto"), "rescan": _param("boolean", default=False), "run_preanalysis": _param("boolean", default=True), }, ), - src/trailmark_mcp/models.py:11-22 (helper)EngineHandle dataclass used to represent the state of an open repository session, including session_id, repo_path, language, engine, timestamps, and snapshot metadata.
@dataclass class EngineHandle: session_id: str repo_path: Path language: str engine: QueryEngine | None = None created_at: datetime | None = None last_scan_at: datetime | None = None preanalysis_ran: bool = False applied_augmentations: list[str] = field(default_factory=list) last_snapshot_path: Path | None = None snapshot_metadata: dict[str, Any] | None = None