equisense-research-mcp 0.3.0 → 0.3.1

package/README.md

@@ -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
 ```
 
@@ -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_equisense` 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

@@ -178,7 +178,7 @@ function createServer() {
   const server = new Server(
     {
       name: "equisense-research",
-      version: "0.3.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,6 +1,6 @@
 {
   "name": "equisense-research-mcp",
-  "version": "0.3.0",
+  "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",