whistler-mcp 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# Whistler MCP Server
+
+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.
+
+## 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).
+- **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`).
+
+## Usage via npx (Claude Desktop)
+
+To use this server locally with Claude Desktop, add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "whistler-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "whistler-mcp"
+      ],
+      "env": {
+        "API_URL": "https://whistler-backend.onrender.com/api"
+      }
+    }
+  }
+}
+```
+
+*Note: You do not need to provide a JWT token in the config. Try asking Claude a Whistler-related question, and it will prompt you to securely log in directly within the chat interface!*
+
+## Local Development
+1. Clone the repository.
+2. Run `npm install` inside the `/mcp` folder.
+3. Test locally using the `node server.js` command.

package/adapters/apiClient.js

@@ -0,0 +1,108 @@
+import 'dotenv/config';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const API_BASE_URL = process.env.API_URL || 'http://localhost:5000/api';
+export const TOKEN_PATH = path.join(os.homedir(), '.whistler_mcp_token.json');
+
+export function getSavedToken() {
+  if (fs.existsSync(TOKEN_PATH)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+      return data.token;
+    } catch(e) {}
+  }
+  return process.env.WHISTLER_API_TOKEN || null;
+}
+
+export function saveToken(token, user) {
+  fs.writeFileSync(TOKEN_PATH, JSON.stringify({ token, user }), 'utf8');
+}
+
+export function clearToken() {
+  if (fs.existsSync(TOKEN_PATH)) fs.unlinkSync(TOKEN_PATH);
+}
+
+/**
+ * Core adapter: Makes an HTTP request to the running Express application.
+ */
+export async function invokeApi(endpoint, method = 'GET', body = null) {
+  const headers = { 'Content-Type': 'application/json' };
+  
+  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.');
+  }
+
+  // Inject the real user token
+  headers['Authorization'] = `Bearer ${token}`;
+
+  const options = { method, headers };
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  let response;
+  try {
+    response = await fetch(`${API_BASE_URL}${endpoint}`, options);
+  } catch (error) {
+    throw new Error(`Failed to connect to API at ${API_BASE_URL}. Is the server running? ${error.message}`);
+  }
+  
+  let data;
+  try {
+    data = await response.json();
+  } catch (err) {
+    const text = await response.text();
+    data = { message: text || 'Non-JSON response' };
+  }
+
+  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(`API Error ${response.status}: ${data.message || JSON.stringify(data)}`);
+  }
+  
+  return data;
+}
+
+/**
+ * Fetch binary data (like PDFs) from the API.
+ */
+export async function invokeApiBinary(endpoint, method = 'GET', body = null) {
+  const headers = {};
+  
+  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.');
+  }
+
+  headers['Authorization'] = `Bearer ${token}`;
+
+  const options = { method, headers };
+  if (body) {
+    options.body = JSON.stringify(body);
+    headers['Content-Type'] = 'application/json';
+  }
+
+  let response;
+  try {
+    response = await fetch(`${API_BASE_URL}${endpoint}`, options);
+  } catch (error) {
+    throw new Error(`Failed to connect to API at ${API_BASE_URL}. Is the server running? ${error.message}`);
+  }
+
+  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.`);
+    }
+    const text = await response.text();
+    throw new Error(`API Error ${response.status}: ${text}`);
+  }
+  
+  return await response.arrayBuffer();
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "whistler-mcp",
+  "version": "1.0.0",
+  "description": "An MCP Server for retrieving placement data, job roles, and platform statistics from the Whistler API.",
+  "main": "server.js",
+  "bin": {
+    "whistler-mcp": "server.js"
+  },
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.2.0",
+    "dotenv": "^16.4.5",
+    "pdf-parse": "^1.1.1",
+    "zod": "^3.23.0"
+  },
+  "keywords": [
+    "mcp",
+    "whistler",
+    "ai",
+    "claude",
+    "cursor",
+    "IIT",
+    "Placement data archive"
+  ],
+  "author": "",
+  "license": "ISC"
+}

package/server.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  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';
+
+const API_BASE_URL = process.env.API_URL || 'https://whistler-backend.onrender.com/api';
+
+const server = new Server(
+  {
+    name: "whistler-mcp-server",
+    version: "2.0.0",
+  },
+  {
+    capabilities: { tools: {} },
+  }
+);
+
+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.",
+    schema: z.object({ email: z.string().email(), password: z.string() }),
+    inputSchema: { type: "object", properties: { email: { type: "string" }, password: { type: "string" } }, required: ["email", "password"] }
+  },
+  logout_whistler: {
+    description: "Log out of Whistler and clear the saved authentication token.",
+    schema: z.object({}),
+    inputSchema: { type: "object", properties: {} }
+  },
+
+  // Placement Data
+  get_companies: {
+    description: "Retrieve a list of companies. Optionally filter by year.",
+    schema: z.object({ year: z.number().optional() }),
+    inputSchema: { type: "object", properties: { year: { type: "number" } } }
+  },
+  get_company_roles: {
+    description: "Fetch specific job roles for a company.",
+    schema: z.object({ companyName: z.string(), year: z.number().optional() }),
+    inputSchema: { type: "object", properties: { companyName: { type: "string" }, year: { type: "number" } }, required: ["companyName"] }
+  },
+  
+  // Platform Stats
+  get_public_stats: {
+    description: "Retrieve public platform statistics.",
+    schema: z.object({}),
+    inputSchema: { type: "object", properties: {} }
+  },
+
+  // Feedback Management
+  submit_feedback: {
+    description: "Submit new user feedback.",
+    schema: z.object({
+      name: z.string(), email: z.string().email(), type: z.enum(['bug', 'feature', 'improvement', 'other']),
+      subject: z.string(), message: z.string()
+    }),
+    inputSchema: { type: "object", properties: { name: { type: "string" }, email: { type: "string" }, type: { type: "string" }, subject: { type: "string" }, message: { type: "string" } }, required: ["name", "email", "type", "subject", "message"] }
+  },
+
+  // PDF Access Requests
+  submit_pdf_request: {
+    description: "Submit a request to increase a user's daily PDF view limit.",
+    schema: z.object({ requestedLimit: z.number(), reason: z.string() }),
+    inputSchema: { type: "object", properties: { requestedLimit: { type: "number" }, reason: { type: "string" } }, required: ["requestedLimit", "reason"] }
+  },
+
+  // Buy Bids
+  submit_buy_bid: {
+    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: "Read the specific textual content of a company's job role PDF. This will consume 1 from the user's daily PDF view limit. Ensure you pass the exact `pdfUrl` obtained from `get_company_roles`.",
+    schema: z.object({ pdfUrl: z.string() }),
+    inputSchema: { type: "object", properties: { pdfUrl: { type: "string" } }, required: ["pdfUrl"] }
+  }
+};
+
+// Register tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: Object.entries(toolsDefinition).map(([name, def]) => ({
+      name,
+      description: def.description,
+      inputSchema: def.inputSchema,
+    }))
+  };
+});
+
+// Execute logic (Mapping Tools to the API Adapter)
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  if (!toolsDefinition[name]) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+
+  let validatedArgs;
+  try {
+    validatedArgs = toolsDefinition[name].schema.parse(args || {});
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(`Invalid arguments: ${error.errors.map(e => e.path.join('.') + ': ' + e.message).join(', ')}`);
+    }
+    throw error;
+  }
+
+  const params = validatedArgs;
+  let result;
+
+  try {
+    switch (name) {
+      case 'login_to_whistler': {
+        const loginRes = await fetch(`${API_BASE_URL}/auth/login`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ email: params.email, password: params.password })
+        });
+        
+        // Handle non-JSON or weird responses gracefully
+        let loginData = {};
+        try {
+          loginData = await loginRes.json();
+        } catch(e) {
+          const text = await loginRes.text();
+          throw new Error(`Login failed with weird response: ${text.substring(0, 100)}`);
+        }
+
+        if (!loginRes.ok) throw new Error(loginData.message || 'Login failed');
+        if (!loginData.token) throw new Error('Login succeeded but no token was returned.');
+        
+        saveToken(loginData.token, loginData);
+        result = { success: true, message: `Successfully authenticated! Token saved securely.` };
+        break;
+      }
+      case 'logout_whistler':
+        clearToken();
+        result = { success: true, message: 'Logged out successfully. Token cleared.' };
+        break;
+      case 'get_companies':
+        result = await invokeApi(`/pdfs/companies${params.year ? '?year='+params.year : ''}`);
+        break;
+      case 'get_company_roles':
+        result = await invokeApi(`/pdfs/company/${params.companyName}${params.year ? '?year='+params.year : ''}`, 'GET');
+        break;
+      case 'get_public_stats':
+        result = await invokeApi('/pdfs/stats');
+        break;
+      case 'submit_feedback':
+        result = await invokeApi('/feedback', 'POST', params);
+        break;
+      case 'submit_pdf_request':
+        result = await invokeApi('/pdf-access/request', 'POST', params);
+        break;
+      case 'submit_buy_bid':
+        result = await invokeApi('/buy-bid', 'POST', params);
+        break;
+      case 'view_job_pdf': {
+        const arrayBuffer = await invokeApiBinary(params.pdfUrl);
+        const buffer = Buffer.from(arrayBuffer);
+        const pdfData = await pdfParse(buffer);
+        result = { 
+          success: true, 
+          text: pdfData.text,
+          pages: pdfData.numpages,
+          message: "PDF successfully read and your daily limit has been updated."
+        };
+        break;
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Tool Execution Error: ${error.message}` }],
+      isError: true
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);