Cutline MCP CLI

Command-line tool for authenticating with Cutline MCP servers.

Installation

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:

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:

cutline-mcp status

Shows:

• Whether you're authenticated
• Your email and user ID
• Token expiration time
• Subscription status (coming soon)

Logout

Remove stored credentials:

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 protected]
6. CLI receives token and stores in keychain
7. CLI displays success message

MCP Server Integration

MCP servers automatically read tokens from the keychain:

// 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:

lsof -i :8765
kill -9 <PID>

"Authentication timeout"

The browser didn't complete the OAuth flow within 5 minutes. Try again:

cutline-mcp login

"Failed to refresh token"

Your stored token may be invalid or revoked. Log out and log in again:

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

npm run build

Watch Mode

npm run dev

Test Locally

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