@uteamup/mcp-server 1.0.0-beta.9 → 2.4.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
@@ -9,21 +13,73 @@
 ## Links
 
 - **📦 [npm Package](https://www.npmjs.com/package/@uteamup/mcp-server)** - Install with `npx -y @uteamup/mcp-server`
-- **📖 [Documentation](https://docs.uteamup.com/mcp)** - Full MCP integration guide
-- **🐛 [Issues](https://github.com/uteamup/mcp-server/issues)** - Report bugs and request features
-- **💬 [Support](mailto:support@uteamup.com)** - Get help
+- **📖 [Documentation](https://github.com/UteamUP/uteamup-mcp#readme)** - Full MCP integration guide
+- **🐛 [Issues](https://github.com/UteamUP/uteamup-mcp/issues)** - Report bugs and request features
+- **💬 [Support](mailto:gisli@uteamup.com)** - Get help
 
 ## What is this?
 
 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 Claude, Grok, Grok Bot and ChatGPT
+
+Use the production HTTPS endpoint:
+
+| Environment | MCP server URL |
+|---|---|
+| Production | `https://api.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.
+- **Claude:** add a custom connector with the endpoint, choose **Sign in now** and
+  **Register automatically**, then approve on the UteamUP 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)
+- ✅ Token caching with automatic refresh
 - ✅ Works with Claude Desktop, Claude Code, and any MCP-compatible client
 - ✅ Zero configuration - just provide API credentials
 - ✅ Comprehensive error messages
-- ✅ Development mode support (self-signed certificates)
 - ✅ Server-Sent Events (SSE) response parsing
 - ✅ Proper JSON-RPC 2.0 notification handling
 - ✅ **NEW:** Structured logging with Pino (JSON/text formats)
@@ -31,9 +87,10 @@ This package enables AI assistants like Claude Desktop and Claude Code to connec
 - ✅ **NEW:** Performance monitoring and metrics
 - ✅ **NEW:** Retry logic with exponential backoff
 - ✅ **NEW:** CLI utilities (--help, --version, --validate-config, --test-auth)
-- ✅ **NEW:** Comprehensive test suite (70 tests)
+- ✅ Comprehensive test suite
 
-**Current Status:** `v1.0.0-beta.7` - Production-ready with enhanced debugging! See [CHANGELOG.md](CHANGELOG.md) for details.
+**Release status:** Beta. The npm badge above shows the published version;
+see [CHANGELOG.md](CHANGELOG.md) for release details.
 
 **Example Conversation:**
 ```
@@ -60,6 +117,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
@@ -75,8 +148,11 @@ npm install -g @uteamup/mcp-server
 
 ### 2. Configure Claude Desktop
 
-**macOS/Linux:** Edit `~/.config/claude/mcp.json`
-**Windows:** Edit `%APPDATA%\Claude\mcp.json`
+In Claude Desktop, open **Settings → Developer → Edit Config**.
+The configuration file is located at:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 Add this configuration:
 
@@ -95,22 +171,8 @@ Add this configuration:
 }
 ```
 
-**Optional:** For development/testing against a local backend:
-```json
-{
-  "mcpServers": {
-    "uteamup-dev": {
-      "command": "npx",
-      "args": ["-y", "@uteamup/mcp-server"],
-      "env": {
-        "UTEAMUP_API_KEY": "your-api-key",
-        "UTEAMUP_SECRET": "your-secret",
-        "UTEAMUP_API_BASE_URL": "https://devback.uteamup.com"
-      }
-    }
-  }
-}
-```
+All UteamUP MCP connections use `https://api.uteamup.com`. Use a restricted key
+from a demo workspace when validating an integration.
 
 ### 3. Restart Claude Desktop
 
@@ -150,16 +212,19 @@ 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
+### API Base URL
+
+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 |
-| **Development** | `https://devback.uteamup.com` | Testing against dev backend |
-| **Local** | `https://localhost:5002` | Local development with self-signed cert |
+Always use `https://api.uteamup.com`, including when running the Node proxy
+locally. The full MCP endpoint is `/mcp`; the read-only endpoint is
+`/mcp/read-only`.
 
 ### Permissions
 
@@ -183,7 +248,7 @@ Your AI assistant's permissions are controlled by the **role assigned to your AP
 **Cause:** `UTEAMUP_API_KEY` or `UTEAMUP_SECRET` not set in MCP configuration.
 
 **Solution:**
-1. Check your MCP configuration file (`~/.config/claude/mcp.json` or `%APPDATA%\Claude\mcp.json`)
+1. Check your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows)
 2. Verify the `env` section includes both `UTEAMUP_API_KEY` and `UTEAMUP_SECRET`
 3. Ensure there are no typos in the environment variable names
 4. Restart Claude Desktop after making changes
@@ -232,36 +297,32 @@ Your AI assistant's permissions are controlled by the **role assigned to your AP
 1. **Check your internet connection**
 2. **Verify the base URL:**
    - Production: `https://api.uteamup.com` (default, no env var needed)
-   - Development: Set `UTEAMUP_API_BASE_URL=https://devback.uteamup.com`
 3. **Check if UteamUP is down:**
-   - Contact support@uteamup.com
-4. **For local development:**
-   - Ensure backend is running: `cd UteamUP_Backend/UteamUP_API && make watch`
-   - Use `UTEAMUP_API_BASE_URL=https://localhost:5002`
+   - Contact gisli@uteamup.com
 
 ---
 
 #### "UNABLE_TO_VERIFY_LEAF_SIGNATURE" or certificate errors
 
-**Cause:** Self-signed certificate (development mode).
+**Cause:** The connection cannot validate the server's TLS certificate.
 
-**Solution:** This package automatically accepts self-signed certificates for development. If you're seeing this error:
-1. Verify `UTEAMUP_API_BASE_URL` is set correctly
-2. If using local backend, ensure it's running on HTTPS
-3. For production, this should never happen - contact support
+**Solution:**
+1. Verify the API base URL is `https://api.uteamup.com`
+2. Check the device's date and trusted certificate configuration
+3. Contact gisli@uteamup.com if the certificate error persists
 
 ---
 
 #### Tools list is empty or incomplete
 
-**Cause:** API key role has limited permissions.
+**Cause:** The credential, role, or company configuration does not grant the requested tools.
 
 **Solution:**
 1. Go to **Tenant Settings** → **API Keys** in UteamUP
-2. Edit your API key
-3. Change the role to one with more permissions (e.g., Admin or Supervisor)
-4. Available tools depend on your role's permissions
-5. Changes take effect immediately
+2. Confirm the key is active and MCP-enabled for the intended company
+3. Ask a company administrator to check the specific read permissions needed for your workflow
+4. For the remote read-only connector, use a restricted read-only role; write or wildcard grants are not eligible
+5. Reconnect the client to refresh its tool list after an authorized permission change
 
 ---
 
@@ -325,9 +386,9 @@ Enable different log levels and formats:
    ```
 
 4. **Get help:**
-   - Email: support@uteamup.com
-   - Documentation: https://docs.uteamup.com/mcp
-   - GitHub Issues: https://github.com/uteamup/mcp-server/issues
+   - Email: gisli@uteamup.com
+   - Documentation: https://github.com/UteamUP/uteamup-mcp#readme
+   - GitHub Issues: https://github.com/UteamUP/uteamup-mcp/issues
 
 ---
 
@@ -337,20 +398,20 @@ Enable different log levels and formats:
 
 ```bash
 # Clone the repository
-git clone https://github.com/UteamUP/uteamup-mcp-proxy.git
-cd uteamup-mcp-proxy
+git clone https://github.com/UteamUP/uteamup-mcp.git
+cd uteamup-mcp
 
 # Install dependencies
 npm install
 
-# Run tests
-npm test
+# Run tests only at the final whole-goal gate (see MCPGuidelines.md)
+UTEAMUP_FINAL_GOAL_GATE=1 npm test
 
 # Test with debug logging
 export UTEAMUP_LOG_LEVEL=DEBUG
-export UTEAMUP_API_KEY="your-dev-key"
-export UTEAMUP_SECRET="your-dev-secret"
-export UTEAMUP_API_BASE_URL="https://localhost:5002"
+export UTEAMUP_API_KEY="your-demo-workspace-key"
+export UTEAMUP_SECRET="your-demo-workspace-secret"
+export UTEAMUP_API_BASE_URL="https://api.uteamup.com"
 node index.js
 
 # CLI Utilities
@@ -374,7 +435,7 @@ npm link
   "mcpServers": {
     "uteamup-local": {
       "command": "node",
-      "args": ["/absolute/path/to/uteamup-mcp-proxy/index.js"],
+      "args": ["/absolute/path/to/uteamup-mcp/index.js"],
       "env": {
         "UTEAMUP_API_KEY": "your-key",
         "UTEAMUP_SECRET": "your-secret",
@@ -388,7 +449,7 @@ npm link
 ### Project Structure
 
 ```
-uteamup-mcp-proxy/
+uteamup-mcp/
 ├── index.js           # Main entry point (OAuth + MCP client)
 ├── package.json       # Package metadata
 ├── README.md          # This file
@@ -473,9 +534,9 @@ See [LICENSE](LICENSE) for details.
 
 ## Support
 
-- **Documentation:** https://docs.uteamup.com/mcp
-- **Email:** support@uteamup.com
-- **Issues:** https://github.com/uteamup/mcp-server/issues
+- **Documentation:** https://github.com/UteamUP/uteamup-mcp#readme
+- **Email:** gisli@uteamup.com
+- **Issues:** https://github.com/UteamUP/uteamup-mcp/issues
 
 ---
 

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>