equisense-research-mcp 0.1.1 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Thin Node.js MCP wrapper that exposes the EquiSense AI equity-research engine as
 
 | Tool | Endpoint | What it does |
 |---|---|---|
-| `ask_research` | `POST /api/v1/research/ask` | Natural-language Q&A over Indian-listed companies. Returns answer, detected company, intent, follow-up suggestions. |
+| `ask_equisense` | `POST /api/v1/research/ask` | Natural-language Q&A over Indian-listed companies. Returns answer, detected company, intent, follow-up suggestions. |
 
 Same brain the WhatsApp chat uses, just over MCP instead of WhatsApp.
 
@@ -72,7 +72,7 @@ Should show `equisense-research - ✓ Connected`.
 
 In any Claude Code session:
 
-> Use ask_research: bull case for OLAELEC
+> Use ask_equisense: bull case for OLAELEC
 
 You should get back `{ answer, companyName, isin, detectedIntent, followUpQuestions, responseTimeMs }`.
 
@@ -91,7 +91,7 @@ You should get back `{ answer, companyName, isin, detectedIntent, followUpQuesti
 - The minted token grants **full session access** for 90 days, scope-equivalent to a logged-in browser session for that user. Not scoped to research-only.
 - There is no per-token revocation in v1. The only way to invalidate a token early is to rotate the global `auth.token.secret` (which logs out every user).
 - Never commit the token. Never log it. Never paste it into chat.
-- Each `ask_research` call counts against the represented user's `AI_EQUITY_RESEARCH` daily quota — same metering as the web UI.
+- Each `ask_equisense` call counts against the represented user's `AI_EQUITY_RESEARCH` daily quota — same metering as the web UI.
 
 ---
 

package/index.js

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
 // EquiSense Research MCP server.
 //
-// Single tool: ask_research — proxies POST /api/v1/research/ask. The Spring Boot
-// app authenticates the caller via a Cookie: ES_AUTH=<token> header. The token
-// is minted via POST /api/v1/admin/auth/mint-mcp-token (admin-only) and passed
-// in here through the EQUISENSE_MCP_TOKEN env var.
+// Single tool: ask_equisense — proxies POST /api/v1/research/ask. The user mints a
+// scoped, revocable token in the web app (Settings → Claude) and passes it here
+// via the EQUISENSE_MCP_TOKEN env var.
 //
-// Treat the token like a password — it grants full session access to that user
-// for SESSION_TTL_SECONDS (90 days). Never log it. Never commit it.
+// Auth: we send the token BOTH as `Authorization: Bearer <token>` and as a
+// `Cookie: ES_AUTH=<token>` header. New self-serve tokens are RESEARCH-scoped and
+// authenticate via the Bearer path (McpAuthFilter); legacy admin-minted full-session
+// tokens authenticate via the cookie path (PersistentAuthFilter). Sending both means
+// either kind of token works with no client-side branching — the backend ignores the
+// header that doesn't apply.
+//
+// Treat the token like a password. A scoped token grants read-only research access;
+// revoke it any time in Settings → Claude. Never log it. Never commit it.
 //
 // Transport: stdio. Register in Claude Code via:
 //   claude mcp add equisense-research --scope local \
-//     --env EQUISENSE_BASE_URL=http://localhost:8080 \
-//     --env EQUISENSE_MCP_TOKEN='<minted>' \
+//     --env EQUISENSE_BASE_URL=https://equisense.ai \
+//     --env EQUISENSE_MCP_TOKEN='<token from Settings → Claude>' \
 //     -- node /abs/path/to/index.js
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -31,15 +37,21 @@ const MCP_TOKEN = process.env.EQUISENSE_MCP_TOKEN;
 
 if (!MCP_TOKEN || MCP_TOKEN.trim() === "") {
   console.error(
-    "FATAL: EQUISENSE_MCP_TOKEN env var is required. Mint one via " +
-      "POST /api/v1/admin/auth/mint-mcp-token?phoneNumber=<userPhone>.",
+    "FATAL: EQUISENSE_MCP_TOKEN env var is required. Generate one in the " +
+      "EquiSense web app under Settings → Claude.",
   );
   process.exit(1);
 }
 
+// Client identity from the MCP initialize handshake (e.g. "claude-ai",
+// "Claude Code"). Captured once, forwarded as X-MCP-Client so the backend can
+// auto-name the connection in Settings → Claude. Null until the handshake lands
+// and when askEquisense is exercised directly in unit tests.
+let clientName = null;
+
 export const TOOLS = [
   {
-    name: "ask_research",
+    name: "ask_equisense",
     description:
       "Ask EquiSense's AI equity-research engine a natural-language question " +
       "about an Indian-listed company (NSE/BSE). Returns the answer, the " +
@@ -83,7 +95,10 @@ async function callRest(path, options = {}) {
       headers: {
         "Content-Type": "application/json",
         Accept: "application/json",
+        // Bearer for new scoped tokens; Cookie for legacy session tokens. See header note.
+        Authorization: `Bearer ${MCP_TOKEN}`,
         Cookie: `ES_AUTH=${MCP_TOKEN}`,
+        ...(clientName ? { "X-MCP-Client": clientName } : {}),
         ...(options.headers || {}),
       },
     });
@@ -103,8 +118,8 @@ function formatHttpError(path, status, bodyText) {
     return (
       "Auth failed (HTTP 401) calling " +
       path +
-      ". EQUISENSE_MCP_TOKEN is expired or invalid. Re-mint via " +
-      "POST /api/v1/admin/auth/mint-mcp-token and update the env var."
+      ". EQUISENSE_MCP_TOKEN is expired, revoked, or invalid. Generate a fresh one " +
+      "in the EquiSense web app under Settings → Claude and update the env var."
     );
   }
   if (status === 402) {
@@ -135,7 +150,7 @@ function formatHttpError(path, status, bodyText) {
   return `EquiSense REST ${path} returned HTTP ${status}: ${snippet}`;
 }
 
-export async function askResearch(args) {
+export async function askEquisense(args) {
   const body = {
     query: args.query,
     isin: args.isin ?? null,
@@ -156,14 +171,14 @@ export async function askResearch(args) {
 }
 
 const TOOL_HANDLERS = {
-  ask_research: askResearch,
+  ask_equisense: askEquisense,
 };
 
 function createServer() {
   const server = new Server(
     {
       name: "equisense-research",
-      version: "0.1.0",
+      version: "0.3.0",
     },
     {
       capabilities: {
@@ -172,6 +187,16 @@ function createServer() {
     },
   );
 
+  // Capture the client identity once the initialize handshake completes, so
+  // callRest can forward it as X-MCP-Client for auto-naming the connection.
+  server.oninitialized = () => {
+    try {
+      clientName = server.getClientVersion()?.name || null;
+    } catch {
+      clientName = null;
+    }
+  };
+
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
   }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "equisense-research-mcp",
-  "version": "0.1.1",
-  "description": "MCP server wrapper for the EquiSense AI equity-research API. Exposes a single ask_research tool that proxies POST /api/v1/research/ask, authenticated via a minted ES_AUTH bearer token.",
+  "version": "0.3.0",
+  "description": "MCP server wrapper for the EquiSense AI equity-research API. Exposes a single ask_equisense tool that proxies POST /api/v1/research/ask, authenticated via a scoped, revocable token minted in Settings → Claude.",
   "type": "module",
   "main": "index.js",
   "bin": {