@uteamup/mcp-server 1.0.0-beta.9 → 2.3.0-beta.9

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="UteamUP Logo" width="88" />
+</p>
+
 # @uteamup/mcp-server
 
 > MCP server client for UteamUP - enables Claude Desktop/Code integration with automatic OAuth 2.0 authentication
@@ -17,6 +21,58 @@
 
 This package enables AI assistants like Claude Desktop and Claude Code to connect to your UteamUP CMMS system using the Model Context Protocol (MCP). It handles OAuth 2.0 authentication automatically, so you can manage work orders, assets, inventory, and more through natural conversation.
 
+### Read-only access for Grok, Grok Bot and ChatGPT
+
+Use the environment-specific HTTPS endpoint:
+
+| Environment | MCP server URL |
+|---|---|
+| Production | `https://api.uteamup.com/mcp/read-only` |
+| Development | `https://devback.uteamup.com/mcp/read-only` |
+
+**Sign in with your UteamUP account (recommended).** A tenant administrator (`Tenant.Update`)
+first turns on **Allow members to connect AI assistants** in the company's **API Keys** tab.
+Then each member connects their own assistant; no API key or secret is involved:
+
+- **Grok:** open [Connectors](https://grok.com/connectors), choose **New Connector → Custom**,
+  and enter the endpoint. Grok registers itself (RFC 7591), sends you to the UteamUP consent
+  page, and you pick the company and allow access. Business/Enterprise workspaces require
+  their administrator to provision the connector.
+- **Grok Bot:** add a **Custom MCP server, Remote HTTPS** with the endpoint on the Bot's
+  Setup → Plugins card; each teammate signs in the first time they use it.
+- **ChatGPT:** add a custom MCP server with the endpoint and choose OAuth; ChatGPT registers
+  itself and you approve on the same consent page.
+
+The assistant uses the member's own permissions in the chosen company, and only the read
+tools below. Access tokens last 60 minutes and refresh tokens rotate on every use. A member
+disconnects under **Profile → Accounts**; an administrator sees and revokes every link in the
+API Keys tab, or with the `uteamup_assistant_connection_list` /
+`uteamup_assistant_connection_revoke` MCP tools. Turning the company setting off stops all
+links immediately.
+
+**Tenant API key (service integrations).** The **API Keys → Set up UPMate Integration** wizard
+still offers the **Private read-only pilot for ChatGPT and Grok**: select an active role whose
+grants are exclusively `View`/`Read` and create a separate MCP-enabled key per assistant. In
+ChatGPT, configure OAuth with predefined client credentials (the API key as **Client ID**, its
+secret as **Client Secret**). Grok only supports sign-in, so use the option above for Grok.
+Tenant administrators retain the normal key quotas, expiration, IP restrictions, rate
+limits, rotation, and revocation controls.
+
+Only the existing asset list, asset search, asset-by-GUID, work-order list and work-order
+search tools are advertised. Current UPMate capability settings, role permissions and
+tenant scope are checked before discovery and invocation. Guessed write/admin tool calls
+are denied before execution. The read-only endpoint also rejects a key if its persisted
+role gains a write or wildcard permission, or if the key is revoked, expired or rotated.
+These reads do not invoke a UteamUP AI provider or spend UteamUP AI credits.
+
+The Node proxy can use the same endpoint with `UTEAMUP_MCP_PATH=/mcp/read-only`.
+Its default `/mcp` transport retains the existing behavior and role-based authorization.
+The CLI continues to use existing API-key creation, role selection and revocation commands;
+no separate credential store or tool implementation is required.
+
+References: [OpenAI custom MCP servers](https://developers.openai.com/api/docs/guides/custom-mcp-server)
+and [Grok connectors](https://docs.x.ai/grok/connectors).
+
 **Key Features:**
 - ✅ Automatic OAuth 2.0 + PKCE authentication
 - ✅ Token caching (7-day expiration, auto-refresh)
@@ -60,6 +116,22 @@ Or install globally:
 npm install -g @uteamup/mcp-server
 ```
 
+### Install via CLI Plugin Marketplaces
+
+- **Claude Code:**
+  ```bash
+  claude plugin marketplace add UteamUP/uteamup-mcp
+  claude plugin install uteamup@uteamup
+  ```
+- **Grok Build:**
+  ```bash
+  grok plugin install https://github.com/UteamUP/uteamup-mcp.git --trust
+  ```
+- **Gemini CLI:**
+  ```bash
+  gemini extensions install https://github.com/UteamUP/uteamup-mcp
+  ```
+
 ---
 
 ## Quick Start
@@ -150,11 +222,16 @@ That's it! 🎉
 | `UTEAMUP_DEBUG` | Legacy debug mode (`1` or `true`) | `false` |
 | `UTEAMUP_REQUEST_TIMEOUT` | Request timeout in milliseconds | `30000` |
 | `UTEAMUP_MAX_RETRIES` | Max retry attempts for network errors | `3` |
+| `UTEAMUP_MAX_REQUEST_BYTES` | Maximum bytes in one JSON-RPC request | `1048576` |
+| `UTEAMUP_MAX_RESPONSE_BYTES` | Maximum bytes buffered from one backend response | `10485760` |
 | `UTEAMUP_TOKEN_CACHE_DIR` | Persistent token cache directory | - |
 | `UTEAMUP_TOKEN_REFRESH_MARGIN` | Token refresh margin in seconds | `300` |
 
 ### API Base URLs
 
+The configured base URL must be a bare HTTPS origin. Credentials, paths, query
+parameters, fragments, and plain HTTP endpoints are rejected.
+
 | Environment | URL | When to Use |
 |-------------|-----|-------------|
 | **Production** | `https://api.uteamup.com` | Default - for normal use |

package/assets/logo.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" fill="none" role="img" aria-label="UteamUP">
+  <path d="M372.26,86.67 L372.26,188.95 L255.84,121.72 L255.84,32.00 C268.46,32.00 281.07,34.91 292.65,40.71 L292.66,40.72 Z" fill="#FAA61A"/>
+  <path d="M255.84,32.00 L255.84,121.72 L139.40,188.95 L139.40,86.67 L219.07,40.68 C230.63,34.90 243.23,32.00 255.84,32.00 Z" fill="#F37021"/>
+  <path d="M461.16,137.59 L460.82,279.69 L460.70,331.35 L460.70,331.37 L460.70,331.39 C459.99,344.51 456.15,357.07 449.74,368.13 C449.74,368.13 449.74,368.14 449.73,368.14 L372.25,323.40 L372.03,323.28 L372.26,188.95 L460.82,137.78 Z" fill="#184795"/>
+  <path d="M139.40,188.95 L139.40,323.39 L61.92,368.13 C54.78,355.81 50.84,341.64 50.84,326.91 L50.84,137.82 Z" fill="#198F45"/>
+  <path d="M449.74,368.13 C449.74,368.13 449.74,368.14 449.73,368.14 C442.64,380.36 432.40,390.77 419.74,398.07 L296.91,468.99 C284.20,476.32 270.02,480.00 255.84,480.00 L255.84,390.61 L372.25,323.40 L372.26,323.39 Z" fill="#28327A"/>
+  <path d="M255.84,390.61 L255.84,480.00 C241.64,480.00 227.46,476.32 214.75,468.98 L91.92,398.07 C79.25,390.76 69.02,380.36 61.92,368.13 L139.40,323.39 Z" fill="#176334"/>
+  <path d="M255.84,256.17 L255.84,390.61 L139.40,323.39 L139.40,188.95 Z" fill="#1BAE4B"/>
+  <path d="M372.26,188.95 L372.26,323.39 L255.84,390.61 L255.84,256.16 Z" fill="#1A6CB5"/>
+  <path d="M372.26,188.95 L255.84,256.16 L255.84,256.17 L139.40,188.95 L255.84,121.72 Z" fill="#F9ED24"/>
+</svg>