@uteamup/mcp-server 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+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).
+
+## [1.0.0-beta.1] - 2026-02-10
+
+### Added
+- Initial beta release
+- OAuth 2.0 Authorization Code + PKCE authentication flow
+- Automatic token caching with 7-day expiration
+- Stdio transport for Claude Desktop/Code compatibility
+- Support for self-signed certificates (development mode)
+- Debug logging via `UTEAMUP_DEBUG` environment variable
+- Graceful shutdown handling (SIGINT/SIGTERM)
+- Comprehensive error messages for common authentication issues
+- Configuration validation with helpful error messages
+- JSDoc documentation for all public functions
+
+### Fixed
+- Token response parsing to use OAuth 2.0 standard `access_token` field (was incorrectly expecting `accessToken`)
+- JSON-RPC 2.0 response format to always include request IDs
+- Error handling for 401/403 HTTP status codes with user-friendly messages
+
+### Security
+- Single-use authorization codes enforced
+- PKCE S256 challenge method (SHA-256)
+- Token-only authentication (credentials never logged)
+- Memory-only token storage (not persisted to disk)
+
+## [Unreleased]
+
+### Planned
+- Automatic token refresh on expiration
+- Configurable token cache location
+- Additional error recovery strategies
+- Rate limiting support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UteamUP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,443 @@
+# @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)
+
+## 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.
+
+**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)
+
+**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
+```
+
+---
+
+## 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
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `UTEAMUP_API_KEY` | **Yes** | Your MCP-enabled API key (32 chars) | - |
+| `UTEAMUP_SECRET` | **Yes** | Your API key secret (64 chars) | - |
+| `UTEAMUP_API_BASE_URL` | No | API endpoint URL | `https://api.uteamup.com` |
+| `UTEAMUP_DEBUG` | No | Enable debug logging (`1` or `true`) | `false` |
+
+### API Base URLs
+
+| 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 variable names
+4. Restart Claude Desktop after making changes
+
+---
+
+#### "Authentication failed: Invalid API Key or Secret"
+
+**Cause:** Wrong credentials or API key has been revoked.
+
+**Solution:**
+1. Verify your credentials in UteamUP:
+   - Go to **Tenant Settings** → **API Keys**
+   - Check that your API key is **Active** (not expired or revoked)
+2. If credentials are lost, create a new API key:
+   - Click **"Create API Key"**
+   - Enable **"MCP Enabled"**
+   - Copy the new credentials
+3. Update your MCP configuration with the new credentials
+4. Restart Claude Desktop
+
+---
+
+#### "MCP access denied: Your API key does not have MCP enabled"
+
+**Cause:** The API key was created without MCP support.
+
+**Solution:**
+1. Create a new API key with MCP enabled:
+   - Go to **Tenant Settings** → **API Keys**
+   - Click **"Set up AI Integration"** or **"Create API Key"**
+   - **Important:** Check the **"MCP Enabled"** toggle
+   - Click **Create API Key**
+2. Update your MCP configuration with the new credentials
+3. Restart Claude Desktop
+
+**Note:** You cannot enable MCP on an existing API key. You must create a new one.
+
+---
+
+#### "ECONNREFUSED" or "Connection refused"
+
+**Cause:** Cannot reach the API server.
+
+**Solutions:**
+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`
+
+---
+
+#### "UNABLE_TO_VERIFY_LEAF_SIGNATURE" or certificate errors
+
+**Cause:** Self-signed certificate (development mode).
+
+**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
+
+---
+
+#### Tools list is empty or incomplete
+
+**Cause:** API key role has limited permissions.
+
+**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
+
+---
+
+### Debugging
+
+Enable debug logging to see detailed information:
+
+```json
+{
+  "mcpServers": {
+    "uteamup": {
+      "command": "npx",
+      "args": ["-y", "@uteamup/mcp-server"],
+      "env": {
+        "UTEAMUP_API_KEY": "your-key",
+        "UTEAMUP_SECRET": "your-secret",
+        "UTEAMUP_DEBUG": "1"
+      }
+    }
+  }
+}
+```
+
+Debug logs include:
+- OAuth flow details
+- PKCE generation
+- Token caching events
+- Request/response details
+
+**Note:** Debug logs are written to stderr, not stdout (which is reserved for JSON-RPC messages).
+
+---
+
+### Still Having Issues?
+
+1. **Check the logs:**
+   - Claude Desktop: View → Developer → Developer Tools → Console
+   - Look for `[MCP Proxy]` messages
+
+2. **Verify credentials format:**
+   - API Key: exactly 32 characters
+   - Secret: at least 64 characters
+   - No extra spaces or quotes
+
+3. **Test manually:**
+   ```bash
+   export UTEAMUP_API_KEY="your-key"
+   export UTEAMUP_SECRET="your-secret"
+   export UTEAMUP_DEBUG="1"
+   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx @uteamup/mcp-server
+   ```
+
+4. **Get help:**
+   - Email: support@uteamup.com
+   - Documentation: https://docs.uteamup.com/mcp
+   - GitHub Issues: https://github.com/uteamup/mcp-server/issues
+
+---
+
+## Development
+
+### Local Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/UteamUP/uteamup-mcp-proxy.git
+cd uteamup-mcp-proxy
+
+# Install dev dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run with debug logging
+export UTEAMUP_DEBUG=1
+export UTEAMUP_API_KEY="your-dev-key"
+export UTEAMUP_SECRET="your-dev-secret"
+export UTEAMUP_API_BASE_URL="https://localhost:5002"
+node index.js
+
+# Test with a sample request
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js
+```
+
+### Testing Locally with Claude Desktop
+
+```bash
+# Create a local link
+npm link
+
+# Update Claude Desktop config to use local version
+{
+  "mcpServers": {
+    "uteamup-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/uteamup-mcp-proxy/index.js"],
+      "env": {
+        "UTEAMUP_API_KEY": "your-key",
+        "UTEAMUP_SECRET": "your-secret",
+        "UTEAMUP_DEBUG": "1"
+      }
+    }
+  }
+}
+```
+
+### Project Structure
+
+```
+uteamup-mcp-proxy/
+├── index.js           # Main entry point (OAuth + MCP client)
+├── package.json       # Package metadata
+├── README.md          # This file
+├── LICENSE            # MIT license
+├── CHANGELOG.md       # Version history
+├── .gitignore         # Git ignore rules
+├── .npmignore         # Files to exclude from npm package
+└── test/              # Test files (not published)
+    ├── oauth.test.js
+    └── integration.test.js
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run only integration tests (requires credentials)
+npm run test:integration
+
+# Run with coverage
+npm test -- --coverage
+```
+
+### Code Style
+
+This project uses:
+- **ESLint** for linting
+- **Prettier** for formatting
+- **CommonJS** modules (not ESM) for maximum compatibility
+
+```bash
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`npm test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Commit Message Format
+
+```
+type(scope): subject
+
+Types: feat, fix, docs, refactor, test, chore
+Scope: oauth, client, docs, etc.
+
+Example:
+feat(oauth): add automatic token refresh on expiry
+fix(client): handle network timeouts gracefully
+docs(readme): update troubleshooting section
+```
+
+---
+
+## License
+
+MIT © UteamUP
+
+See [LICENSE](LICENSE) for details.
+
+---
+
+## Support
+
+- **Documentation:** https://docs.uteamup.com/mcp
+- **Email:** support@uteamup.com
+- **Issues:** https://github.com/uteamup/mcp-server/issues
+
+---
+
+## Related Links
+
+- [UteamUP Website](https://uteamup.com)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io)
+- [Claude Desktop](https://claude.ai/download)
+- [OAuth 2.0 PKCE](https://oauth.net/2/pkce/)

package/index.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+
+/**
+ * UteamUP MCP Proxy - Simple OAuth handler
+ * Usage: Set environment variables and run via npx or node
+ */
+
+const https = require('https');
+const crypto = require('crypto');
+
+// Configuration
+const API_KEY = process.env.UTEAMUP_API_KEY;
+const SECRET = process.env.UTEAMUP_SECRET;
+const BASE_URL = process.env.UTEAMUP_API_BASE_URL || 'https://localhost:5002';
+const DEBUG = process.env.UTEAMUP_DEBUG === '1' || process.env.UTEAMUP_DEBUG === 'true';
+
+// Token cache
+let accessToken = null;
+let tokenExpiry = null;
+
+/**
+ * Debug logging helper (only outputs when UTEAMUP_DEBUG is enabled)
+ * @param {...any} args - Arguments to log
+ */
+function debug(...args) {
+  if (DEBUG) console.error('[DEBUG]', ...args);
+}
+
+/**
+ * Generates a PKCE (Proof Key for Code Exchange) code verifier and challenge pair.
+ * @returns {{verifier: string, challenge: string}} PKCE pair with S256 challenge
+ */
+function generatePKCE() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  debug('Generated PKCE pair:', { verifierLength: verifier.length, challengeLength: challenge.length });
+  return { verifier, challenge };
+}
+
+/**
+ * Gets an OAuth access token, using cached token if still valid.
+ * Implements full OAuth 2.0 Authorization Code + PKCE flow.
+ * @returns {Promise<string>} JWT access token valid for 7 days
+ * @throws {Error} If authentication fails or credentials are invalid
+ */
+async function getAccessToken() {
+  // Return cached token if still valid
+  if (accessToken && tokenExpiry && Date.now() < tokenExpiry - 60000) {
+    debug('Using cached access token');
+    return accessToken;
+  }
+
+  console.error('[MCP Proxy] Getting new access token...');
+
+  const { verifier, challenge } = generatePKCE();
+
+  // Step 1: Get authorization code
+  const authCode = await new Promise((resolve, reject) => {
+    const authParams = new URLSearchParams({
+      response_type: 'code',
+      client_id: API_KEY,
+      redirect_uri: 'http://localhost:3000/callback',
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+      scope: 'mcp:full'
+    });
+
+    debug('Authorization request params:', authParams.toString());
+
+    https.get(`${BASE_URL}/oauth/authorize?${authParams}`, {
+      rejectUnauthorized: false // Allow self-signed certs for dev
+    }, (res) => {
+      const location = res.headers.location || '';
+      debug('Authorization redirect location:', location);
+
+      // Check for OAuth error in redirect
+      if (location.includes('error=')) {
+        const url = new URL(location, 'http://localhost');
+        const error = url.searchParams.get('error');
+        const description = url.searchParams.get('error_description');
+        reject(new Error(`OAuth authorization failed: ${error} - ${description || 'Unknown error'}`));
+        return;
+      }
+
+      const match = location.match(/code=([^&]+)/);
+      if (match) {
+        debug('Authorization code received');
+        resolve(match[1]);
+      } else {
+        reject(new Error('No authorization code in redirect. Location: ' + location));
+      }
+    }).on('error', reject);
+  });
+
+  console.error(`[MCP Proxy] Got auth code: ${authCode.substring(0, 20)}...`);
+
+  // Step 2: Exchange for access token
+  const tokenData = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: authCode,
+    redirect_uri: 'http://localhost:3000/callback',
+    client_id: API_KEY,
+    client_secret: SECRET,
+    code_verifier: verifier
+  }).toString();
+
+  const token = await new Promise((resolve, reject) => {
+    const req = https.request(`${BASE_URL}/oauth/token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(tokenData)
+      },
+      rejectUnauthorized: false
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        debug('Token exchange response status:', res.statusCode);
+        debug('Token exchange response data:', data);
+
+        // Check for error status codes
+        if (res.statusCode === 401) {
+          reject(new Error('Authentication failed: Invalid API Key or Secret. Please verify your credentials in UteamUP Tenant Settings → API Keys.'));
+          return;
+        }
+        if (res.statusCode === 403) {
+          if (data.includes('MCP') || data.includes('mcp')) {
+            reject(new Error('MCP access denied: Your API key does not have MCP enabled. Create a new MCP-enabled key in Tenant Settings → API Keys.'));
+          } else {
+            reject(new Error('Access forbidden: ' + data));
+          }
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`Token exchange failed (HTTP ${res.statusCode}): ${data}`));
+          return;
+        }
+
+        try {
+          const json = JSON.parse(data);
+          // CRITICAL FIX: Backend returns access_token (OAuth 2.0 standard), not accessToken
+          if (json.access_token) {
+            debug('Access token received successfully');
+            resolve(json.access_token);
+          } else if (json.error) {
+            reject(new Error(`OAuth error: ${json.error} - ${json.error_description || ''}`));
+          } else {
+            reject(new Error(`Token exchange failed: ${data}`));
+          }
+        } catch (e) {
+          reject(new Error(`Invalid JSON response: ${data}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(tokenData);
+    req.end();
+  });
+
+  accessToken = token;
+  tokenExpiry = Date.now() + (7 * 24 * 60 * 60 * 1000); // 7 days
+  console.error('[MCP Proxy] ✅ Got access token');
+  debug('Token cached, expires at:', new Date(tokenExpiry).toISOString());
+
+  return accessToken;
+}
+
+/**
+ * Forwards a JSON-RPC 2.0 MCP request to the backend.
+ * @param {object} request - JSON-RPC 2.0 request object
+ * @returns {Promise<object>} JSON-RPC 2.0 response object
+ */
+async function forwardRequest(request) {
+  const token = await getAccessToken();
+  const data = JSON.stringify(request);
+
+  debug('Forwarding request:', { method: request.method, id: request.id });
+
+  return new Promise((resolve, reject) => {
+    const req = https.request(`${BASE_URL}/mcp`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data)
+      },
+      rejectUnauthorized: false
+    }, (res) => {
+      let responseData = '';
+      res.on('data', chunk => responseData += chunk);
+      res.on('end', () => {
+        debug('MCP response received:', { statusCode: res.statusCode, dataLength: responseData.length });
+        try {
+          resolve(JSON.parse(responseData));
+        } catch (e) {
+          resolve({ error: { code: -32700, message: 'Parse error', data: responseData } });
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      console.error('[MCP Proxy] Network error:', error.message);
+      resolve({ error: { code: -32603, message: error.message } });
+    });
+
+    req.write(data);
+    req.end();
+  });
+}
+
+// Main stdio loop
+async function main() {
+  // Validate required environment variables
+  if (!API_KEY || !SECRET) {
+    console.error('ERROR: Missing required environment variables');
+    console.error('');
+    console.error('Required:');
+    console.error('  UTEAMUP_API_KEY    - Your MCP-enabled API key (32 characters)');
+    console.error('  UTEAMUP_SECRET     - Your API key secret (64+ characters)');
+    console.error('');
+    console.error('Optional:');
+    console.error('  UTEAMUP_API_BASE_URL - API endpoint (default: https://api.uteamup.com)');
+    console.error('  UTEAMUP_DEBUG        - Enable debug logging (1 or true)');
+    console.error('');
+    console.error('Example:');
+    console.error('  export UTEAMUP_API_KEY="your-api-key"');
+    console.error('  export UTEAMUP_SECRET="your-secret"');
+    console.error('  npx @uteamup/mcp-server');
+    process.exit(1);
+  }
+
+  // Validate API key format (should be 32 chars)
+  if (API_KEY.length !== 32) {
+    console.error('WARNING: API Key should be exactly 32 characters');
+    console.error(`  Current length: ${API_KEY.length}`);
+  }
+
+  // Validate secret format (should be 64+ chars)
+  if (SECRET.length < 64) {
+    console.error('WARNING: Secret should be at least 64 characters');
+    console.error(`  Current length: ${SECRET.length}`);
+  }
+
+  console.error('[MCP Proxy] Starting UteamUP MCP Server');
+  console.error(`[MCP Proxy] Version: 1.0.0-beta.1`);
+  console.error(`[MCP Proxy] Base URL: ${BASE_URL}`);
+  console.error(`[MCP Proxy] API Key: ${API_KEY.substring(0, 8)}...`);
+  console.error(`[MCP Proxy] Debug: ${DEBUG ? 'enabled' : 'disabled'}`);
+  console.error('[MCP Proxy] Ready to receive JSON-RPC requests');
+
+  let buffer = '';
+
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk.toString();
+
+    let newlineIndex;
+    while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+
+      if (!line) continue;
+
+      try {
+        const request = JSON.parse(line);
+        debug('Processing request:', request.method, 'id:', request.id);
+        console.error(`[MCP Proxy] Request: ${request.method}`);
+
+        const response = await forwardRequest(request);
+
+        // Ensure response includes request ID for proper JSON-RPC 2.0 format
+        if (request.id !== undefined && response.id === undefined) {
+          response.id = request.id;
+        }
+
+        process.stdout.write(JSON.stringify(response) + '\n');
+        debug('Response sent for request id:', request.id);
+      } catch (error) {
+        console.error('[MCP Proxy] Error:', error.message);
+
+        // Try to extract request ID if possible
+        let requestId = null;
+        try {
+          const req = JSON.parse(line);
+          requestId = req.id;
+        } catch (e) {
+          // Line wasn't valid JSON, use null
+        }
+
+        const errorResponse = {
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: error.message,
+            data: DEBUG ? error.stack : undefined
+          },
+          id: requestId
+        };
+        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    console.error('[MCP Proxy] stdin closed, exiting');
+    process.exit(0);
+  });
+
+  process.stdin.resume();
+}
+
+// Graceful shutdown handlers
+process.on('SIGINT', () => {
+  console.error('[MCP Proxy] Received SIGINT, shutting down gracefully...');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  console.error('[MCP Proxy] Received SIGTERM, shutting down gracefully...');
+  process.exit(0);
+});
+
+process.on('uncaughtException', (error) => {
+  console.error('[MCP Proxy] Uncaught exception:', error.message);
+  if (DEBUG) console.error(error.stack);
+  process.exit(1);
+});
+
+main().catch((error) => {
+  console.error('[MCP Proxy] Fatal error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@uteamup/mcp-server",
+  "version": "1.0.0-beta.1",
+  "description": "MCP server client for UteamUP - enables Claude Desktop/Code integration with automatic OAuth 2.0 authentication",
+  "main": "index.js",
+  "bin": {
+    "uteamup-mcp-server": "./index.js"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "uteamup",
+    "claude",
+    "claude-desktop",
+    "claude-code",
+    "oauth",
+    "oauth2",
+    "pkce",
+    "cmms",
+    "maintenance",
+    "work-orders",
+    "asset-management"
+  ],
+  "author": "UteamUP <support@uteamup.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uteamup/mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uteamup/mcp-server/issues"
+  },
+  "homepage": "https://github.com/uteamup/mcp-server#readme",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:integration": "jest test/integration.test.js",
+    "lint": "eslint index.js test/",
+    "format": "prettier --write \"**/*.{js,json,md}\"",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "eslint": "^8.56.0",
+    "prettier": "^3.2.5"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}