io.github.andrew-ji-cupix/cupix-compass

list-my-projects

List construction projects the user can access within a team. **Use this tool ONLY when the user wants to switch project or has no saved current project.** If `check-current-project` returns a saved facility_key, do NOT call this tool — call the analysis tool directly with no arguments. Required workflow when this tool IS appropriate: 1. Present the returned projects to the user. 2. Wait for the user to select one. 3. Call `set-focus-project` with team_domain and facility_key to persist the selection so future sessions skip this step. 4. Then invoke analysis tools. Args: team_domain: Team domain. Optional; if omitted, falls back to the saved current project, otherwise returns the team list so the caller can pick a team first. Returns: str: Accessible facilities with their keys and names.

ask-about-project-data

Query the construction project database using natural language (Text-to-SQL). Converts natural language into SQL to retrieve captures, annotations, progress metrics, schedules, and other project records. Pass the user's question as-is without modification. For trade visibility, use `analyze-progress-and-forecasts` instead. **WORKFLOW:** - **Default**: call this tool with only `query`. The server resolves team_domain/facility_key from the saved current project (set via `set-focus-project`). Do NOT call `list-my-projects` again just to obtain these values. - Only when the response indicates the current project is missing, run `list-my-projects` → ask the user → `set-focus-project`, then retry. - Pass explicit team_domain/facility_key **only** when the user clearly wants to query a different project than the saved one. **Available tables:** - progresses: SI progress metrics (level, category, phase, workarea, cost, dates) - captures: Camera captures metadata (level, camera_model, capture_state, user_email) - records: Capture events with timestamps (captured_at, state, id) - photo_notes: Photonotes (description, state, user_email, created_at) - voice_notes: Voicenotes (level, description, state, user_email, created_at) - facilities: Site info (name, address, size, location, bim_count, created_at) - users: User profiles (name, email) - workareas: Spatial zones (level, name, user_name) Args: query: Natural language question (pass as-is, no SQL syntax) team_domain: Omit by default. Pass only to override the current project. facility_key: Omit by default. Pass only to override the current project. Returns: Query results as tab-separated text

set-focus-project

Save the user's current team and project so subsequent tool calls can omit the `team_domain` / `facility_key` arguments. Args: team_domain: Team domain to remember (required unless `clear=True`). facility_key: Facility key to remember (required unless `clear=True`). clear: If true, delete the stored selection and ignore the other args. Returns: Human-readable confirmation message.

check-current-project

Return the currently saved team_domain and facility_key for this user.

No parameters.

search-site-photos

Search 360° captures (panoramic site photos) by visual content analysis. Searches what is VISUALLY SEEN in 360° captures — safety hazards, quality issues, work types, objects, equipment, materials, and physical site conditions. Do NOT use for capture counts or statistics — use `ask-about-project-data` instead. **WORKFLOW:** - **Default**: call this tool with only `query` (and optionally date filters / limit). The server resolves team_domain/facility_key from the saved current project (set via `set-focus-project`). Do NOT call `list-my-projects` again just to obtain these values. - Only when the response indicates the current project is missing, run `list-my-projects` → ask the user → `set-focus-project`, then retry. - Pass explicit team_domain/facility_key **only** when the user clearly wants to search a different project than the saved one. **Date filtering:** Only use start_date/end_date when the user explicitly mentions dates. Format: YYYY-MM-DD. Omit entirely for general queries without date context. Args: query: Keywords or phrases describing what to find in 360° captures team_domain: Omit by default. Pass only to override the current project. facility_key: Omit by default. Pass only to override the current project. limit: Maximum number of results (default: 10) start_date: Start date filter, YYYY-MM-DD (omit if no date context) end_date: End date filter, YYYY-MM-DD (omit if no date context) Returns: ToolResult: Image viewer links, 3D coordinates, and capture dates

analyze-progress-and-forecasts

Analyze Work In Place (WIP) progress from SiteInsights(SI) — completion rates, delays, and forecasts. Generates a progress report: overall completion, progress by category/vendor/level, delay analysis, and estimated completion dates. **WORKFLOW:** - **Default**: call this tool with NO arguments. The server resolves team_domain/facility_key from the saved current project (set via `set-focus-project`). Do NOT call `list-my-projects` again just to obtain these values — the saved selection is the source of truth. - Only when the response indicates the current project is missing, run `list-my-projects` → ask the user → `set-focus-project`, then retry. - Pass explicit arguments **only** when the user clearly wants to analyze a different project than the saved one. Args: team_domain: Omit by default. Pass only to override the current project. facility_key: Omit by default. Pass only to override the current project. Returns: Progress analysis report with completion rates and forecasts