equisense-research-mcp 0.1.0 → 0.1.1

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

@@ -200,11 +200,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,6 +1,6 @@
 {
   "name": "equisense-research-mcp",
-  "version": "0.1.0",
+  "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.",
   "type": "module",
   "main": "index.js",