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

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0-beta.9](https://github.com/UteamUP/uteamup-mcp/compare/2.3.0-beta.9...2.4.0-beta.9) (2026-10-21)
+
+
+### Features
+
+* package OpenAI marketplace integration with UteamUP branding ([026ad6f](https://github.com/UteamUP/uteamup-mcp/commit/026ad6f207e007f0085aecc73162d3ded97dc9ad))
+
+
+### Bug Fixes
+
+* **auth:** bind the proxy's OAuth token to the MCP endpoint ([a5b0f4a](https://github.com/UteamUP/uteamup-mcp/commit/a5b0f4a116579098dc60f67861d14eb1d3fdbfd8))
+* avoid redundant Claude documentation asset review ([5818f0e](https://github.com/UteamUP/uteamup-mcp/commit/5818f0e86c93fed7b703f5775f3a053f83ed595f))
+* complete Claude listing links and data handling disclosures ([e3b2b78](https://github.com/UteamUP/uteamup-mcp/commit/e3b2b789def1f8067b0a1f35644d984a43572996))
+* correct Glama maintainer identity ([dc9f5a5](https://github.com/UteamUP/uteamup-mcp/commit/dc9f5a57ad01d5f3ca2736f5c9493e40cb195191))
+* correct Grok marketplace contact ([48cad67](https://github.com/UteamUP/uteamup-mcp/commit/48cad677694d10260501613f2bd2a61d807fcd23))
+* package Claude plugin with locked dependencies and explicit configuration ([92a2e40](https://github.com/UteamUP/uteamup-mcp/commit/92a2e405acf395553826e0c7b08913a9aed4b1a9))
+* prepare MCP manifests for marketplace validation ([1b555a6](https://github.com/UteamUP/uteamup-mcp/commit/1b555a66cd8ae9fe390cf127ce349499d2f3ded9))
+* update fast-copy to patched version ([0fd7cd8](https://github.com/UteamUP/uteamup-mcp/commit/0fd7cd8ece27446bbb5a118da5b981094d2010a9))
+* update release workflow conditions and add test for MCP registry publication ([44180fd](https://github.com/UteamUP/uteamup-mcp/commit/44180fd7f859340f6752dd1b07119d45df0703ad))
+* use UteamUP publisher contact for Claude submissions ([acd457f](https://github.com/UteamUP/uteamup-mcp/commit/acd457f7a2a114a77f2b55a63b2eaf7be019078d))
+
+
+### Documentation
+
+* correct Claude troubleshooting and read-only access guidance ([aba9dfe](https://github.com/UteamUP/uteamup-mcp/commit/aba9dfebbb98dd5dc877fc26eba9df201278d0df))
+* correct marketplace setup links and production connection guidance ([91c4945](https://github.com/UteamUP/uteamup-mcp/commit/91c4945f561f3c26da8dd3f0da5c4be7883cbe94))
+
+
+### Tests
+
+* cover floorplan scan draft tools ([f251595](https://github.com/UteamUP/uteamup-mcp/commit/f251595c54d35320e8ef9c3cd42f3139f831666f))
+* **model3d:** cover the 3D model and scene items MCP tools ([5ef7c9e](https://github.com/UteamUP/uteamup-mcp/commit/5ef7c9ec8ae58ec3d5e980b9b59d063935366eed))
+* **model3d:** cover the uteamup_model3d_catalogue_* tools ([2d7eb15](https://github.com/UteamUP/uteamup-mcp/commit/2d7eb153eb38430b6c5de7300b7cd9e3b14392d7))
+
+
+### CI/CD
+
+* publish @uteamup/mcp-server to npm on every release ([85cf397](https://github.com/UteamUP/uteamup-mcp/commit/85cf39706266f54aacdc3e8e5a9869b66080cbf8))
+
 ## [2.3.0-beta.9](https://github.com/UteamUP/uteamup-mcp/compare/2.2.0-beta.9...2.3.0-beta.9) (2026-10-19)
 
 

package/README.md

@@ -13,22 +13,21 @@
 ## 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 Grok, Grok Bot and ChatGPT
+### Read-only access for Claude, Grok, Grok Bot and ChatGPT
 
-Use the environment-specific HTTPS endpoint:
+Use the production 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.
@@ -42,6 +41,8 @@ Then each member connects their own assistant; no API key or secret is involved:
   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
@@ -75,11 +76,10 @@ 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)
@@ -87,9 +87,10 @@ and [Grok connectors](https://docs.x.ai/grok/connectors).
 - ✅ **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:**
 ```
@@ -147,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:
 
@@ -167,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
 
@@ -227,16 +217,14 @@ That's it! 🎉
 | `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
 
@@ -260,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
@@ -309,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
 
 ---
 
@@ -402,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
 
 ---
 
@@ -414,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
@@ -451,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",
@@ -465,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
@@ -550,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/index.js

@@ -280,14 +280,16 @@ async function requestNewAccessToken() {
 
     info('Authorization code received');
 
-    // Step 2: Exchange for access token with retry
+    // Step 2: Exchange for access token with retry. Naming the MCP endpoint as the resource
+    // (RFC 8707) gets a token the backend accepts only there, never on its REST API.
     const tokenData = new URLSearchParams({
       grant_type: 'authorization_code',
       code: authCode,
       redirect_uri: OAUTH_REDIRECT_URI,
       client_id: config.apiKey,
       client_secret: config.secret,
-      code_verifier: verifier
+      code_verifier: verifier,
+      resource: new URL(config.mcpPath, config.baseUrl).href
     }).toString();
 
     const tokenResponse = await retryWithBackoff(

package/openapi-actions.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "UteamUP CMMS Read-Only Assistant Actions",
     "description": "OpenAPI 3.1.0 Action schema for ChatGPT Custom GPTs (GPT Store) and Google Gemini / Vertex AI Extensions. Invokes the UteamUP read-only MCP endpoint (/mcp/read-only) to list and search assets and work orders using the caller's tenant-scoped permissions.",
-    "version": "2.3.0-beta.9",
+    "version": "2.4.0-beta.9",
     "x-logo": {
       "url": "https://raw.githubusercontent.com/UteamUP/uteamup-mcp/main/assets/logo.png",
       "altText": "UteamUP CMMS"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uteamup/mcp-server",
-  "version": "2.3.0-beta.9",
+  "version": "2.4.0-beta.9",
   "mcpName": "io.github.UteamUP/mcp-server",
   "description": "MCP server client for UteamUP - enables Claude Desktop/Code integration with automatic OAuth 2.0 authentication",
   "main": "index.js",
@@ -30,7 +30,7 @@
     "work-orders",
     "asset-management"
   ],
-  "author": "UteamUP <support@uteamup.com>",
+  "author": "UteamUP <gisli@uteamup.com>",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.UteamUP/mcp-server",
   "title": "UteamUP CMMS",
   "description": "Connect AI assistants to UteamUP CMMS for work orders, assets, maintenance, and inventory.",
-  "version": "2.3.0-beta.9",
+  "version": "2.4.0-beta.9",
   "websiteUrl": "https://uteamup.com",
   "icons": [
     {
@@ -30,7 +30,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@uteamup/mcp-server",
-      "version": "2.3.0-beta.9",
+      "version": "2.4.0-beta.9",
       "transport": {
         "type": "stdio"
       },