feat: Add administrative tools for user, group, content, and site management

docs/docs/configuration/mcp-config/tool-scoping.md

@@ -4,10 +4,44 @@ sidebar_position: 6
 
 # Tool Scoping
 
-The Tableau MCP server can be configured to limit the scope of its tools to a set of data sources,
-workbooks, projects, or tags.
+The Tableau MCP server can be configured to limit both which tools are available and the scope of data those tools can access.
 
-Enabling tool scoping can cause:
+## Tool Filtering
+
+You can control which tools are available using the `INCLUDE_TOOLS` and `EXCLUDE_TOOLS` environment variables. These variables accept either individual tool names or tool group names.
+
+### `INCLUDE_TOOLS`
+
+A comma-separated list of tool names or tool group names to include. When set, only the specified tools will be available.
+
+**Tool Groups:**
+- `datasource` - Data source tools (list-datasources, get-datasource-metadata, query-datasource)
+- `workbook` - Workbook tools (list-workbooks, get-workbook)
+- `view` - View tools (list-views, get-view-data, get-view-image)
+- `pulse` - Pulse/metrics tools
+- `content-exploration` - Content search tools
+- `token-management` - Token management tools
+- `admin` - Admin tools for users and groups (admin-users, admin-groups)
+- `content` - Content management tools (content-projects, content-workbooks, content-views)
+- `operations` - Operational tools (content-permissions, site-jobs, tableau-operations)
+
+Example: `INCLUDE_TOOLS=datasource,workbook,admin` (enables all datasource, workbook, and admin tools)
+
+### `EXCLUDE_TOOLS`
+
+A comma-separated list of tool names or tool group names to exclude. When set, all tools except the specified ones will be available.
+
+Example: `EXCLUDE_TOOLS=pulse,operations` (disables all pulse and operations tools)
+
+:::warning
+You cannot use both `INCLUDE_TOOLS` and `EXCLUDE_TOOLS` simultaneously. The server will throw an error if both are specified.
+:::
+
+## Content Scoping
+
+The Tableau MCP server can also be configured to limit the scope of content accessed by tools to a set of data sources, workbooks, projects, or tags.
+
+Enabling content scoping can cause:
 
 1. Tools to return an error if they are called with arguments that are not within the allowed scope.
 2. Tools to respond with results that have been filtered to only include content from the allowed

docs/docs/tools/admin/admin-groups.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# admin-groups
+
+Administrative tool for managing Tableau groups, group sets, and group memberships.
+
+## Operations
+
+### Group Management
+
+- `create-group` - Create a new group
+- `delete-group` - Delete a group
+- `update-group` - Update group properties
+- `query-groups` - List groups with filtering and pagination
+- `get-group` - Get details of a specific group
+
+### Group Membership
+
+- `add-user-to-group` - Add a user to a group
+- `remove-user-from-group` - Remove a user from a group
+- `get-users-in-group` - List users in a group
+
+### Group Sets
+
+- `create-group-set` - Create a new group set
+- `update-group-set` - Update a group set
+- `delete-group-set` - Delete a group set
+- `add-group-to-group-set` - Add a group to a group set
+- `remove-group-from-group-set` - Remove a group from a group set
+
+## Parameters
+
+- `operation` (required) - The operation to perform
+- `groupId` - Group LUID
+- `userId` - User LUID (for membership operations)
+- `groupSetId` - Group set LUID
+- `pageSize` - Results per page
+- `pageNumber` - Page number
+- `filter` - Filter expression
+- `sort` - Sort expression
+- `body` - Request body
+
+## Required Scopes
+
+- **MCP Scope**: `tableau:mcp:admin:groups`
+- **API Scopes** (operation-dependent):
+  - `tableau:groups:read` - Query operations
+  - `tableau:groups:create` - Create operations
+  - `tableau:groups:update` - Update operations  
+  - `tableau:groups:delete` - Delete operations
+  - `tableau:users:read` - Get users in group
+
+## Example Usage
+
+```typescript
+// List all groups
+{
+  operation: "query-groups",
+  pageSize: 50
+}
+
+// Add user to group
+{
+  operation: "add-user-to-group",
+  groupId: "group-luid",
+  userId: "user-luid"
+}
+```

docs/docs/tools/admin/admin-tools-overview.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+---
+
+# Admin Tools Overview
+
+The Tableau MCP server provides a comprehensive set of administrative tools for managing users, groups, content, permissions, and site operations. These tools are designed for Tableau administrators who need programmatic access to administrative functions.
+
+## Tool Categories
+
+### User & Group Administration
+
+- **[admin-users](./admin-users.md)** - Manage Tableau users including creation, updates, deletion, and OAuth credential management
+- **[admin-groups](./admin-groups.md)** - Manage groups, group sets, and group memberships
+
+### Content Management
+
+- **[content-projects](./content-projects.md)** - Create, update, delete, and query projects
+- **[content-workbooks](./content-workbooks.md)** - Advanced workbook operations including querying, updating, deleting, and downloading
+- **[content-views](./content-views.md)** - Query views and export data in multiple formats (CSV, image, PDF, Excel)
+
+### Permissions & Access Control
+
+- **[content-permissions](./content-permissions.md)** - Manage granular and default permissions for content
+
+### Operations & Monitoring
+
+- **[site-jobs](./site-jobs.md)** - Query and manage background jobs on the site
+- **[tableau-operations](./tableau-operations.md)** - Advanced operational tools including job conflict detection, effective permissions analysis, and workbook archiving
+
+## Required Scopes
+
+Admin tools require specific OAuth scopes depending on the operations performed. Common scopes include:
+
+- `tableau:mcp:admin:users` - User administration
+- `tableau:mcp:admin:groups` - Group administration
+- `tableau:mcp:admin:permissions` - Permission management
+- `tableau:mcp:admin:jobs` - Job monitoring
+- `tableau:mcp:admin:operations` - Advanced operations
+
+Refer to individual tool documentation for specific scope requirements.
+
+## Tool Filtering
+
+You can control access to admin tools using the `INCLUDE_TOOLS` or `EXCLUDE_TOOLS` environment variables with tool group names:
+
+```bash
+# Enable only admin and content tools
+INCLUDE_TOOLS=admin,content
+
+# Disable operations tools
+EXCLUDE_TOOLS=operations
+```
+
+See [Tool Scoping](../../configuration/mcp-config/tool-scoping.md) for more information.

docs/docs/tools/admin/admin-users.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 2
+---
+
+# admin-users
+
+Administrative tool for managing Tableau users, exposing non-SCIM user methods from the Tableau REST API.
+
+## Operations
+
+### User Lifecycle
+
+- `add-user-to-site` - Add a new user to the site
+- `remove-user-from-site` - Remove a user from the site  
+- `update-user` - Update user properties
+- `query-user-on-site` - Query a specific user by ID
+- `get-users-on-site` - List all users on the site with optional filtering, sorting, and pagination
+- `get-groups-for-user` - Get groups that a user belongs to
+
+### Bulk Operations
+
+- `import-users-to-site-from-csv` - Import multiple users from CSV
+- `delete-users-from-site-with-csv` - Bulk delete users using CSV
+
+### OAuth Credentials
+
+- `upload-user-credentials` - Upload OAuth credentials for a user
+- `download-user-credentials` - Download OAuth credentials for a user
+
+## Parameters
+
+- `operation` (required) - The operation to perform
+- `userId` - User LUID (required for user-specific operations)
+- `pageSize` - Number of results per page
+- `pageNumber` - Page number for pagination
+- `filter` - Tableau REST API filter syntax
+- `sort` - Sort expression
+- `fields` - Field selection
+- `body` - Request body for create/update operations
+
+## Required Scopes
+
+- **MCP Scope**: `tableau:mcp:admin:users`
+- **API Scopes** (operation-dependent):
+  - `tableau:users:read` - Query operations
+  - `tableau:users:create` - Add/import operations
+  - `tableau:users:update` - Update operations
+  - `tableau:users:delete` - Delete/remove operations
+  - `tableau:oauth_credentials:upload` - Upload credentials
+  - `tableau:oauth_credentials:download` - Download credentials
+
+## Example Usage
+
+```typescript
+// Get all users on the site
+{
+  operation: "get-users-on-site",
+  pageSize: 100
+}
+
+// Query a specific user
+{
+  operation: "query-user-on-site",
+  userId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+}
+
+// Add a new user
+{
+  operation: "add-user-to-site",
+  body: {
+    user: {
+      name: "john.doe@example.com",
+      siteRole: "Viewer"
+    }
+  }
+}
+```
+
+## References
+
+- [Tableau REST API - Users and Groups](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm)

docs/docs/tools/admin/tableau-operations.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 7
+---
+
+# tableau-operations
+
+Higher-level administrative operations for Tableau Cloud including job conflict detection, permissions analysis, and workbook archiving.
+
+## Operations
+
+### Job Management
+
+- `get-background-job-conflicts` - Detect overlapping background jobs that may be competing for resources
+- `get-job-performance-stats` - Get performance statistics for running jobs
+- `kill-job-by-priority` - Cancel jobs based on priority with dry-run support
+
+### Permissions & Access
+
+- `get-effective-permissions` - Calculate effective read permissions for a specific user and workbook (heuristic analysis)
+- `trace-access-reason` - Trace why a user has access to specific content
+- `list-content-overrides` - List content with explicit permission overrides at the project level
+
+### Content Management
+
+- `get-stale-content-report` - Identify workbooks that haven't been accessed in a specified number of days
+- `get-workbook-lineage-impact` - Analyze workbook lineage and impact using Tableau Metadata GraphQL API
+- `archive-workbook` - Archive a workbook to S3 (if configured) or return as base64
+
+## Parameters
+
+- `operation` (required) - The operation to perform
+- `workbookId` - Workbook LUID
+- `userId` - User LUID  
+- `projectFilter` - Filter for workbooks by project
+- `staleDays` - Days of inactivity threshold (default from `TABLEAU_OPS_STALE_DAYS`)
+- `runningThresholdMinutes` - Job runtime threshold (default from `TABLEAU_OPS_RUNNING_THRESHOLD_MINUTES`)
+- `minPriority` - Minimum priority for job cancellation
+- `overlapWindowMs` - Time window for detecting job overlaps (default from `TABLEAU_OPS_OVERLAP_WINDOW_MS`)
+- `dryRun` - Preview actions without executing (for kill-job-by-priority)
+- `maxCancels` - Maximum number of jobs to cancel
+- `maxBase64Bytes` - Maximum size for base64 encoding
+
+## Environment Variables
+
+### S3 Archive Configuration
+
+- `TABLEAU_ARCHIVE_S3_BUCKET` - S3 bucket name for workbook archiving
+- `TABLEAU_ARCHIVE_S3_REGION` - AWS region
+- `TABLEAU_ARCHIVE_S3_KEY_PREFIX` - S3 key prefix
+
+### Operation Defaults
+
+- `TABLEAU_OPS_RUNNING_THRESHOLD_MINUTES` - Default threshold for flagging long-running jobs
+- `TABLEAU_OPS_STALE_DAYS` - Default days of inactivity for stale content  
+- `TABLEAU_OPS_OVERLAP_WINDOW_MS` - Default time window for detecting job conflicts
+
+## Required Scopes
+
+- **MCP Scope**: `tableau:mcp:admin:operations`
+- **API Scopes** (operation-dependent):
+  - `tableau:jobs:read`, `tableau:jobs:update` - Job operations
+  - `tableau:permissions:read`, `tableau:users:read`, `tableau:groups:read` - Permission analysis
+  - `tableau:content:read` - Content operations
+  - `tableau:views:download` - Workbook archiving
+
+## Example Usage
+
+```typescript
+// Detect job conflicts
+{
+  operation: "get-background-job-conflicts",
+  overlapWindowMs: 60000
+}
+
+// Get effective permissions
+{
+  operation: "get-effective-permissions",
+  userId: "user-luid",
+  workbookId: "workbook-luid"
+}
+
+// Archive workbook to S3
+{
+  operation: "archive-workbook",
+  workbookId: "workbook-luid"
+}
+```
+
+## Notes
+
+- `get-effective-permissions` provides a heuristic analysis for a single user/workbook pair, not a comprehensive site-wide viewer list
+- For complete ACL information, use the `content-permissions` tool with `list-granular-permissions`
+- Workbook archiving requires S3 environment variables to be configured; otherwise returns base64 for small workbooks