whistler-mcp 1.0.21 → 1.0.24

package/README.md

@@ -5,9 +5,9 @@ An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) ser
 
 ## Features
 - **Job Placement Data:** Fetch lists of companies and role metadata (title, CTC, eligibility) for any requested year.
-- **Job descriptions on demand (`get_role_jd`):** The backend derives JD content server-side — extracted text when the PDF has a text layer, or page images when it is image-only. The raw PDF file is never shared. Counts toward your daily view limit.
-- **Feedback & Requests:** Submit bug reports, feature ideas, and PDF limit increase requests dynamically.
-- **Agentic Authentication:** The AI securely prompts you for your email and password when you first connect, fetches a real token from the backend, and saves it locally (`~/.whistler_mcp_token.json`).
+- **Job descriptions on demand (`get_role_jd`):** Fetch a role's job description by company and role id. Counts toward your daily view limit.
+- **Feedback & Requests:** Submit bug reports, feature ideas, and daily limit increase requests dynamically.
+- **Agentic Authentication:** The AI securely prompts you for your email and password when you first connect, fetches a real token from the backend, and saves it locally (`~/.whistler_mcp_token.json`). No account? Sign up via `signup_to_whistler` or the website. If you use Google on the site, sign in there first; otherwise use the password you set on the website.
 
 ## Usage via npx (Claude Desktop)
 

package/adapters/apiClient.js

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { createRequire } from 'module';
+import { formatAuthRequiredError, formatTokenExpiredError } from './authGuidance.js';
 
 const require = createRequire(import.meta.url);
 const { version: MCP_VERSION } = require('../package.json');
@@ -64,7 +65,7 @@ export async function invokeApi(endpoint, method = 'GET', body = null, options =
   const token = getSavedToken();
   if (requireAuth) {
     if (!token) {
-      throw new Error('Not authenticated. Please ask the user for their email and password, and run the login_to_whistler tool to log them in automatically.');
+      throw new Error(formatAuthRequiredError());
     }
     // Inject the real user token
     headers['Authorization'] = `Bearer ${token}`;
@@ -95,7 +96,7 @@ export async function invokeApi(endpoint, method = 'GET', body = null, options =
   if (!response.ok) {
     if (response.status === 401) {
       clearToken(); // Token might be expired
-      throw new Error(`API Error 401: Token expired or invalid. Please ask the user for their email and password to log in again via login_to_whistler.`);
+      throw new Error(formatTokenExpiredError());
     }
     throw new Error(`API Error ${response.status}: ${data.message || JSON.stringify(data)}`);
   }
@@ -114,7 +115,7 @@ export async function invokeApiBinary(endpoint, method = 'GET', body = null, sig
   if (requireAuth) {
     const token = getSavedToken();
     if (!token) {
-      throw new Error('Not authenticated. Please ask the user for their email and password, and run the login_to_whistler tool to log them in automatically.');
+      throw new Error(formatAuthRequiredError());
     }
     headers['Authorization'] = `Bearer ${token}`;
   }
@@ -136,7 +137,7 @@ export async function invokeApiBinary(endpoint, method = 'GET', body = null, sig
   if (!response.ok) {
     if (response.status === 401) {
       clearToken();
-      throw new Error(`API Error 401: Token expired or invalid. Please ask the user for their email and password to log in again via login_to_whistler.`);
+      throw new Error(formatTokenExpiredError());
     }
     const text = await response.text();
     throw new Error(`API Error ${response.status}: ${text}`);

package/adapters/authGuidance.js

@@ -0,0 +1,71 @@
+const FRONTEND_URL = (process.env.FRONTEND_URL || 'https://whistler-six.vercel.app').replace(/\/$/, '');
+
+export const AUTH_URLS = {
+  login: `${FRONTEND_URL}/login`,
+  signup: `${FRONTEND_URL}/signup`
+};
+
+const PROFILE_PASSWORD_HINT =
+  'If you are already signed in on the website, update your password from Profile → Set password.';
+
+export function formatLoginFailure(status, data = {}) {
+  const message = data.message || 'Login failed';
+
+  if (status === 404 && data.isUserNotFound) {
+    return [
+      message,
+      `No Whistler account exists for this email. Create one at ${AUTH_URLS.signup}, then run login_to_whistler again.`
+    ].join(' ');
+  }
+
+  if (status === 401) {
+    if (/locked/i.test(message)) {
+      return `${message} Wait for the lockout to end, then try again. ${PROFILE_PASSWORD_HINT}`;
+    }
+    return [
+      message,
+      `Sign in at ${AUTH_URLS.login} with Google if you use Google on the site, or use the password you set there.`,
+      PROFILE_PASSWORD_HINT,
+      'Then run login_to_whistler with the correct password.'
+    ].join(' ');
+  }
+
+  if (status === 403 && data.isAccountDeleted) {
+    return `${message} Deleted accounts cannot be recovered.`;
+  }
+
+  if (status === 429) {
+    return `${message} Try again later.`;
+  }
+
+  return message;
+}
+
+export function formatSignupFailure(status, data = {}) {
+  const message = data.message || 'Signup failed';
+
+  if (status === 400 && /already exists/i.test(message)) {
+    return [
+      message,
+      `Sign in with login_to_whistler instead.`
+    ].join(' ');
+  }
+
+  return message;
+}
+
+export function formatAuthRequiredError() {
+  return [
+    'Not authenticated.',
+    'Run login_to_whistler with your email and password.',
+    `No account yet? Sign up at ${AUTH_URLS.signup}.`
+  ].join(' ');
+}
+
+export function formatTokenExpiredError() {
+  return [
+    'API Error 401: Token expired or invalid.',
+    'Run login_to_whistler again.',
+    `Sign in at ${AUTH_URLS.login} if you need to check your account.`
+  ].join(' ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whistler-mcp",
-  "version": "1.0.21",
+  "version": "1.0.24",
   "description": "An MCP Server for retrieving placement data, job roles, and platform statistics from the Whistler API.",
   "main": "server.js",
   "bin": {

package/server.js

@@ -9,13 +9,14 @@ import {
 import { z } from 'zod';
 
 import { invokeApi, saveToken, clearToken, WHISTLER_CLIENT_ID } from './adapters/apiClient.js';
+import { AUTH_URLS, formatLoginFailure, formatSignupFailure } from './adapters/authGuidance.js';
 
 const API_BASE_URL = process.env.API_URL || 'https://whistler-backend.onrender.com/api';
 
 const server = new Server(
   {
     name: "whistler-mcp-server",
-    version: "1.0.21",
+    version: "1.0.24",
   },
   {
     capabilities: { tools: {} },
@@ -25,12 +26,12 @@ const server = new Server(
 const toolsDefinition = {
   // Authentication
   login_to_whistler: {
-    description: "Log into Whistler and save the authentication token. Use this automatically if a request fails with 401 Unauthorized or missing token.",
+    description: `Log into Whistler and save the authentication token. No account? Sign up at ${AUTH_URLS.signup}.`,
     schema: z.object({ email: z.string().email(), password: z.string() }),
     inputSchema: { type: "object", properties: { email: { type: "string" }, password: { type: "string" } }, required: ["email", "password"] }
   },
   signup_to_whistler: {
-    description: "Create a new Whistler account. Use this if the user doesn't have an account yet.",
+    description: `Create a new Whistler account in MCP. Alternatively sign up at ${AUTH_URLS.signup}. If the email already exists, use login_to_whistler.`,
     schema: z.object({
       name: z.string(),
       email: z.string().email(),
@@ -101,7 +102,7 @@ const toolsDefinition = {
     }
   },
   get_company_roles: {
-    description: "Fetch job role metadata for a company (title, CTC, eligibility, location). Returns each role with a stable `id`. To read a role's job description, call get_role_jd with that company and role id. The raw PDF file is never shared.",
+    description: "Fetch job role metadata for a company (title, CTC, eligibility, location). Returns each role with a stable `id`. To read a role's job description, call get_role_jd with that company and role id.",
     schema: z.object({
       companyId: z.string().optional(),
       companyName: z.string().optional(),
@@ -120,7 +121,7 @@ const toolsDefinition = {
   },
 
   get_role_jd: {
-    description: "Get the job description for a single role. The backend derives content server-side: it returns extracted text when the role's PDF has a text layer, or page images (base64) when the PDF is image-only. The raw PDF file is never returned. Counts toward your daily view limit. Use the company name/id and the role `id` from get_company_roles.",
+    description: "Get the job description for a single role. Counts toward your daily view limit. Use the company name and role `id` from get_company_roles.",
     schema: z.object({
       companyName: z.string(),
       jobId: z.string(),
@@ -156,7 +157,7 @@ const toolsDefinition = {
 
   // PDF Access Requests
   submit_pdf_request: {
-    description: "Submit a request to increase a user's daily PDF view limit (web app only for viewing PDFs).",
+    description: "Submit a request to increase a user's daily job description view limit.",
     schema: z.object({ requestedLimit: z.number(), reason: z.string() }),
     inputSchema: { type: "object", properties: { requestedLimit: { type: "number" }, reason: { type: "string" } }, required: ["requestedLimit", "reason"] }
   },
@@ -388,7 +389,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           throw new Error(`Login failed with weird response: ${text.substring(0, 100)}`);
         }
 
-        if (!loginRes.ok) throw new Error(loginData.message || 'Login failed');
+        if (!loginRes.ok) {
+          throw new Error(formatLoginFailure(loginRes.status, loginData));
+        }
         if (!loginData.token) throw new Error('Login succeeded but no token was returned.');
 
         saveToken(loginData.token, loginData);
@@ -413,7 +416,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           throw new Error(`Signup failed with weird response: ${text.substring(0, 100)}`);
         }
 
-        if (!signupRes.ok) throw new Error(signupData.message || 'Signup failed');
+        if (!signupRes.ok) {
+          throw new Error(formatSignupFailure(signupRes.status, signupData));
+        }
         if (!signupData.token) throw new Error('Signup succeeded but no token was returned.');
 
         saveToken(signupData.token, signupData);