@efficy/tribecrm-mcp-server 0.4.1 → 0.4.3

package/README.md

@@ -30,6 +30,44 @@ Model Context Protocol (MCP) server for TribeCRM API integration. This server en
 
 > ⚠️ **Breaking Change in v0.4.0**: The server now defaults to read-only mode for security. If you need write access, set `TRIBECRM_MODE=read-write` in your configuration.
 
+## 🔐 Authentication Methods
+
+### App Authentication (Default)
+The server uses **OAuth2 Client Credentials flow** for service account authentication. This is the default and recommended method for AI assistants and automated systems.
+
+**Use case**: AI assistants, automation, backend services
+
+**Configuration**:
+```bash
+TRIBECRM_AUTH=app  # Default - can be omitted
+```
+
+### User Authentication ✨ NEW
+**OAuth2 Authorization Code flow** for user-specific authentication. This allows the MCP server to act on behalf of a specific user rather than a service account.
+
+**Use case**: Personal AI assistants, user-specific operations
+
+**Setup**:
+1. Run the authentication helper:
+   ```bash
+   npx @efficy/tribecrm-mcp-server authenticate
+   # or if installed locally:
+   npm run authenticate
+   ```
+
+2. Your browser will open for TribeCRM login
+
+3. After successful authentication, tokens are saved locally to `~/.tribecrm/tokens.json`
+
+4. Configure your MCP client with `TRIBECRM_AUTH=user`
+
+**Features**:
+- ✅ Browser-based OAuth consent flow
+- ✅ Automatic token refresh (tokens valid for 24 hours)
+- ✅ Secure local token storage
+- ✅ PKCE (Proof Key for Code Exchange) for additional security
+- ✅ User-specific access rights respected
+
 ## 📋 Prerequisites
 
 - Node.js 18 or higher
@@ -73,14 +111,17 @@ Add to your Claude Desktop config file:
         "TRIBECRM_CLIENT_ID": "your_client_id",
         "TRIBECRM_CLIENT_SECRET": "your_client_secret",
         "TRIBECRM_ORGANIZATION_ID": "your_org_id",
-        "TRIBECRM_MODE": "read-only"
+        "TRIBECRM_MODE": "read-only",
+        "TRIBECRM_AUTH": "app"
       }
     }
   }
 }
 ```
 
-**Note**: Set `TRIBECRM_MODE` to `read-write` if you need to create, update, or delete entities.
+**Note**:
+- Set `TRIBECRM_MODE` to `read-write` if you need to create, update, or delete entities.
+- For user authentication, set `TRIBECRM_AUTH` to `user` and optionally add `TRIBECRM_REDIRECT_URI` (defaults to `http://localhost:3000/callback`).
 
 #### Using Local Installation
 
@@ -96,7 +137,8 @@ Add to your Claude Desktop config file:
         "TRIBECRM_CLIENT_ID": "your_client_id",
         "TRIBECRM_CLIENT_SECRET": "your_client_secret",
         "TRIBECRM_ORGANIZATION_ID": "your_org_id",
-        "TRIBECRM_MODE": "read-only"
+        "TRIBECRM_MODE": "read-only",
+        "TRIBECRM_AUTH": "app"
       }
     }
   }
@@ -121,6 +163,12 @@ Add to your Claude Desktop config file:
 - `TRIBECRM_MODE` (optional): Server operation mode - `read-only` (default) or `read-write`
   - `read-only`: Only allows queries and data retrieval (get, query operations). Write tools are hidden.
   - `read-write`: Allows full access including create, update, and delete operations.
+- `TRIBECRM_AUTH` (optional): Authentication method - `app` (default) or `user`
+  - `app`: OAuth2 Client Credentials flow for service account authentication
+  - `user`: OAuth2 Authorization Code flow for user-specific authentication
+- `TRIBECRM_REDIRECT_URI` (optional): Redirect URI for user authentication (only needed when `TRIBECRM_AUTH=user`)
+  - Default: `http://localhost:3000/callback`
+  - Must match the redirect URI configured in your TribeCRM OAuth application
 
 ## 📚 Available Tools
 

package/dist/auth/callback-server.d.ts

@@ -0,0 +1,41 @@
+export interface CallbackResult {
+    code: string;
+    state: string;
+    error?: string;
+}
+/**
+ * Temporary HTTP server to handle OAuth callback
+ */
+export declare class CallbackServer {
+    private server;
+    private port;
+    constructor(port?: number);
+    /**
+     * Start the callback server and wait for OAuth redirect
+     * @param expectedState Expected state parameter for CSRF validation
+     * @param timeout Timeout in milliseconds (default: 5 minutes)
+     * @returns Promise that resolves with authorization code
+     */
+    waitForCallback(expectedState: string, timeout?: number): Promise<CallbackResult>;
+    /**
+     * Stop the callback server
+     */
+    stop(): void;
+    /**
+     * Get port number
+     */
+    getPort(): number;
+    /**
+     * Generate success HTML page
+     */
+    private getSuccessPage;
+    /**
+     * Generate error HTML page
+     */
+    private getErrorPage;
+    /**
+     * Escape HTML to prevent XSS
+     */
+    private escapeHtml;
+}
+//# sourceMappingURL=callback-server.d.ts.map

package/dist/auth/callback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.d.ts","sourceRoot":"","sources":["../../src/auth/callback-server.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,IAAI,CAAS;gBAET,IAAI,GAAE,MAAa;IAI/B;;;;;OAKG;IACG,eAAe,CACnB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,MAAe,GACvB,OAAO,CAAC,cAAc,CAAC;IA4F1B;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,OAAO,CAAC,cAAc;IAwDtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAgEpB;;OAEG;IACH,OAAO,CAAC,UAAU;CAQnB"}

package/dist/auth/callback-server.js

@@ -0,0 +1,247 @@
+import http from 'http';
+import { URL } from 'url';
+/**
+ * Temporary HTTP server to handle OAuth callback
+ */
+export class CallbackServer {
+    server = null;
+    port;
+    constructor(port = 3000) {
+        this.port = port;
+    }
+    /**
+     * Start the callback server and wait for OAuth redirect
+     * @param expectedState Expected state parameter for CSRF validation
+     * @param timeout Timeout in milliseconds (default: 5 minutes)
+     * @returns Promise that resolves with authorization code
+     */
+    async waitForCallback(expectedState, timeout = 300000) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.stop();
+                reject(new Error('OAuth callback timeout - user did not complete authentication'));
+            }, timeout);
+            this.server = http.createServer((req, res) => {
+                try {
+                    const url = new URL(req.url || '', `http://localhost:${this.port}`);
+                    // Only handle callback path
+                    if (url.pathname !== '/callback') {
+                        res.writeHead(404, { 'Content-Type': 'text/html' });
+                        res.end('<html><body><h1>404 Not Found</h1></body></html>');
+                        return;
+                    }
+                    const code = url.searchParams.get('code');
+                    const state = url.searchParams.get('state');
+                    const error = url.searchParams.get('error');
+                    const errorDescription = url.searchParams.get('error_description');
+                    // Handle OAuth errors
+                    if (error) {
+                        const errorMsg = errorDescription || error;
+                        res.writeHead(400, { 'Content-Type': 'text/html' });
+                        res.end(this.getErrorPage(errorMsg));
+                        clearTimeout(timeoutId);
+                        this.stop();
+                        reject(new Error(`OAuth error: ${errorMsg}`));
+                        return;
+                    }
+                    // Validate required parameters
+                    if (!code || !state) {
+                        res.writeHead(400, { 'Content-Type': 'text/html' });
+                        res.end(this.getErrorPage('Missing code or state parameter'));
+                        clearTimeout(timeoutId);
+                        this.stop();
+                        reject(new Error('Invalid callback: missing code or state'));
+                        return;
+                    }
+                    // Validate state (CSRF protection)
+                    if (state !== expectedState) {
+                        res.writeHead(400, { 'Content-Type': 'text/html' });
+                        res.end(this.getErrorPage('Invalid state parameter - possible CSRF attack'));
+                        clearTimeout(timeoutId);
+                        this.stop();
+                        reject(new Error('State validation failed - possible CSRF attack'));
+                        return;
+                    }
+                    // Success!
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(this.getSuccessPage());
+                    clearTimeout(timeoutId);
+                    this.stop();
+                    resolve({ code, state });
+                }
+                catch (error) {
+                    res.writeHead(500, { 'Content-Type': 'text/html' });
+                    res.end(this.getErrorPage('Internal server error'));
+                    clearTimeout(timeoutId);
+                    this.stop();
+                    reject(error);
+                }
+            });
+            this.server.listen(this.port, 'localhost', () => {
+                console.error(`Callback server listening on http://localhost:${this.port}/callback`);
+            });
+            this.server.on('error', (error) => {
+                clearTimeout(timeoutId);
+                this.stop();
+                if (error.code === 'EADDRINUSE') {
+                    reject(new Error(`Port ${this.port} is already in use. Please close other applications using this port.`));
+                }
+                else {
+                    reject(new Error(`Server error: ${error.message}`));
+                }
+            });
+        });
+    }
+    /**
+     * Stop the callback server
+     */
+    stop() {
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+            console.error('Callback server stopped');
+        }
+    }
+    /**
+     * Get port number
+     */
+    getPort() {
+        return this.port;
+    }
+    /**
+     * Generate success HTML page
+     */
+    getSuccessPage() {
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Authentication Successful</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      min-height: 100vh;
+      margin: 0;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    }
+    .container {
+      background: white;
+      padding: 3rem;
+      border-radius: 1rem;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+      text-align: center;
+      max-width: 500px;
+    }
+    .icon {
+      font-size: 4rem;
+      margin-bottom: 1rem;
+    }
+    h1 {
+      color: #2d3748;
+      margin-bottom: 1rem;
+    }
+    p {
+      color: #4a5568;
+      line-height: 1.6;
+    }
+    .success {
+      color: #48bb78;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon success">✓</div>
+    <h1>Authentication Successful!</h1>
+    <p>You have successfully authenticated with TribeCRM.</p>
+    <p><strong>You can now close this window and return to your terminal.</strong></p>
+    <p style="font-size: 0.875rem; color: #718096; margin-top: 2rem;">
+      Your credentials have been securely stored locally.
+    </p>
+  </div>
+</body>
+</html>`;
+    }
+    /**
+     * Generate error HTML page
+     */
+    getErrorPage(errorMessage) {
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Authentication Failed</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      min-height: 100vh;
+      margin: 0;
+      background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+    }
+    .container {
+      background: white;
+      padding: 3rem;
+      border-radius: 1rem;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+      text-align: center;
+      max-width: 500px;
+    }
+    .icon {
+      font-size: 4rem;
+      margin-bottom: 1rem;
+    }
+    h1 {
+      color: #2d3748;
+      margin-bottom: 1rem;
+    }
+    p {
+      color: #4a5568;
+      line-height: 1.6;
+    }
+    .error {
+      color: #f56565;
+    }
+    .error-detail {
+      background: #fff5f5;
+      border: 1px solid #fc8181;
+      border-radius: 0.5rem;
+      padding: 1rem;
+      margin-top: 1rem;
+      font-family: monospace;
+      font-size: 0.875rem;
+      color: #c53030;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon error">✗</div>
+    <h1>Authentication Failed</h1>
+    <p>There was an error during authentication.</p>
+    <div class="error-detail">${this.escapeHtml(errorMessage)}</div>
+    <p style="margin-top: 2rem;">Please close this window and try again in your terminal.</p>
+  </div>
+</body>
+</html>`;
+    }
+    /**
+     * Escape HTML to prevent XSS
+     */
+    escapeHtml(unsafe) {
+        return unsafe
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#039;');
+    }
+}
+//# sourceMappingURL=callback-server.js.map

package/dist/auth/callback-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.js","sourceRoot":"","sources":["../../src/auth/callback-server.ts"],"names":[],"mappings":"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"}

package/dist/auth/oauth-flow.d.ts

@@ -0,0 +1,55 @@
+import { AuthToken } from '../types.js';
+export interface OAuthConfig {
+    authUrl: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    organizationId?: string;
+}
+export interface PKCEPair {
+    verifier: string;
+    challenge: string;
+}
+/**
+ * OAuth2 Authorization Code Flow Helper
+ * Handles consent URL generation, PKCE, and token exchange
+ */
+export declare class OAuthFlow {
+    private config;
+    constructor(config: OAuthConfig);
+    /**
+     * Generate PKCE code verifier and challenge
+     * @returns PKCEPair with verifier and challenge
+     */
+    generatePKCE(): PKCEPair;
+    /**
+     * Generate OAuth consent URL
+     * @param state Random state parameter for CSRF protection
+     * @param codeChallenge PKCE code challenge
+     * @returns Consent URL for user to visit
+     */
+    generateConsentUrl(state: string, codeChallenge: string): string;
+    /**
+     * Exchange authorization code for tokens
+     * @param code Authorization code from OAuth callback
+     * @param codeVerifier PKCE code verifier
+     * @returns Token response with access_token, refresh_token, etc.
+     */
+    exchangeCodeForTokens(code: string, codeVerifier: string): Promise<AuthToken & {
+        refresh_token?: string;
+    }>;
+    /**
+     * Refresh access token using refresh token
+     * @param refreshToken Refresh token from previous authentication
+     * @returns New token response
+     */
+    refreshAccessToken(refreshToken: string): Promise<AuthToken & {
+        refresh_token?: string;
+    }>;
+    /**
+     * Generate random state parameter for CSRF protection
+     * @returns Random state string
+     */
+    static generateState(): string;
+}
+//# sourceMappingURL=oauth-flow.d.ts.map

package/dist/auth/oauth-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-flow.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAc;gBAEhB,MAAM,EAAE,WAAW;IAI/B;;;OAGG;IACH,YAAY,IAAI,QAAQ;IAaxB;;;;;OAKG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAkBhE;;;;;OAKG;IACG,qBAAqB,CACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BlD;;;;OAIG;IACG,kBAAkB,CACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAwBlD;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,MAAM;CAG/B"}

package/dist/auth/oauth-flow.js

@@ -0,0 +1,106 @@
+import crypto from 'crypto';
+import axios from 'axios';
+/**
+ * OAuth2 Authorization Code Flow Helper
+ * Handles consent URL generation, PKCE, and token exchange
+ */
+export class OAuthFlow {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Generate PKCE code verifier and challenge
+     * @returns PKCEPair with verifier and challenge
+     */
+    generatePKCE() {
+        // Generate code verifier (43-128 characters, base64url)
+        const verifier = crypto.randomBytes(32).toString('base64url');
+        // Generate code challenge (SHA256 hash of verifier, base64url)
+        const challenge = crypto
+            .createHash('sha256')
+            .update(verifier)
+            .digest('base64url');
+        return { verifier, challenge };
+    }
+    /**
+     * Generate OAuth consent URL
+     * @param state Random state parameter for CSRF protection
+     * @param codeChallenge PKCE code challenge
+     * @returns Consent URL for user to visit
+     */
+    generateConsentUrl(state, codeChallenge) {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            state: state,
+            response_type: 'code',
+            scope: 'read write offline',
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        });
+        if (this.config.organizationId) {
+            params.append('organization_id', this.config.organizationId);
+        }
+        return `${this.config.authUrl}/oauth2/auth?${params.toString()}`;
+    }
+    /**
+     * Exchange authorization code for tokens
+     * @param code Authorization code from OAuth callback
+     * @param codeVerifier PKCE code verifier
+     * @returns Token response with access_token, refresh_token, etc.
+     */
+    async exchangeCodeForTokens(code, codeVerifier) {
+        try {
+            const response = await axios.post(`${this.config.authUrl}/oauth2/token`, new URLSearchParams({
+                grant_type: 'authorization_code',
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                redirect_uri: this.config.redirectUri,
+                code: code,
+                code_verifier: codeVerifier,
+            }), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            const errorMsg = error.response?.data?.error_description || error.message;
+            throw new Error(`Token exchange failed: ${errorMsg}`);
+        }
+    }
+    /**
+     * Refresh access token using refresh token
+     * @param refreshToken Refresh token from previous authentication
+     * @returns New token response
+     */
+    async refreshAccessToken(refreshToken) {
+        try {
+            const response = await axios.post(`${this.config.authUrl}/oauth2/token`, new URLSearchParams({
+                grant_type: 'refresh_token',
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                refresh_token: refreshToken,
+            }), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            const errorMsg = error.response?.data?.error_description || error.message;
+            throw new Error(`Token refresh failed: ${errorMsg}`);
+        }
+    }
+    /**
+     * Generate random state parameter for CSRF protection
+     * @returns Random state string
+     */
+    static generateState() {
+        return crypto.randomBytes(16).toString('hex');
+    }
+}
+//# sourceMappingURL=oauth-flow.js.map

package/dist/auth/oauth-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.js","sourceRoot":"","sources":["../../src/auth/oauth-flow.ts"],"names":[],"mappings":"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"}

package/dist/auth/oauth-flow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth-flow.test.d.ts.map

package/dist/auth/oauth-flow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.test.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-flow.test.ts"],"names":[],"mappings":""}