whistler-mcp 1.0.13 → 1.0.21

package/README.md

@@ -1,11 +1,11 @@
 # Whistler MCP Server
 ![npm downloads](https://img.shields.io/npm/dt/whistler-mcp?color=indigo&style=flat) ![npm version](https://img.shields.io/npm/v/whistler-mcp?color=indigo&style=flat)
 
-An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with the Whistler placement data platform. This allows AI assistants like Claude Desktop, Cursor, and others to seamlessly read job roles, platform statistics, and PDFs on your behalf.
+An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for interacting with the Whistler placement data platform. This allows AI assistants like Claude Desktop, Cursor, and others to browse company lists and role metadata on your behalf.
 
 ## Features
-- **Job Placement Data:** Fetch lists of companies and specific job roles for any requested year.
-- **PDF Reading:** Natively extracts text from job description PDFs (respects your daily view limit).
+- **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`).
 

package/adapters/apiClient.js

@@ -2,18 +2,48 @@ import 'dotenv/config';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { version: MCP_VERSION } = require('../package.json');
 
 const API_BASE_URL = process.env.API_URL || 'https://whistler-backend.onrender.com/api';
 export const TOKEN_PATH = path.join(os.homedir(), '.whistler_mcp_token.json');
+export const WHISTLER_CLIENT_ID = `whistler-mcp/${MCP_VERSION}`;
+
+function withClientHeaders(headers = {}) {
+  return {
+    ...headers,
+    'X-Whistler-Client': WHISTLER_CLIENT_ID
+  };
+}
+
+function isTokenExpired(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString('utf8'));
+    return payload.exp && payload.exp < Math.floor(Date.now() / 1000);
+  } catch {
+    return false;
+  }
+}
 
 export function getSavedToken() {
   if (fs.existsSync(TOKEN_PATH)) {
     try {
       const data = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
-      return data.token;
+      if (data.token) {
+        if (isTokenExpired(data.token)) {
+          // Remove the stale token file so the next call prompts re-login
+          fs.unlinkSync(TOKEN_PATH);
+          return null;
+        }
+        return data.token;
+      }
     } catch (e) { }
   }
-  return process.env.WHISTLER_API_TOKEN || null;
+  const envToken = process.env.WHISTLER_API_TOKEN || null;
+  if (envToken && isTokenExpired(envToken)) return null;
+  return envToken;
 }
 
 export function saveToken(token, user) {
@@ -29,7 +59,7 @@ export function clearToken() {
  */
 export async function invokeApi(endpoint, method = 'GET', body = null, options = {}) {
   const { requireAuth = true, includeAuthIfAvailable = false } = options;
-  const headers = { 'Content-Type': 'application/json' };
+  const headers = withClientHeaders({ 'Content-Type': 'application/json' });
 
   const token = getSavedToken();
   if (requireAuth) {
@@ -79,7 +109,7 @@ export async function invokeApi(endpoint, method = 'GET', body = null, options =
  */
 export async function invokeApiBinary(endpoint, method = 'GET', body = null, signal = undefined, options = {}) {
   const { requireAuth = true } = options;
-  const headers = {};
+  const headers = withClientHeaders({});
 
   if (requireAuth) {
     const token = getSavedToken();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whistler-mcp",
-  "version": "1.0.13",
+  "version": "1.0.21",
   "description": "An MCP Server for retrieving placement data, job roles, and platform statistics from the Whistler API.",
   "main": "server.js",
   "bin": {
@@ -10,7 +10,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.2.0",
     "dotenv": "^16.4.5",
-    "pdf-parse": "^1.1.1",
     "zod": "^3.23.0"
   },
   "keywords": [

package/server.js

@@ -7,19 +7,15 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { createRequire } from 'module';
 
-const require = createRequire(import.meta.url);
-const pdfParse = require('pdf-parse');
-
-import { invokeApi, invokeApiBinary, saveToken, clearToken } from './adapters/apiClient.js';
+import { invokeApi, saveToken, clearToken, WHISTLER_CLIENT_ID } from './adapters/apiClient.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.13",
+    version: "1.0.21",
   },
   {
     capabilities: { tools: {} },
@@ -105,7 +101,7 @@ const toolsDefinition = {
     }
   },
   get_company_roles: {
-    description: "Fetch job roles for a company using companyId or companyName.",
+    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.",
     schema: z.object({
       companyId: z.string().optional(),
       companyName: z.string().optional(),
@@ -123,6 +119,24 @@ 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.",
+    schema: z.object({
+      companyName: z.string(),
+      jobId: z.string(),
+      year: z.number().optional()
+    }),
+    inputSchema: {
+      type: "object",
+      properties: {
+        companyName: { type: "string" },
+        jobId: { type: "string" },
+        year: { type: "number" }
+      },
+      required: ["companyName", "jobId"]
+    }
+  },
+
   // Platform Stats
   get_public_stats: {
     description: "Retrieve public platform statistics.",
@@ -142,7 +156,7 @@ const toolsDefinition = {
 
   // PDF Access Requests
   submit_pdf_request: {
-    description: "Submit a request to increase a user's daily PDF view limit.",
+    description: "Submit a request to increase a user's daily PDF view limit (web app only for viewing PDFs).",
     schema: z.object({ requestedLimit: z.number(), reason: z.string() }),
     inputSchema: { type: "object", properties: { requestedLimit: { type: "number" }, reason: { type: "string" } }, required: ["requestedLimit", "reason"] }
   },
@@ -152,13 +166,6 @@ const toolsDefinition = {
     description: "Submit an inquiry or bid to buy the platform.",
     schema: z.object({ name: z.string(), email: z.string().email(), phone: z.string(), amount: z.number(), message: z.string().optional() }),
     inputSchema: { type: "object", properties: { name: { type: "string" }, email: { type: "string" }, phone: { type: "string" }, amount: { type: "number" }, message: { type: "string" } }, required: ["name", "email", "phone", "amount"] }
-  },
-
-  // Read PDF
-  view_job_pdf: {
-    description: "Extract and read the textual content of a company's job role PDF. IMPORTANT: pdfUrl tokens expire after 10 minutes. You MUST call get_company_roles immediately before calling this tool to get a fresh pdfUrl. Never reuse a pdfUrl from a previous tool call. (Consumes 1 daily view).",
-    schema: z.object({ pdfUrl: z.string() }),
-    inputSchema: { type: "object", properties: { pdfUrl: { type: "string" } }, required: ["pdfUrl"] }
   }
 };
 
@@ -365,7 +372,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'login_to_whistler': {
         const loginRes = await fetch(`${API_BASE_URL}/auth/login`, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Whistler-Client': WHISTLER_CLIENT_ID
+          },
           body: JSON.stringify({ email: params.email, password: params.password })
         });
 
@@ -388,7 +398,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'signup_to_whistler': {
         const signupRes = await fetch(`${API_BASE_URL}/auth/signup`, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Whistler-Client': WHISTLER_CLIENT_ID
+          },
           body: JSON.stringify({ ...params, acceptedTerms: true })
         });
 
@@ -471,6 +484,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = await invokeApi(`/pdfs/company/${encodedCompanyIdentifier}${params.year ? '?year=' + params.year : ''}`, 'GET');
         break;
       }
+      case 'get_role_jd': {
+        const encodedCompany = encodeURIComponent(params.companyName);
+        const encodedJobId = encodeURIComponent(params.jobId);
+        result = await invokeApi(
+          `/pdfs/mcp/role-jd/${encodedCompany}/${encodedJobId}${params.year ? '?year=' + params.year : ''}`,
+          'GET'
+        );
+        break;
+      }
       case 'get_public_stats':
         result = await invokeApi('/pdfs/stats', 'GET');
         break;
@@ -486,76 +508,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'submit_buy_bid':
         result = await invokeApi('/buy-bid', 'POST', params, { requireAuth: false });
         break;
-      case 'view_job_pdf': {
-        // Guard: pdfUrl must exist and look like a valid API path
-        if (!params.pdfUrl || params.pdfUrl === 'undefined' || params.pdfUrl === 'null') {
-          result = {
-            success: false,
-            message: "This job does not have a PDF available. The 'pdfUrl' field was not returned by get_company_roles, which means no JD PDF exists for this role."
-          };
-          break;
-        }
-        if (!params.pdfUrl.startsWith('/api/pdfs/')) {
-          result = {
-            success: false,
-            message: `Invalid pdfUrl format: "${params.pdfUrl}". You must pass the exact 'pdfUrl' value returned by get_company_roles (e.g. /api/pdfs/view/<token>). Call get_company_roles again to get a fresh token.`
-          };
-          break;
-        }
-        // pdfUrl from the backend is a relative path like /api/pdfs/view/:token
-        // invokeApiBinary prepends API_BASE_URL which already ends in /api,
-        // so we must strip the leading /api prefix to avoid doubling it.
-        const normalizedPdfUrl = params.pdfUrl.replace(/^\/api/, '');
-        let binaryEndpoint = normalizedPdfUrl;
-
-        // New flow: redeem token and download through viewer session document endpoint.
-        if (/^\/pdfs\/view\/.+/.test(normalizedPdfUrl)) {
-          let viewPayload;
-          try {
-            viewPayload = await invokeApi(normalizedPdfUrl, 'GET');
-          } catch (tokenErr) {
-            // A 401/403 error here almost always means the pdfUrl token expired.
-            if (tokenErr.message.includes('403') || tokenErr.message.includes('401') || tokenErr.message.toLowerCase().includes('token')) {
-              result = {
-                success: false,
-                message: `The pdfUrl token has expired or is invalid. Please call get_company_roles again for ${params.pdfUrl.split('/').pop()?.substring(0, 8) || 'this company'} to receive a fresh pdfUrl, then immediately call view_job_pdf again with the new value.`
-              };
-              break;
-            }
-            throw tokenErr;
-          }
-          const sessionToken = viewPayload?.viewer?.sessionToken;
-          if (!sessionToken) {
-            throw new Error('Viewer session was not created for this pdfUrl.');
-          }
-          binaryEndpoint = `/pdfs/viewer/${sessionToken}/document`;
-        }
-
-        // Fetch binary with a 30-second timeout to avoid indefinite hangs
-        const binaryController = new AbortController();
-        const binaryTimeout = setTimeout(() => binaryController.abort(), 30000);
-        let arrayBuffer;
-        try {
-          arrayBuffer = await invokeApiBinary(binaryEndpoint, 'GET', null, binaryController.signal);
-        } catch (binErr) {
-          if (binErr.name === 'AbortError' || binErr.message?.includes('aborted')) {
-            throw new Error('PDF download timed out after 30 seconds. The file may be too large or the Cloudinary CDN is slow. Please try again.');
-          }
-          throw binErr;
-        } finally {
-          clearTimeout(binaryTimeout);
-        }
-
-        const buffer = Buffer.from(arrayBuffer);
-        const pdfData = await pdfParse(buffer);
-        result = {
-          success: true,
-          text: pdfData.text,
-          pages: pdfData.numpages,
-          message: "PDF read successfully."
-        };
-        break;
-      }
     }
 
     return {