equisense-research-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # equisense-research MCP server
 
-Thin Node.js wrapper that exposes the EquiSense AI equity-research endpoint as a single MCP tool:
+Thin Node.js MCP wrapper that exposes the EquiSense AI equity-research engine as a single tool:
 
 | Tool | Endpoint | What it does |
 |---|---|---|
@@ -8,35 +8,25 @@ Thin Node.js wrapper that exposes the EquiSense AI equity-research endpoint as a
 
 Same brain the WhatsApp chat uses, just over MCP instead of WhatsApp.
 
-## Why Node?
-
-The Java app (Spring Boot 3.1) is too old for the Spring AI MCP server starter (needs 3.4+). All research logic, LLM routing, and feature metering stay server-side in Java; this wrapper just speaks MCP.
-
-## Setup
-
-```bash
-cd mcp-server/equisense-research
-npm install
-```
+Published on npm: [`equisense-research-mcp`](https://www.npmjs.com/package/equisense-research-mcp)
 
-## Environment variables
+---
 
-| Var | Default | Purpose |
-|---|---|---|
-| `EQUISENSE_BASE_URL` | `http://localhost:8080` | Spring Boot app root |
-| `EQUISENSE_TIMEOUT_MS` | `90000` | Per-request timeout (research queries can take 30–90s) |
-| `EQUISENSE_MCP_TOKEN` | **required** | HMAC bearer token. Treat like a password. |
+## Quick start
 
-### Minting the token
+### 1. Mint a token
 
-The token is the same shape as the user's `ES_AUTH` session cookie — it grants full session access for 90 days. Mint via the admin endpoint (admin-gated by the upstream nginx filter chain in prod; reachable on localhost in dev):
+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):
 
 ```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>",
@@ -47,22 +37,30 @@ Response:
 }
 ```
 
-**Security notes:**
+Copy the `token`. Treat it like a password.
 
-- The minted token IS a full session bearer credential. Anyone with it can act as that user for 90 days.
-- There is no per-token denylist in v1 — the only way to revoke is to wait 90 days or rotate the global `auth.token.secret` (which logs everyone out). Don't paste this token anywhere you wouldn't paste your account password.
-- Never commit the token. Never log it. Never paste it into chat.
+### 2. Register the MCP with Claude Code
 
-## Register with Claude Code
+**Recommended (npx, no install):**
 
 ```bash
 claude mcp add equisense-research --scope local \
-  --env EQUISENSE_BASE_URL=http://localhost:8080 \
-  --env EQUISENSE_MCP_TOKEN='<token from mint endpoint>' \
-  -- node /absolute/path/to/equity-sense/mcp-server/equisense-research/index.js
+  --env EQUISENSE_BASE_URL=https://equisense.ai \
+  --env EQUISENSE_MCP_TOKEN='<token from step 1>' \
+  -- npx -y equisense-research-mcp
 ```
 
-Verify:
+**Alternative (global install):**
+
+```bash
+npm install -g equisense-research-mcp
+claude mcp add equisense-research --scope local \
+  --env EQUISENSE_BASE_URL=https://equisense.ai \
+  --env EQUISENSE_MCP_TOKEN='<token>' \
+  -- equisense-research-mcp
+```
+
+### 3. Verify
 
 ```bash
 claude mcp list
@@ -70,32 +68,73 @@ claude mcp list
 
 Should show `equisense-research - ✓ Connected`.
 
-## First-run smoke test
+### 4. Try it
+
+In any Claude Code session:
 
-1. Make sure the Java app is running: `mvn spring-boot:run -Dspring-boot.run.profiles=dev`
-2. Mint a token for your test user (see above).
-3. Register the MCP with the minted token in the env.
-4. In Claude Code, ask: *"Use ask_research: bull case for OLAELEC."*
-5. Confirm a structured response with `answer`, `companyName`, `followUpQuestions` comes back.
-6. Confirm one `AI_EQUITY_RESEARCH` event lands in the user's metering ledger (the call is metered, same as the UI path).
+> Use ask_research: bull case for OLAELEC
 
-## Tests
+You should get back `{ answer, companyName, isin, detectedIntent, followUpQuestions, responseTimeMs }`.
+
+---
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `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. |
+
+## 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).
+- 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.
+
+---
+
+## Contributing / running from source
 
 ```bash
+git clone git@github.com:shivanshu-dixit/equity-sense.git
+cd equity-sense/mcp-server/equisense-research
+npm install
 npm test
 ```
 
-Runs Vitest:
-
-- `test/unit.test.js` — TOOLS shape, fetch body shape, HTTP error mapping (401/402/403/429/5xx)
+Tests:
+- `test/unit.test.js` — TOOLS shape, fetch body, HTTP error mapping (401/402/403/429/5xx)
 - `test/integration.test.js` — fail-fast on missing env, stdio handshake + `tools/list` RPC
 
+Local registration against from-source code (instead of npm):
+
+```bash
+claude mcp add equisense-research --scope local \
+  --env EQUISENSE_BASE_URL=http://localhost:8080 \
+  --env EQUISENSE_MCP_TOKEN='<token>' \
+  -- node /absolute/path/to/equity-sense/mcp-server/equisense-research/index.js
+```
+
+## Why Node?
+
+The Java app (Spring Boot 3.1) is too old for the Spring AI MCP server starter (needs 3.4+). All research logic, LLM routing, and feature metering stay server-side in Java; this wrapper just speaks MCP.
+
+---
+
 ## Troubleshooting
 
 | 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) ... EQUISENSE_MCP_TOKEN is expired or invalid` | Token > 90 days old OR `auth.token.secret` rotated | Re-mint and update the env |
+| `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 |
 | `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 Spring Boot logs |
+| 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
+
+MIT

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_research — 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,12 +37,18 @@ 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 askResearch is exercised directly in unit tests.
+let clientName = null;
+
 export const TOOLS = [
   {
     name: "ask_research",
@@ -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) {
@@ -163,7 +178,7 @@ function createServer() {
   const server = new Server(
     {
       name: "equisense-research",
-      version: "0.1.0",
+      version: "0.2.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,
   }));
@@ -200,11 +225,24 @@ function createServer() {
   return server;
 }
 
-// Only start the server when this file is the entrypoint. Lets the test suite
-// import TOOLS/askResearch without spawning a stdio server.
-const isEntrypoint =
-  import.meta.url === `file://${process.argv[1]}` ||
-  process.argv[1]?.endsWith("index.js");
+// Only start the server when this file is the entrypoint. Resolve symlinks on
+// both sides so the check survives npx, global bin installs, and pnpm shims.
+// Without realpath, a `bin` entry symlinked to index.js shows up in argv[1] as
+// `<cache>/.bin/equisense-research-mcp` — not ending in index.js — and the
+// server silently never starts.
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const isEntrypoint = (() => {
+  try {
+    if (!process.argv[1]) return false;
+    const thisFile = realpathSync(fileURLToPath(import.meta.url));
+    const argvFile = realpathSync(process.argv[1]);
+    return thisFile === argvFile;
+  } catch {
+    return false;
+  }
+})();
 
 if (isEntrypoint) {
   const server = createServer();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "equisense-research-mcp",
-  "version": "0.1.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 minted ES_AUTH bearer token.",
+  "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.",
   "type": "module",
   "main": "index.js",
   "bin": {