Sign in to Trimble Connect via the browser (OAuth2 + PKCE).

Opens the user's default browser at the Trimble Identity login page and listens on the registered localhost callback (TC_REDIRECT_URI, default http://localhost:8385/callback). Tokens are cached locally and refreshed automatically, so this is only needed the first time or after the session fully expires.

The call does NOT block indefinitely: if the sign-in is not finished within wait_seconds it returns {"pending": true, "auth_url": ...} while the callback listener keeps waiting in the background (up to 10 minutes total). In that case tell the user to finish signing in — opening auth_url manually if no browser appeared — and then call tc_auth_status to confirm. Do NOT immediately call tc_login again; a second call simply waits on the same pending login.

Args: wait_seconds: How long to wait before returning a pending result (default 90). Use a small value to return quickly. open_browser: Set false to only return auth_url without launching a browser (useful when the browser cannot be opened automatically).

Returns: {"logged_in": true, "user": {...}} on success, {"logged_in": false, "pending": true, "auth_url": ...} if the user has not finished yet, or {"error": ...}.

Abort a browser sign-in that is still waiting and free the callback port.

Use when a tc_login attempt was abandoned (wrong account, browser closed) and the local callback listener should stop before starting a new login.

Returns: {"cancelled": true|false}

Check whether the user is signed in to Trimble Connect.

Returns login state, token expiry, and the signed-in user's name/email (from the cached ID token). Call this first if any other tool returns an authentication error, and after a tc_login call that came back with "pending": true (login_in_progress marks a browser sign-in still waiting).

Check whether this server may modify data in Trimble Connect.

Write tools (create/rename/move/copy/upload/delete, permissions, members, groups) only work when the environment variable TC_ENABLE_WRITE=1 is set for this MCP server in Claude Desktop. Destructive tools additionally require confirm=true on the call.

Returns: {"write_enabled": bool, "env_var": str, "how_to_enable": str, "destructive_tools_need": "confirm=true"}

List Trimble Connect regional servers (North America, Europe, Asia...).

Returns: {"count": int, "regions": [{"location": str, "origin": str}]} — 'origin' is the regional API base URL. Projects live in exactly one region; other tools resolve the region automatically from project_id.

List all Trimble Connect projects the signed-in user can access.

Queries every region and merges the results. Use this to find a project's ID before calling folder/file tools.

Args: name_filter: Optional case-insensitive substring to filter by name. refresh: Re-discover regions before listing (default False).

Returns: {"count": int, "projects": [{"id","name","rootId","region", "access","createdOn","modifiedOn",...}]}

Get full details of one project (raw API object).

Args: project_id: Project ID from tc_list_projects.

Returns the complete project JSON including rootId (root folder), license info, counts and settings.

List members (users) of a project with their role and status.

Args: project_id: Project ID from tc_list_projects. include_removed: Also list users with status REMOVED (default False). group_id: Optional — only members of this group (see tc_list_groups).

Returns: {"count": int, "members": [{"id","email","name","role" ("ADMIN"|"USER"),"status" ("ACTIVE"|"PENDING"|"REMOVED")}]}. Member ids are what folder-permission tools expect as subject ids.

List the contents (subfolders and files) of one folder.

Args: project_id: Project ID (used to resolve the correct region). folder_id: Folder ID to list. Omit to list the project's ROOT folder.

Returns: {"folder_id": str, "count": int, "items": [{"id","name", "type" ("FOLDER"|"FILE"),"size","revision","versionId","modifiedOn", "modifiedBy",...}]}. Use item ids to descend into subfolders or fetch file details.

Render a compact text tree of the project's folder structure.

Recursively walks folders breadth-limited by max_depth and max_entries — ideal for a quick overview of a CDE structure before drilling in.

Args: project_id: Project ID. folder_id: Start folder (default: project root). max_depth: Levels to descend, 1-6 (default 3). max_entries: Hard cap on total lines to keep output small (default 400).

Returns: Markdown-ish text tree. Folders show their ID so you can call tc_list_folder / tc_folder_tree on a subtree; files show size and last modified date. A trailing note reports truncation, if any.

Get metadata of a file (latest version): name, size, revision, dates.

Args: project_id: Project the file belongs to (resolves the region). file_id: File ID (from tc_list_folder).

Returns the raw file JSON from the API.

List the version history of a file.

Args: project_id: Project the file belongs to. file_id: File ID.

Returns: {"count": int, "versions": [...]} with versionId, revision, size, createdOn/modifiedOn and author per version (fields as provided by the API).

Download a file from Trimble Connect to the local disk.

Read-only on the Trimble side; writes only to the local download folder.

Args: project_id: Project the file belongs to. file_id: File ID (from tc_list_folder). version_id: Optional specific version (from tc_list_file_versions); default latest. file_name: Optional name for the saved file; defaults to the file's name from metadata. save_dir: Optional target directory; default TC_DOWNLOAD_DIR (~/Downloads/TrimbleConnect).

Returns: {"saved_to": str, "size_bytes": int}

Search Trimble Connect for files, folders, todos etc. by text.

Args: query: Search text (e.g. a file name or keyword). project_id: Optional — limit the search to one project (faster, searches only that project's region). Omit to search all regions.

Returns: {"count": int, "results": [...]} (raw search results from the API, per region).

Advanced escape hatch: perform a raw GET on the Trimble Connect Core API (v2) and return the raw JSON.

Use when no dedicated tool covers an endpoint (e.g. 'todos?projectId=X', 'views', 'releases', 'projects/{id}/activities'). Read-only — for writes use the dedicated tools, or tc_api_write.

Args: path: Path relative to the API base, e.g. 'projects/{id}/activities' or 'todos'. Must not include a scheme/host. project_id: Optional — route the call to this project's region. Omit to call the master (North America) server. params: Optional query parameters as a flat string dict.

Returns raw JSON (paginated list endpoints are fetched fully up to a safety cap).

Create ONE new folder inside a parent folder.

Requires TC_ENABLE_WRITE=1 (see tc_write_status).

Args: project_id: Project ID (resolves the region). name: New folder name (max 255 chars, must be unique in the parent). parent_folder_id: Parent folder; omit to create under the project ROOT folder.

Returns: {"created": true, "id", "name", "parentId", "path"}. For a whole CDE tree use tc_create_folder_structure instead.

Create a whole folder tree in one call (e.g. an ISO 19650 CDE).

Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. paths: Folder paths relative to the start folder, '/' separated, e.g. ["01-WIP/01-ARC", "01-WIP/02-STR", "02-SHARED", "03-PUBLISHED"]. Intermediate levels are created automatically, so listing only the leaves is enough. parent_folder_id: Start folder; omit for the project ROOT. skip_existing: Reuse a folder that already exists instead of failing (default True) — makes the call safe to re-run.

Returns: {"created": [{"path","id"}], "existing": [{"path","id"}], "errors": [{"path","error"}], "root_folder_id": str}

Rename a folder or a file.

Requires TC_ENABLE_WRITE=1. Renaming and moving must be separate calls — the API ignores the new name if a new parent is sent at the same time.

Args: project_id: Project ID. item_id: Folder or file ID. new_name: New name. item_type: "FOLDER" (default) or "FILE".

Returns: {"renamed": true, "id", "name", ...}

Move a folder or file into another folder.

Requires TC_ENABLE_WRITE=1. Moving a folder moves its whole subtree, and permissions may change through inheritance in the new location.

Args: project_id: Project ID. item_id: Folder or file ID to move. new_parent_folder_id: Destination folder ID. item_type: "FOLDER" (default) or "FILE".

Returns: {"moved": true, "id", "name", "parentId", ...}

Copy one file into another folder (server-side copy).

Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID (source and target must be the same project). file_id: Source file ID. target_folder_id: Destination folder ID. version_id: Optional specific version to copy; default = latest. copy_metadata: Also copy the file's metadata/attributes. merge_existing: If a file with the same name exists in the target, add the copy as a NEW REVISION of it instead of failing. Cannot be combined with copy_metadata.

Returns the new file object with {"copied": true}.

Copy a folder and everything inside it to another location.

Trimble Connect has no server-side folder-copy endpoint, so this walks the tree and recreates folders + copies files one by one. Slow for large trees — max_items caps the work. Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. folder_id: Folder to copy. target_parent_folder_id: Folder that will contain the copy. new_name: Name for the copy (default: same name as the source). max_items: Safety cap on folders+files processed (default 300).

Returns: {"copied": true, "new_folder_id", "folders_created", "files_copied", "errors": [...], "truncated": bool}

Delete a folder or a file. DESTRUCTIVE — there is no undo via the API.

Trimble Connect deletes are soft (an admin can restore from the web UI), but this API offers NO restore endpoint. Requires TC_ENABLE_WRITE=1 AND confirm=true. Always show the user what will be deleted first.

Args: project_id: Project ID. item_id: Folder or file ID. confirm: Must be true — safety gate. item_type: "FOLDER" (default) or "FILE". force: Required to delete a folder that is NOT empty (deletes the whole subtree, runs as a background job).

Returns: {"deleted": true, ...} or an error explaining what is missing.

Upload a NEW file from the local disk into a Trimble Connect folder.

Fails if a file with the same name already exists in that folder — use tc_upload_new_version to add a revision instead. Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. folder_id: Destination folder ID (tc_list_folder / tc_folder_tree). local_path: Full path of the file on this computer. name: Optional name to use in Trimble Connect (default: file name).

Returns: {"uploaded": true, "file_id", "version_id", "revision", "name", "size_bytes"}

Upload a file as a NEW VERSION of an existing file in that folder.

The existing file keeps its history; the uploaded content becomes the latest revision that everyone will see. Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. folder_id: Folder that already contains the file. local_path: Full path of the new content on this computer. name: Name of the existing file in Trimble Connect (default: the local file name) — it must match exactly, otherwise a new file is created instead. confirm: Must be true — safety gate.

Returns: {"uploaded": true, "file_id", "version_id", "revision", ...}

Read the access control list (ACL) of a folder or file.

Args: project_id: Project ID. item_id: Folder or file ID. item_type: "FOLDER" (default) or "FILE".

Returns: {"acl": {"READ": [ids], "FULL_ACCESS": [ids], "NO_ACCESS": [ids]}, "inheritance": bool, ...}. Ids are project user ids (tc_list_project_members) or group ids (tc_list_groups); the special id "tc-groups:*" means all project members. Files support only READ and FULL_ACCESS.

Give users/groups a permission level on a folder or file (safe merge).

Reads the current ACL, moves the given subjects to the requested level, and writes the whole ACL back — everyone else keeps what they had. Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. item_id: Folder or file ID. subject_ids: User ids (tc_list_project_members) and/or group ids (tc_list_groups). Use "tc-groups:*" for all project members. level: "READ", "FULL_ACCESS", or "NO_ACCESS" (folders only). item_type: "FOLDER" (default) or "FILE". inheritance: Optional — set True/False to also change whether the folder inherits permissions from its parent.

Returns: {"updated": true, "acl": {...}, "inheritance": bool}

Remove users/groups from a folder's or file's ACL entirely.

They fall back to whatever the parent folder / project grants them. To actively BLOCK someone instead, use tc_grant_permissions with level="NO_ACCESS". Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. item_id: Folder or file ID. subject_ids: User/group ids to drop from the ACL. confirm: Must be true — safety gate. item_type: "FOLDER" (default) or "FILE".

Returns: {"updated": true, "acl": {...}, "removed": [ids]}

REPLACE the whole ACL of a folder or file (advanced).

Everything not listed in acl loses its explicit permission. Prefer tc_grant_permissions / tc_remove_permissions, which merge safely. Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. item_id: Folder or file ID. acl: {"READ": [ids], "FULL_ACCESS": [ids], "NO_ACCESS": [ids]} — levels may be omitted. "tc-groups:*" = all project members. confirm: Must be true — safety gate. item_type: "FOLDER" (default) or "FILE". inheritance: Optional — whether the folder inherits from its parent.

Returns: {"updated": true, "acl": {...}, "previous_acl": {...}}

List the roles available in a project (typically ADMIN and USER).

Args: project_id: Project ID.

Returns: {"roles": [str]}

Invite a user to a project by email.

Requires TC_ENABLE_WRITE=1. The invitee gets status PENDING until they open the project.

Args: project_id: Project ID. email: Email address to invite. role: "USER" (default) or "ADMIN" — check tc_list_project_roles. notify: Send the invitation email (default True).

Returns the created member object with {"invited": true}.

Change a project member's role (e.g. USER → ADMIN).

Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. user_id: Member id from tc_list_project_members (not the email). role: "ADMIN" or "USER".

Returns the updated member object with {"updated": true}.

Remove a member from a project. DESTRUCTIVE — they lose all access.

Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. user_id: Member id from tc_list_project_members. confirm: Must be true — safety gate.

Returns: {"removed": true, "user_id": str}

List the user groups of a project.

Groups are the practical way to grant folder permissions to a whole discipline or company at once.

Args: project_id: Project ID.

Returns: {"count": int, "groups": [{"id","name","usersCount",...}]}

List the members of a project group.

Args: project_id: Project ID (resolves the region). group_id: Group ID from tc_list_groups.

Returns: {"count": int, "users": [{"id","email","name","status"}]}

Create a user group in a project.

Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. name: Group name (e.g. "Architects", "Contractor - Site").

Returns the created group with {"created": true}.

Rename a project group.

Requires TC_ENABLE_WRITE=1.

Args: project_id: Project ID. group_id: Group ID. new_name: New group name.

Returns the updated group with {"renamed": true}.

Delete a project group. DESTRUCTIVE — any folder permission granted to this group disappears with it.

Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. group_id: Group ID. confirm: Must be true — safety gate.

Returns: {"deleted": true, "group_id": str}

Add project members to a group.

Requires TC_ENABLE_WRITE=1. Users must already be project members (invite them first with tc_add_project_user).

Args: project_id: Project ID. group_id: Group ID. user_ids: Member ids from tc_list_project_members.

Returns: {"added": [ids], "count": int}

Remove members from a group (they stay in the project).

Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: project_id: Project ID. group_id: Group ID. user_ids: Member ids to remove. confirm: Must be true — safety gate.

Returns: {"removed": [ids], "count": int}

Advanced escape hatch: raw POST/PATCH/PUT/DELETE on the Core API (v2).

Only for endpoints with no dedicated tool (todos, views, releases, attributes...). Requires TC_ENABLE_WRITE=1 AND confirm=true.

Args: method: "POST", "PATCH", "PUT" or "DELETE". path: Path relative to the API base, e.g. 'todos'. No scheme/host. confirm: Must be true — safety gate. project_id: Optional — route to this project's region (recommended; otherwise the master/North America server is used). params: Optional query parameters. body: Optional JSON body.

Returns the raw JSON response (or {"status": 204} for empty responses).