@kylewadegrove/cutline-mcp-cli 0.1.0

package/README.md

@@ -0,0 +1,173 @@
+# Cutline MCP CLI
+
+Command-line tool for authenticating with Cutline MCP servers.
+
+## Installation
+
+```bash
+cd functions/cutline/mcp-cli
+npm install
+npm run build
+npm link  # Makes cutline-mcp available globally
+```
+
+## Usage
+
+### Login
+
+Authenticate with Cutline and store credentials securely in your OS keychain:
+
+```bash
+cutline-mcp login
+```
+
+This will:
+1. Open your browser to Cutline's authentication page
+2. After you log in, receive a refresh token
+3. Store the token securely in your system keychain
+4. Display confirmation with your email
+
+### Check Status
+
+View your current authentication status:
+
+```bash
+cutline-mcp status
+```
+
+Shows:
+- Whether you're authenticated
+- Your email and user ID
+- Token expiration time
+- Subscription status (coming soon)
+
+### Logout
+
+Remove stored credentials:
+
+```bash
+cutline-mcp logout
+```
+
+## How It Works
+
+### Security
+
+- **Keychain Storage**: Tokens are stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
+- **Refresh Tokens**: Long-lived refresh tokens are stored, not short-lived ID tokens
+- **Automatic Refresh**: MCP servers automatically exchange refresh tokens for fresh ID tokens
+- **Revocable**: Tokens can be revoked from your Cutline account settings
+
+### Authentication Flow
+
+```
+1. User runs: cutline-mcp login
+2. CLI starts local callback server on localhost:8765
+3. CLI opens browser to: https://cutline.app/mcp-auth?callback=http://localhost:8765
+4. User logs in to Cutline (or is already logged in)
+5. Cutline redirects to: http://localhost:8765?token=REFRESH_TOKEN&email=user@example.com
+6. CLI receives token and stores in keychain
+7. CLI displays success message
+```
+
+### MCP Server Integration
+
+MCP servers automatically read tokens from the keychain:
+
+```typescript
+// In utils.ts
+async function requirePremium(authToken?: string) {
+  // Priority: explicit token > keychain > error
+  let token = authToken;
+  
+  if (!token) {
+    const refreshToken = await getStoredRefreshToken();
+    if (refreshToken) {
+      token = await exchangeRefreshToken(refreshToken);
+    }
+  }
+  
+  if (!token) {
+    throw new Error("Run 'cutline-mcp login' to authenticate");
+  }
+  
+  // ... validate token and subscription
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+- `CUTLINE_AUTH_URL`: Override auth endpoint (default: `https://cutline.app/mcp-auth`)
+- `FIREBASE_API_KEY`: Firebase API key for token exchange
+
+### Callback Port
+
+The CLI uses port `8765` for the OAuth callback. If this port is in use, you'll see an error. Close other applications and try again.
+
+## Troubleshooting
+
+### "Port 8765 is already in use"
+
+Another application is using the callback port. Find and close it:
+
+```bash
+lsof -i :8765
+kill -9 <PID>
+```
+
+### "Authentication timeout"
+
+The browser didn't complete the OAuth flow within 5 minutes. Try again:
+
+```bash
+cutline-mcp login
+```
+
+### "Failed to refresh token"
+
+Your stored token may be invalid or revoked. Log out and log in again:
+
+```bash
+cutline-mcp logout
+cutline-mcp login
+```
+
+### Keychain Access Denied
+
+On macOS, you may need to grant Terminal/IDE access to Keychain:
+
+1. Open Keychain Access app
+2. Find "cutline-mcp" entry
+3. Right-click → Get Info → Access Control
+4. Add your Terminal/IDE to allowed applications
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+### Test Locally
+
+```bash
+npm link
+cutline-mcp --help
+```
+
+## Next Steps
+
+- [ ] Add web app `/mcp-auth` endpoint
+- [ ] Implement device registration in Firestore
+- [ ] Add subscription status to `status` command
+- [ ] Publish to npm as `@cutline/mcp-cli`
+- [ ] Create standalone binaries for macOS/Windows/Linux

package/dist/auth/callback.d.ts

@@ -0,0 +1,5 @@
+export interface CallbackResult {
+    token: string;
+    email?: string;
+}
+export declare function startCallbackServer(): Promise<CallbackResult>;

package/dist/auth/callback.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCallbackServer = startCallbackServer;
+const express_1 = __importDefault(require("express"));
+const CALLBACK_PORT = 8765;
+const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+async function startCallbackServer() {
+    return new Promise((resolve, reject) => {
+        const app = (0, express_1.default)();
+        let server;
+        // Timeout handler
+        const timeout = setTimeout(() => {
+            server?.close();
+            reject(new Error('Authentication timeout - no callback received'));
+        }, TIMEOUT_MS);
+        // Callback endpoint
+        app.get('/', (req, res) => {
+            const token = req.query.token;
+            const email = req.query.email;
+            if (!token) {
+                res.status(400).send('Missing token parameter');
+                return;
+            }
+            // Send success page
+            res.send(`
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>Cutline MCP - Authentication Successful</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                display: flex;
+                justify-content: center;
+                align-items: center;
+                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: 400px;
+              }
+              h1 {
+                color: #667eea;
+                margin-bottom: 1rem;
+              }
+              p {
+                color: #666;
+                line-height: 1.6;
+              }
+              .checkmark {
+                font-size: 4rem;
+                color: #4CAF50;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="container">
+              <div class="checkmark">✓</div>
+              <h1>Authentication Successful!</h1>
+              <p>You can now close this window and return to your terminal.</p>
+              ${email ? `<p>Logged in as: <strong>${email}</strong></p>` : ''}
+            </div>
+          </body>
+        </html>
+      `);
+            // Clean up and resolve
+            clearTimeout(timeout);
+            server.close();
+            resolve({ token, email });
+        });
+        // Start server
+        server = app.listen(CALLBACK_PORT, () => {
+            console.log(`Callback server listening on http://localhost:${CALLBACK_PORT}`);
+        });
+        server.on('error', (err) => {
+            clearTimeout(timeout);
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${CALLBACK_PORT} is already in use. Please close other applications and try again.`));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}

package/dist/auth/keychain.d.ts

@@ -0,0 +1,3 @@
+export declare function storeRefreshToken(token: string): Promise<void>;
+export declare function getRefreshToken(): Promise<string | null>;
+export declare function deleteRefreshToken(): Promise<boolean>;

package/dist/auth/keychain.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeRefreshToken = storeRefreshToken;
+exports.getRefreshToken = getRefreshToken;
+exports.deleteRefreshToken = deleteRefreshToken;
+const keytar_1 = __importDefault(require("keytar"));
+const SERVICE_NAME = 'cutline-mcp';
+const ACCOUNT_NAME = 'refresh-token';
+async function storeRefreshToken(token) {
+    await keytar_1.default.setPassword(SERVICE_NAME, ACCOUNT_NAME, token);
+}
+async function getRefreshToken() {
+    return await keytar_1.default.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+}
+async function deleteRefreshToken() {
+    return await keytar_1.default.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+export declare function loginCommand(options: {
+    staging?: boolean;
+}): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loginCommand = loginCommand;
+const open_1 = __importDefault(require("open"));
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const callback_js_1 = require("../auth/callback.js");
+const keychain_js_1 = require("../auth/keychain.js");
+const config_js_1 = require("../utils/config.js");
+async function exchangeCustomToken(customToken, apiKey) {
+    const response = await fetch(`https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${apiKey}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            token: customToken,
+            returnSecureToken: true,
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to exchange custom token: ${error}`);
+    }
+    const data = await response.json();
+    return {
+        refreshToken: data.refreshToken,
+        email: data.email,
+    };
+}
+async function loginCommand(options) {
+    const config = (0, config_js_1.getConfig)(options);
+    console.log(chalk_1.default.bold('\n🔐 Cutline MCP Authentication\n'));
+    if (options.staging) {
+        console.log(chalk_1.default.yellow('  ⚠️  Using STAGING environment\n'));
+    }
+    if (!config.FIREBASE_API_KEY) {
+        const varName = options.staging ? 'FIREBASE_API_KEY_STAGING' : 'FIREBASE_API_KEY';
+        console.error(chalk_1.default.red(`Error: ${varName} environment variable is required.`));
+        console.error(chalk_1.default.gray('Please set it before running this command:'));
+        console.error(chalk_1.default.cyan(`  export ${varName}=AIzaSy...`));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('Starting authentication flow...').start();
+    try {
+        // Start callback server
+        spinner.text = 'Waiting for authentication...';
+        const serverPromise = (0, callback_js_1.startCallbackServer)();
+        // Open browser
+        const authUrl = `${config.AUTH_URL}?callback=${encodeURIComponent(config.CALLBACK_URL)}`;
+        await (0, open_1.default)(authUrl);
+        spinner.text = 'Browser opened - please complete authentication';
+        // Wait for callback with custom token
+        const result = await serverPromise;
+        // Exchange custom token for refresh token
+        spinner.text = 'Exchanging token...';
+        const { refreshToken, email } = await exchangeCustomToken(result.token, config.FIREBASE_API_KEY);
+        // Store refresh token
+        await (0, keychain_js_1.storeRefreshToken)(refreshToken);
+        spinner.succeed(chalk_1.default.green('Successfully authenticated!'));
+        if (email || result.email) {
+            console.log(chalk_1.default.gray(`  Logged in as: ${email || result.email}`));
+        }
+        console.log(chalk_1.default.gray('  MCP servers can now access your account\n'));
+        console.log(chalk_1.default.dim('  Run'), chalk_1.default.cyan('cutline-mcp status'), chalk_1.default.dim('to verify\n'));
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red('Authentication failed'));
+        if (error instanceof Error) {
+            console.error(chalk_1.default.red(`  ${error.message}\n`));
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1 @@
+export declare function logoutCommand(): Promise<void>;

package/dist/commands/logout.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logoutCommand = logoutCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const keychain_js_1 = require("../auth/keychain.js");
+async function logoutCommand() {
+    console.log(chalk_1.default.bold('\n👋 Logging out of Cutline MCP\n'));
+    const spinner = (0, ora_1.default)('Removing stored credentials...').start();
+    try {
+        const deleted = await (0, keychain_js_1.deleteRefreshToken)();
+        if (deleted) {
+            spinner.succeed(chalk_1.default.green('Successfully logged out'));
+            console.log(chalk_1.default.gray('  Credentials removed from keychain\n'));
+        }
+        else {
+            spinner.info(chalk_1.default.yellow('No credentials found'));
+            console.log(chalk_1.default.gray('  You were not logged in\n'));
+        }
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red('Logout failed'));
+        if (error instanceof Error) {
+            console.error(chalk_1.default.red(`  ${error.message}\n`));
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+export declare function statusCommand(options: {
+    staging?: boolean;
+}): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const firebase_admin_1 = __importDefault(require("firebase-admin"));
+const keychain_js_1 = require("../auth/keychain.js");
+const config_js_1 = require("../utils/config.js");
+async function exchangeRefreshToken(refreshToken, apiKey) {
+    const response = await fetch(`https://securetoken.googleapis.com/v1/token?key=${apiKey}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        let errorMessage = 'Failed to refresh token';
+        try {
+            const errorData = JSON.parse(errorText);
+            errorMessage = errorData.error?.message || errorText;
+        }
+        catch {
+            errorMessage = errorText;
+        }
+        throw new Error(errorMessage);
+    }
+    const data = await response.json();
+    return data.id_token;
+}
+async function statusCommand(options) {
+    console.log(chalk_1.default.bold('\n📊 Cutline MCP Status\n'));
+    const spinner = (0, ora_1.default)('Checking authentication...').start();
+    try {
+        // Check for stored refresh token
+        const refreshToken = await (0, keychain_js_1.getRefreshToken)();
+        if (!refreshToken) {
+            spinner.info(chalk_1.default.yellow('Not authenticated'));
+            console.log(chalk_1.default.gray('  Run'), chalk_1.default.cyan('cutline-mcp login'), chalk_1.default.gray('to authenticate\n'));
+            return;
+        }
+        // Get config for API key
+        const config = (0, config_js_1.getConfig)(options);
+        if (!config.FIREBASE_API_KEY) {
+            const varName = options.staging ? 'FIREBASE_API_KEY_STAGING' : 'FIREBASE_API_KEY';
+            spinner.fail(chalk_1.default.red('Configuration error'));
+            console.error(chalk_1.default.red(`  ${varName} environment variable is required.`));
+            process.exit(1);
+        }
+        // Exchange refresh token for ID token
+        spinner.text = 'Verifying credentials...';
+        const idToken = await exchangeRefreshToken(refreshToken, config.FIREBASE_API_KEY);
+        // Initialize Firebase Admin with correct project ID
+        if (firebase_admin_1.default.apps.length === 0) {
+            const projectId = options.staging ? 'demo-makerkit' : 'makerkit-todo-app';
+            firebase_admin_1.default.initializeApp({ projectId });
+        }
+        // Verify the ID token
+        const decoded = await firebase_admin_1.default.auth().verifyIdToken(idToken);
+        spinner.succeed(chalk_1.default.green('Authenticated'));
+        console.log(chalk_1.default.gray('  User:'), chalk_1.default.white(decoded.email || decoded.uid));
+        console.log(chalk_1.default.gray('  UID:'), chalk_1.default.dim(decoded.uid));
+        // Calculate token expiry
+        const expiresIn = Math.floor((decoded.exp * 1000 - Date.now()) / 1000 / 60);
+        console.log(chalk_1.default.gray('  Token expires in:'), chalk_1.default.white(`${expiresIn} minutes`));
+        // Show custom claims if present
+        if (decoded.mcp) {
+            console.log(chalk_1.default.gray('  MCP enabled:'), chalk_1.default.green('✓'));
+        }
+        if (decoded.deviceId) {
+            console.log(chalk_1.default.gray('  Device ID:'), chalk_1.default.dim(decoded.deviceId));
+        }
+        // TODO: Check subscription status from Firestore
+        console.log(chalk_1.default.gray('  Subscription:'), chalk_1.default.dim('(checking...)'));
+        console.log();
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red('Status check failed'));
+        if (error instanceof Error) {
+            console.error(chalk_1.default.red(`  ${error.message}`));
+            console.log(chalk_1.default.gray('  Try running'), chalk_1.default.cyan('cutline-mcp login'), chalk_1.default.gray('again\n'));
+        }
+        process.exit(1);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const login_js_1 = require("./commands/login.js");
+const logout_js_1 = require("./commands/logout.js");
+const status_js_1 = require("./commands/status.js");
+const program = new commander_1.Command();
+program
+    .name('cutline-mcp')
+    .description('CLI tool for authenticating with Cutline MCP servers')
+    .version('0.1.0');
+program
+    .command('login')
+    .description('Authenticate with Cutline and store credentials')
+    .option('--staging', 'Use staging environment')
+    .action(login_js_1.loginCommand);
+program
+    .command('logout')
+    .description('Remove stored credentials')
+    .action(logout_js_1.logoutCommand);
+program
+    .command('status')
+    .description('Show current authentication status')
+    .option('--staging', 'Use staging environment')
+    .action(status_js_1.statusCommand);
+program.parse();

package/dist/utils/config.d.ts

@@ -0,0 +1,8 @@
+export interface Config {
+    AUTH_URL: string;
+    CALLBACK_URL: string;
+    FIREBASE_API_KEY: string;
+}
+export declare function getConfig(options?: {
+    staging?: boolean;
+}): Config;

package/dist/utils/config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+function getConfig(options = {}) {
+    if (options.staging) {
+        return {
+            AUTH_URL: process.env.CUTLINE_AUTH_URL || 'https://cutline-staging.web.app/mcp-auth',
+            CALLBACK_URL: 'http://localhost:8765',
+            FIREBASE_API_KEY: process.env.FIREBASE_API_KEY_STAGING || process.env.FIREBASE_API_KEY || 'AIzaSyAAqU_euGAMtJoXp0sECblAIndifCp0pmE',
+        };
+    }
+    return {
+        AUTH_URL: process.env.CUTLINE_AUTH_URL || 'https://thecutline.ai/mcp-auth',
+        CALLBACK_URL: 'http://localhost:8765',
+        FIREBASE_API_KEY: process.env.FIREBASE_API_KEY || 'AIzaSyDW7846oQfvFU3Vnc1DELj4XdlvvYFjaIU',
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@kylewadegrove/cutline-mcp-cli",
+    "version": "0.1.0",
+    "description": "CLI tool for authenticating with Cutline MCP servers",
+    "main": "dist/index.js",
+    "bin": {
+        "cutline-mcp": "./dist/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "start": "node dist/index.js"
+    },
+    "keywords": [
+        "cutline",
+        "mcp",
+        "cli",
+        "authentication"
+    ],
+    "author": "Cutline",
+    "license": "MIT",
+    "dependencies": {
+        "commander": "^11.1.0",
+        "keytar": "^7.9.0",
+        "open": "^9.1.0",
+        "express": "^4.18.2",
+        "firebase-admin": "^12.0.0",
+        "chalk": "^4.1.2",
+        "ora": "^5.4.1"
+    },
+    "devDependencies": {
+        "@types/express": "^4.17.21",
+        "@types/node": "^20.0.0",
+        "typescript": "^5.3.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/auth/callback.ts

@@ -0,0 +1,102 @@
+import express from 'express';
+import type { Server } from 'http';
+
+const CALLBACK_PORT = 8765;
+const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+export interface CallbackResult {
+    token: string;
+    email?: string;
+}
+
+export async function startCallbackServer(): Promise<CallbackResult> {
+    return new Promise((resolve, reject) => {
+        const app = express();
+        let server: Server;
+
+        // Timeout handler
+        const timeout = setTimeout(() => {
+            server?.close();
+            reject(new Error('Authentication timeout - no callback received'));
+        }, TIMEOUT_MS);
+
+        // Callback endpoint
+        app.get('/', (req, res) => {
+            const token = req.query.token as string;
+            const email = req.query.email as string;
+
+            if (!token) {
+                res.status(400).send('Missing token parameter');
+                return;
+            }
+
+            // Send success page
+            res.send(`
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>Cutline MCP - Authentication Successful</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                display: flex;
+                justify-content: center;
+                align-items: center;
+                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: 400px;
+              }
+              h1 {
+                color: #667eea;
+                margin-bottom: 1rem;
+              }
+              p {
+                color: #666;
+                line-height: 1.6;
+              }
+              .checkmark {
+                font-size: 4rem;
+                color: #4CAF50;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="container">
+              <div class="checkmark">✓</div>
+              <h1>Authentication Successful!</h1>
+              <p>You can now close this window and return to your terminal.</p>
+              ${email ? `<p>Logged in as: <strong>${email}</strong></p>` : ''}
+            </div>
+          </body>
+        </html>
+      `);
+
+            // Clean up and resolve
+            clearTimeout(timeout);
+            server.close();
+            resolve({ token, email });
+        });
+
+        // Start server
+        server = app.listen(CALLBACK_PORT, () => {
+            console.log(`Callback server listening on http://localhost:${CALLBACK_PORT}`);
+        });
+
+        server.on('error', (err: any) => {
+            clearTimeout(timeout);
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${CALLBACK_PORT} is already in use. Please close other applications and try again.`));
+            } else {
+                reject(err);
+            }
+        });
+    });
+}

package/src/auth/keychain.ts

@@ -0,0 +1,16 @@
+import keytar from 'keytar';
+
+const SERVICE_NAME = 'cutline-mcp';
+const ACCOUNT_NAME = 'refresh-token';
+
+export async function storeRefreshToken(token: string): Promise<void> {
+    await keytar.setPassword(SERVICE_NAME, ACCOUNT_NAME, token);
+}
+
+export async function getRefreshToken(): Promise<string | null> {
+    return await keytar.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+}
+
+export async function deleteRefreshToken(): Promise<boolean> {
+    return await keytar.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+}

package/src/commands/login.ts

@@ -0,0 +1,89 @@
+import open from 'open';
+import chalk from 'chalk';
+import ora from 'ora';
+import { startCallbackServer } from '../auth/callback.js';
+import { storeRefreshToken } from '../auth/keychain.js';
+import { getConfig } from '../utils/config.js';
+
+async function exchangeCustomToken(customToken: string, apiKey: string): Promise<{ refreshToken: string; email?: string }> {
+    const response = await fetch(
+        `https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${apiKey}`,
+        {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                token: customToken,
+                returnSecureToken: true,
+            }),
+        }
+    );
+
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Failed to exchange custom token: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+        refreshToken: data.refreshToken,
+        email: data.email,
+    };
+}
+
+export async function loginCommand(options: { staging?: boolean }) {
+    const config = getConfig(options);
+    console.log(chalk.bold('\n🔐 Cutline MCP Authentication\n'));
+
+    if (options.staging) {
+        console.log(chalk.yellow('  ⚠️  Using STAGING environment\n'));
+    }
+
+    if (!config.FIREBASE_API_KEY) {
+        const varName = options.staging ? 'FIREBASE_API_KEY_STAGING' : 'FIREBASE_API_KEY';
+        console.error(chalk.red(`Error: ${varName} environment variable is required.`));
+        console.error(chalk.gray('Please set it before running this command:'));
+        console.error(chalk.cyan(`  export ${varName}=AIzaSy...`));
+        process.exit(1);
+    }
+
+    const spinner = ora('Starting authentication flow...').start();
+
+    try {
+        // Start callback server
+        spinner.text = 'Waiting for authentication...';
+        const serverPromise = startCallbackServer();
+
+        // Open browser
+        const authUrl = `${config.AUTH_URL}?callback=${encodeURIComponent(config.CALLBACK_URL)}`;
+        await open(authUrl);
+        spinner.text = 'Browser opened - please complete authentication';
+
+        // Wait for callback with custom token
+        const result = await serverPromise;
+
+        // Exchange custom token for refresh token
+        spinner.text = 'Exchanging token...';
+        const { refreshToken, email } = await exchangeCustomToken(result.token, config.FIREBASE_API_KEY);
+
+        // Store refresh token
+        await storeRefreshToken(refreshToken);
+
+        spinner.succeed(chalk.green('Successfully authenticated!'));
+
+        if (email || result.email) {
+            console.log(chalk.gray(`  Logged in as: ${email || result.email}`));
+        }
+
+        console.log(chalk.gray('  MCP servers can now access your account\n'));
+        console.log(chalk.dim('  Run'), chalk.cyan('cutline-mcp status'), chalk.dim('to verify\n'));
+
+    } catch (error) {
+        spinner.fail(chalk.red('Authentication failed'));
+
+        if (error instanceof Error) {
+            console.error(chalk.red(`  ${error.message}\n`));
+        }
+
+        process.exit(1);
+    }
+}

package/src/commands/logout.ts

@@ -0,0 +1,30 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { deleteRefreshToken } from '../auth/keychain.js';
+
+export async function logoutCommand() {
+    console.log(chalk.bold('\n👋 Logging out of Cutline MCP\n'));
+
+    const spinner = ora('Removing stored credentials...').start();
+
+    try {
+        const deleted = await deleteRefreshToken();
+
+        if (deleted) {
+            spinner.succeed(chalk.green('Successfully logged out'));
+            console.log(chalk.gray('  Credentials removed from keychain\n'));
+        } else {
+            spinner.info(chalk.yellow('No credentials found'));
+            console.log(chalk.gray('  You were not logged in\n'));
+        }
+
+    } catch (error) {
+        spinner.fail(chalk.red('Logout failed'));
+
+        if (error instanceof Error) {
+            console.error(chalk.red(`  ${error.message}\n`));
+        }
+
+        process.exit(1);
+    }
+}

package/src/commands/status.ts

@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import admin from 'firebase-admin';
+import { getRefreshToken } from '../auth/keychain.js';
+import { getConfig } from '../utils/config.js';
+
+async function exchangeRefreshToken(refreshToken: string, apiKey: string): Promise<string> {
+    const response = await fetch(
+        `https://securetoken.googleapis.com/v1/token?key=${apiKey}`,
+        {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+            }),
+        }
+    );
+
+    if (!response.ok) {
+        const errorText = await response.text();
+        let errorMessage = 'Failed to refresh token';
+        try {
+            const errorData = JSON.parse(errorText);
+            errorMessage = errorData.error?.message || errorText;
+        } catch {
+            errorMessage = errorText;
+        }
+        throw new Error(errorMessage);
+    }
+
+    const data = await response.json();
+    return data.id_token;
+}
+
+export async function statusCommand(options: { staging?: boolean }) {
+    console.log(chalk.bold('\n📊 Cutline MCP Status\n'));
+
+    const spinner = ora('Checking authentication...').start();
+
+    try {
+        // Check for stored refresh token
+        const refreshToken = await getRefreshToken();
+
+        if (!refreshToken) {
+            spinner.info(chalk.yellow('Not authenticated'));
+            console.log(chalk.gray('  Run'), chalk.cyan('cutline-mcp login'), chalk.gray('to authenticate\n'));
+            return;
+        }
+
+        // Get config for API key
+        const config = getConfig(options);
+
+        if (!config.FIREBASE_API_KEY) {
+            const varName = options.staging ? 'FIREBASE_API_KEY_STAGING' : 'FIREBASE_API_KEY';
+            spinner.fail(chalk.red('Configuration error'));
+            console.error(chalk.red(`  ${varName} environment variable is required.`));
+            process.exit(1);
+        }
+
+        // Exchange refresh token for ID token
+        spinner.text = 'Verifying credentials...';
+        const idToken = await exchangeRefreshToken(refreshToken, config.FIREBASE_API_KEY);
+
+        // Initialize Firebase Admin with correct project ID
+        if (admin.apps.length === 0) {
+            const projectId = options.staging ? 'demo-makerkit' : 'makerkit-todo-app';
+            admin.initializeApp({ projectId });
+        }
+
+        // Verify the ID token
+        const decoded = await admin.auth().verifyIdToken(idToken);
+
+        spinner.succeed(chalk.green('Authenticated'));
+
+        console.log(chalk.gray('  User:'), chalk.white(decoded.email || decoded.uid));
+        console.log(chalk.gray('  UID:'), chalk.dim(decoded.uid));
+
+        // Calculate token expiry
+        const expiresIn = Math.floor((decoded.exp * 1000 - Date.now()) / 1000 / 60);
+        console.log(chalk.gray('  Token expires in:'), chalk.white(`${expiresIn} minutes`));
+
+        // Show custom claims if present
+        if (decoded.mcp) {
+            console.log(chalk.gray('  MCP enabled:'), chalk.green('✓'));
+        }
+        if (decoded.deviceId) {
+            console.log(chalk.gray('  Device ID:'), chalk.dim(decoded.deviceId));
+        }
+
+        // TODO: Check subscription status from Firestore
+        console.log(chalk.gray('  Subscription:'), chalk.dim('(checking...)'));
+
+        console.log();
+
+    } catch (error) {
+        spinner.fail(chalk.red('Status check failed'));
+
+        if (error instanceof Error) {
+            console.error(chalk.red(`  ${error.message}`));
+            console.log(chalk.gray('  Try running'), chalk.cyan('cutline-mcp login'), chalk.gray('again\n'));
+        }
+
+        process.exit(1);
+    }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { statusCommand } from './commands/status.js';
+
+const program = new Command();
+
+program
+    .name('cutline-mcp')
+    .description('CLI tool for authenticating with Cutline MCP servers')
+    .version('0.1.0');
+
+program
+    .command('login')
+    .description('Authenticate with Cutline and store credentials')
+    .option('--staging', 'Use staging environment')
+    .action(loginCommand);
+
+program
+    .command('logout')
+    .description('Remove stored credentials')
+    .action(logoutCommand);
+
+program
+    .command('status')
+    .description('Show current authentication status')
+    .option('--staging', 'Use staging environment')
+    .action(statusCommand);
+
+program.parse();

package/src/utils/config.ts

@@ -0,0 +1,21 @@
+export interface Config {
+    AUTH_URL: string;
+    CALLBACK_URL: string;
+    FIREBASE_API_KEY: string;
+}
+
+export function getConfig(options: { staging?: boolean } = {}): Config {
+    if (options.staging) {
+        return {
+            AUTH_URL: process.env.CUTLINE_AUTH_URL || 'https://cutline-staging.web.app/mcp-auth',
+            CALLBACK_URL: 'http://localhost:8765',
+            FIREBASE_API_KEY: process.env.FIREBASE_API_KEY_STAGING || process.env.FIREBASE_API_KEY || 'AIzaSyAAqU_euGAMtJoXp0sECblAIndifCp0pmE',
+        };
+    }
+
+    return {
+        AUTH_URL: process.env.CUTLINE_AUTH_URL || 'https://thecutline.ai/mcp-auth',
+        CALLBACK_URL: 'http://localhost:8765',
+        FIREBASE_API_KEY: process.env.FIREBASE_API_KEY || 'AIzaSyDW7846oQfvFU3Vnc1DELj4XdlvvYFjaIU',
+    };
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "declaration": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}