equisense-research-mcp 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# equisense-research MCP server
+
+Thin Node.js wrapper that exposes the EquiSense AI equity-research endpoint as a single MCP tool:
+
+| 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. |
+
+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
+```
+
+## 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. |
+
+### Minting the 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):
+
+```bash
+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
+}
+```
+
+**Security notes:**
+
+- 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.
+
+## Register with Claude Code
+
+```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
+```
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+Should show `equisense-research - ✓ Connected`.
+
+## First-run smoke test
+
+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).
+
+## Tests
+
+```bash
+npm test
+```
+
+Runs Vitest:
+
+- `test/unit.test.js` — TOOLS shape, fetch body shape, HTTP error mapping (401/402/403/429/5xx)
+- `test/integration.test.js` — fail-fast on missing env, stdio handshake + `tools/list` RPC
+
+## 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 |
+| `AI_EQUITY_RESEARCH quota exhausted (HTTP 402)` | Daily quota hit | Wait until tomorrow OR upgrade the user's plan |
+| `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 |

package/index.js

@@ -0,0 +1,216 @@
+#!/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.
+//
+// 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.
+//
+// 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>' \
+//     -- node /abs/path/to/index.js
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const BASE_URL = process.env.EQUISENSE_BASE_URL || "http://localhost:8080";
+const REQUEST_TIMEOUT_MS = parseInt(
+  process.env.EQUISENSE_TIMEOUT_MS || "90000",
+  10,
+);
+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>.",
+  );
+  process.exit(1);
+}
+
+export const TOOLS = [
+  {
+    name: "ask_research",
+    description:
+      "Ask EquiSense's AI equity-research engine a natural-language question " +
+      "about an Indian-listed company (NSE/BSE). Returns the answer, the " +
+      "detected company, the inferred query intent, and follow-up question " +
+      "suggestions. Pass a stable session_id to preserve multi-turn context " +
+      "across calls.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Natural-language question. Examples: 'What's the bull case for OLAELEC?', " +
+            "'Compare margins of TCS vs Infosys.', 'Why did HDFC Bank stock fall last week?'",
+        },
+        isin: {
+          type: "string",
+          description:
+            "Optional 12-char ISIN to pin the answer to a specific security. " +
+            "If omitted, the backend infers the company from the query text.",
+        },
+        session_id: {
+          type: "string",
+          description:
+            "Stable identifier for the chat session. Pass the same value across " +
+            "follow-up calls so the backend can apply session memory.",
+        },
+      },
+    },
+  },
+];
+
+async function callRest(path, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${BASE_URL}${path}`, {
+      ...options,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Cookie: `ES_AUTH=${MCP_TOKEN}`,
+        ...(options.headers || {}),
+      },
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(formatHttpError(path, response.status, text));
+    }
+    return text ? JSON.parse(text) : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function formatHttpError(path, status, bodyText) {
+  const snippet = (bodyText || "").slice(0, 500);
+  if (status === 401) {
+    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."
+    );
+  }
+  if (status === 402) {
+    return (
+      "AI_EQUITY_RESEARCH quota exhausted (HTTP 402) calling " +
+      path +
+      ". Retry tomorrow or upgrade the plan. Body: " +
+      snippet
+    );
+  }
+  if (status === 429) {
+    return (
+      "Rate limited (HTTP 429) calling " +
+      path +
+      ". Retry after a short delay. Body: " +
+      snippet
+    );
+  }
+  if (status === 403) {
+    return (
+      "Forbidden (HTTP 403) calling " +
+      path +
+      ". The user this token represents may not have AI_EQUITY_RESEARCH access. " +
+      "Body: " +
+      snippet
+    );
+  }
+  return `EquiSense REST ${path} returned HTTP ${status}: ${snippet}`;
+}
+
+export async function askResearch(args) {
+  const body = {
+    query: args.query,
+    isin: args.isin ?? null,
+    sessionId: args.session_id ?? null,
+  };
+  const data = await callRest("/api/v1/research/ask", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+const TOOL_HANDLERS = {
+  ask_research: askResearch,
+};
+
+function createServer() {
+  const server = new Server(
+    {
+      name: "equisense-research",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const handler = TOOL_HANDLERS[name];
+    if (!handler) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    try {
+      return await handler(args);
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Tool ${name} failed: ${err.message}`,
+          },
+        ],
+      };
+    }
+  });
+
+  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");
+
+if (isEntrypoint) {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("equisense-research MCP server ready (stdio)");
+}
+
+export { createServer };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "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.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "equisense-research-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "equisense",
+    "equity-research",
+    "indian-stocks",
+    "claude",
+    "ai"
+  ],
+  "author": "EquiSense",
+  "license": "MIT",
+  "homepage": "https://equisense.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivanshu-dixit/equity-sense.git",
+    "directory": "mcp-server/equisense-research"
+  },
+  "bugs": {
+    "url": "https://github.com/shivanshu-dixit/equity-sense/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}