uteamup-mcp

<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

[![npm version](https://img.shields.io/npm/v/@uteamup/mcp-server.svg)](https://www.npmjs.com/package/@uteamup/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

## 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

## 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

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)
- ✅ 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)
- ✅ **NEW:** Configuration validation with Zod
- ✅ **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)

**Current Status:** `v1.0.0-beta.7` - Production-ready with enhanced debugging! See [CHANGELOG.md](CHANGELOG.md) for details.

**Example Conversation:**
```
You: Show me all high-priority work orders in Building A
AI: I found 5 high-priority work orders in Building A...

You: Assign them all to John Doe
AI: Done! All 5 work orders are now assigned to John Doe.
```

---

## Installation

No installation needed! Use `npx` to run directly:

```bash
npx -y @uteamup/mcp-server
```

Or install globally:

```bash
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

### 1. Get Your API Credentials

1. Log in to [UteamUP](https://app.uteamup.com)
2. Go to **Tenant Settings** → **API Keys**
3. Click **"Set up AI Integration"** or **"Create API Key"**
4. Enable **"MCP Enabled"** toggle
5. Click **Create API Key**
6. **Copy and save** your API Key and Secret (you won't see them again!)

### 2. Configure Claude Desktop

**macOS/Linux:** Edit `~/.config/claude/mcp.json`
**Windows:** Edit `%APPDATA%\Claude\mcp.json`

Add this configuration:

```json
{
  "mcpServers": {
    "uteamup": {
      "command": "npx",
      "args": ["-y", "@uteamup/mcp-server"],
      "env": {
        "UTEAMUP_API_KEY": "your-32-character-api-key",
        "UTEAMUP_SECRET": "your-64-character-secret"
      }
    }
  }
}
```

**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"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop. The UteamUP tools will be available automatically.

### 4. Test the Connection

In Claude, try:
```
What UteamUP tools do you have access to?
```
or
```
Show me all open work orders
```

That's it! 🎉

---

## Configuration

### Environment Variables

#### Required
| Variable | Description |
|----------|-------------|
| `UTEAMUP_API_KEY` | Your MCP-enabled API key (32 chars) |
| `UTEAMUP_SECRET` | Your API key secret (64+ chars) |

#### Optional
| Variable | Description | Default |
|----------|-------------|---------|
| `UTEAMUP_API_BASE_URL` | API endpoint URL | `https://api.uteamup.com` |
| `UTEAMUP_LOG_LEVEL` | Log level: TRACE, DEBUG, INFO, WARN, ERROR | `INFO` |
| `UTEAMUP_LOG_FORMAT` | Log format: text, json | `text` |
| `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 |
| **Development** | `https://devback.uteamup.com` | Testing against dev backend |
| **Local** | `https://localhost:5002` | Local development with self-signed cert |

### Permissions

Your AI assistant's permissions are controlled by the **role assigned to your API key**. To change what the AI can do:

1. Go to **Tenant Settings** → **API Keys** in UteamUP
2. Edit your API key
3. Change the **Role** (e.g., Admin, Supervisor, Read-Only)
4. Changes take effect immediately - no reconnection needed

**Tip:** Create separate API keys with different roles for different use cases (e.g., one for read-only queries, one for full access).

---

## Troubleshooting

### Common Issues

#### "Missing required environment variables"

**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`)
2. Verify the `env` section includes both `UTEAMUP_API_KEY` and `UTEAMUP_SECRET`
3. Ensure there are no typos in the environment