equisense-research-mcp 0.2.0 → 0.3.1

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.
 
@@ -14,30 +14,13 @@ Published on npm: [`equisense-research-mcp`](https://www.npmjs.com/package/equis
 
 ## Quick start
 
-### 1. Mint a token
+### 1. Generate a token (self-serve)
 
-The MCP authenticates via a 90-day HMAC bearer token, byte-identical to a logged-in `ES_AUTH` session cookie. Mint it via the admin endpoint (admin-IP-restricted in prod via nginx; reachable on localhost in dev):
+Log in to the EquiSense web app and open **Settings → Claude → Connect Claude**. You get a **research-scoped, individually-revocable** token, shown once. Copy it (the web UI even pre-fills the full config block for you).
 
-```bash
-# Prod (must be on an admin-allowlisted IP)
-curl -X POST "https://equisense.ai/api/v1/admin/auth/mint-mcp-token?phoneNumber=9876543210"
-
-# Dev
-curl -X POST "http://localhost:8080/api/v1/admin/auth/mint-mcp-token?phoneNumber=9876543210"
-```
-
-Response:
-```json
-{
-  "token": "<payload>.<sig>",
-  "expiresAt": 1777777777,
-  "userId": "user-abc",
-  "phone": "9876543210",
-  "ttlSeconds": 7776000
-}
-```
+The token authenticates as `Authorization: Bearer <token>` and is limited to the research API — it cannot trade, change account settings, or mint further tokens. Revoke it any time from the same Settings page; revocation takes effect immediately.
 
-Copy the `token`. Treat it like a password.
+> The old admin endpoint `POST /api/v1/admin/auth/mint-mcp-token` is **deprecated** — it issued full-account session tokens with no per-token revocation. Use Settings → Claude instead.
 
 ### 2. Register the MCP with Claude Code
 
@@ -46,7 +29,7 @@ Copy the `token`. Treat it like a password.
 ```bash
 claude mcp add equisense-research --scope local \
   --env EQUISENSE_BASE_URL=https://equisense.ai \
-  --env EQUISENSE_MCP_TOKEN='<token from step 1>' \
+  --env EQUISENSE_MCP_TOKEN='<token from Settings → Claude>' \
   -- npx -y equisense-research-mcp
 ```
 
@@ -72,7 +55,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 }`.
 
@@ -84,14 +67,15 @@ You should get back `{ answer, companyName, isin, detectedIntent, followUpQuesti
 |---|---|---|
 | `EQUISENSE_BASE_URL` | `http://localhost:8080` | Backend root URL |
 | `EQUISENSE_TIMEOUT_MS` | `90000` | Per-request timeout (research queries can take 30–90s) |
-| `EQUISENSE_MCP_TOKEN` | **required** | HMAC bearer token. Treat like a password. |
+| `EQUISENSE_MCP_TOKEN` | **required** | Scoped bearer token from Settings → Claude. Treat like a password. |
 
 ## Security notes
 
-- 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).
+- The token is **research-scoped** — it can only call the research API (`/api/v1/research/*`), enforced by the backend registering its authenticator only on those paths. It cannot trade, change account settings, or mint further tokens.
+- The token is **individually revocable** from Settings → Claude. Revocation is immediate: a revoked token gets a `401` on the next call, with no signature-only fallback.
+- Tokens last 90 days. The wrapper also sends the token as a legacy `Cookie: ES_AUTH` header so older admin-minted session tokens keep working during migration; new scoped tokens authenticate via `Authorization: Bearer`.
 - 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 user's `AI_EQUITY_RESEARCH` daily quota — same metering as the web UI.
 
 ---
 
@@ -128,12 +112,11 @@ The Java app (Spring Boot 3.1) is too old for the Spring AI MCP server starter (
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `FATAL: EQUISENSE_MCP_TOKEN env var is required` on startup | Env var unset or empty | Pass `--env EQUISENSE_MCP_TOKEN=...` to `claude mcp add` |
-| `Auth failed (HTTP 401) ... re-mint via /api/v1/admin/auth/mint-mcp-token` | Token > 90 days old OR `auth.token.secret` rotated | Re-mint and update the env |
+| `Auth failed (HTTP 401)` | Token expired, revoked, or `auth.token.secret` rotated | Generate a fresh token in Settings → Claude and update the env |
 | `AI_EQUITY_RESEARCH quota exhausted (HTTP 402)` | Daily quota hit | Wait until tomorrow OR upgrade the user's plan |
 | `Rate limited (HTTP 429)` | Transient | Retry in a few seconds |
 | `Forbidden (HTTP 403)` | User doesn't have `AI_EQUITY_RESEARCH` feature | Check the user's license/plan |
 | Hangs > 90s with no response | Backend research query timed out | Bump `EQUISENSE_TIMEOUT_MS`; check backend logs |
-| `403` minting in prod | Your IP isn't admin-allowlisted | SSH to prod box and mint from there, or have an admin mint for you |
 
 ## License
 

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // EquiSense Research MCP server.
 //
-// Single tool: ask_research — proxies POST /api/v1/research/ask. The user mints a
+// 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.
 //
@@ -46,12 +46,12 @@ if (!MCP_TOKEN || MCP_TOKEN.trim() === "") {
 // 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 askResearch is exercised directly in unit tests.
+// 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 " +
@@ -150,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,
@@ -171,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.2.0",
+      version: "0.3.1",
     },
     {
       capabilities: {
@@ -187,21 +187,20 @@ 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,
   }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    // Capture the client identity here rather than via the `initialized`
+    // notification: a tool call can only arrive after initialize has completed,
+    // so getClientVersion() is reliably populated by now. The notification
+    // callback raced the first call (it could fire after the call's fetch had
+    // already built its headers), leaving the connection un-named on first use.
+    try {
+      clientName = server.getClientVersion()?.name || clientName;
+    } catch { /* leave clientName as-is */ }
+
     const { name, arguments: args } = request.params;
     const handler = TOOL_HANDLERS[name];
     if (!handler) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "equisense-research-mcp",
-  "version": "0.2.0",
-  "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 scoped, revocable token minted in Settings → Claude.",
+  "version": "0.3.1",
+  "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": {