@stock2trend/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,300 @@
+# Stock2Trend MCP Server
+
+A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets an
+AI agent — Claude Desktop, Cursor, VS Code, or any MCP-compatible client — use **your**
+Stock2Trend account. Every request is forwarded to Stock2Trend's `agent-gateway` Edge
+Function using your **personal API key**, so your **Pro/Elite plan and daily limits are
+enforced server-side**.
+
+> This process stores **no** Stock2Trend or Supabase secrets. It only reads your API key
+> from an environment variable and runs locally on your machine. The key is never logged.
+
+---
+
+## Table of contents
+
+- [How it works](#how-it-works)
+- [Tools](#tools)
+- [Prerequisites](#prerequisites)
+- [1. Get your API key](#1-get-your-api-key)
+- [2. Install & build](#2-install--build)
+- [3. Configure your MCP client](#3-configure-your-mcp-client)
+- [Environment variables](#environment-variables)
+- [Verify it works (no AI client needed)](#verify-it-works-no-ai-client-needed)
+- [Tool reference](#tool-reference)
+- [How plans & limits work](#how-plans--limits-work)
+- [Security best practices](#security-best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Updating & rotating keys](#updating--rotating-keys)
+- [FAQ](#faq)
+- [Advanced: self-hosting the gateway](#advanced-self-hosting-the-gateway)
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[AI agent / MCP client] -->|stdio| B[Stock2Trend MCP server<br/>this package]
+    B -->|HTTPS + Bearer API key| C[agent-gateway<br/>Supabase Edge Function]
+    C --> D{API key valid?<br/>Pro/Elite?<br/>within daily limit?}
+    D -->|yes| E[Hot Stocks / Symbols / Options data]
+    D -->|no| F[401 / 403 / 429 error]
+```
+
+The MCP server is a thin bridge. **All security decisions happen in the gateway**, not here:
+key validation, plan gating (Pro/Elite only), per-action scopes, and quota consumption.
+
+---
+
+## Tools
+
+| Tool | What it does | Consumes quota? |
+|------|--------------|-----------------|
+| `get_hot_stocks` | Latest "Hot Stocks to Watch" (unusual options activity), optionally by price range | No — cached read |
+| `search_symbols` | Find US tickers by company name or keyword | No — read |
+| `analyze_options` | Single-stock options analysis (call/put flow, premium flow, IV, max pain, signals) | **Yes — 1 stock-analysis unit** from your daily plan limit |
+
+---
+
+## Prerequisites
+
+- **Node.js 18 or newer** (`node --version` to check)
+- A Stock2Trend **Pro** or **Elite** account (Basic/Free cannot create API keys)
+- A personal **API key** (next section)
+
+---
+
+## 1. Get your API key
+
+1. Sign in to Stock2Trend on the **web** (key management is web-only).
+2. Go to **Settings → Developer**.
+3. Click **Create key**, give it a name (e.g. `Claude desktop`), and **copy the key shown** —
+   it looks like `s2t_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
+
+> ⚠️ The full key is shown **only once**. Store it in a password manager. If you lose it,
+> just **rotate** or **create** a new one from the same screen.
+
+---
+
+## 2. Install & build
+
+```bash
+cd packages/mcp-server
+npm install      # installs @modelcontextprotocol/sdk + zod
+npm run build    # compiles src/ -> dist/index.js
+```
+
+After building, the runnable entry point is `dist/index.js`. Note its **absolute path** —
+you'll need it for your client config.
+
+---
+
+## 3. Configure your MCP client
+
+In every client you provide two things: the **command** to run this server and your
+**API key** as an environment variable.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "stock2trend": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
+      "env": {
+        "STOCK2TREND_API_KEY": "s2t_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the `stock2trend` tools appear.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`) using the **same shape**
+as above (`command`, `args`, `env`).
+
+### VS Code (MCP-enabled extensions)
+
+Add to your MCP config (`.vscode/mcp.json` or the extension's settings):
+
+```json
+{
+  "servers": {
+    "stock2trend": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
+      "env": { "STOCK2TREND_API_KEY": "s2t_live_your_key_here" }
+    }
+  }
+}
+```
+
+> **Windows paths in JSON:** use forward slashes (`C:/Users/you/.../dist/index.js`) or
+> escaped backslashes (`C:\\Users\\you\\...\\dist\\index.js`). A single backslash is invalid JSON.
+
+---
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STOCK2TREND_API_KEY` | **Yes** | — | Your personal key (`s2t_live_…`). The server exits immediately if missing. |
+| `STOCK2TREND_API_URL` | No | Production `agent-gateway` URL | Override only for staging/self-hosted gateways. |
+
+You can also create a `.env` from [`.env.example`](.env.example) for local runs, but most
+users set these in the **MCP client config** (`env` block) instead.
+
+---
+
+## Verify it works (no AI client needed)
+
+Sanity-check your key and the gateway directly, before wiring up any AI client.
+
+**PowerShell:**
+```powershell
+$key = 's2t_live_your_key_here'
+$uri = 'https://fhtslnidlypkdclqjjme.supabase.co/functions/v1/agent-gateway'
+Invoke-RestMethod -Method Post -Uri $uri `
+  -Headers @{ Authorization = "Bearer $key" } `
+  -ContentType 'application/json' -Body '{"action":"capabilities"}'
+```
+
+**curl:**
+```bash
+curl -s -X POST https://fhtslnidlypkdclqjjme.supabase.co/functions/v1/agent-gateway \
+  -H "Authorization: Bearer s2t_live_your_key_here" \
+  -H "Content-Type: application/json" \
+  -d '{"action":"capabilities"}'
+```
+
+A healthy response looks like:
+```json
+{ "success": true, "plan": "pro", "scopes": ["hot_stocks:read","symbols:read","options:read"], "tools": [ ... ] }
+```
+
+If you get `success: false` or a non-200 status, jump to [Troubleshooting](#troubleshooting).
+
+---
+
+## Tool reference
+
+### `get_hot_stocks`
+| Param | Type | Required | Notes |
+|-------|------|----------|-------|
+| `priceRange` | `"under10" \| "10to50" \| "over50"` | No | Omit to get all three ranges |
+| `limit` | number (1–50) | No | Max stocks per range (default 10) |
+
+Returns sanitized top stocks per range: `ticker`, `companyName`, `currentPrice`,
+`priceChangePct1d`, `sector`, `shareVolume`, `optionsVolume`, `heatLabel`, `totalScore`,
+reasons, plus `scanTimestamp`.
+
+### `search_symbols`
+| Param | Type | Required |
+|-------|------|----------|
+| `query` | string | Yes |
+
+Returns up to 15 matches: `symbol`, `name`, `type`, `region`, `currency`.
+
+### `analyze_options`  *(consumes 1 stock-analysis unit)*
+| Param | Type | Required |
+|-------|------|----------|
+| `ticker` | string (e.g. `AAPL`) | Yes |
+
+Returns analysis (price, call/put flow, premium flow, implied volatility, max pain,
+signals) **and** a `quota` object showing `used` / `limit` for the day.
+
+---
+
+## How plans & limits work
+
+- **Pro/Elite only.** Free/Basic keys are rejected with `403`.
+- **Shared daily budget.** The agent draws from the *same* daily limits as the Stock2Trend
+  app. If you've used analyses in the app, the agent has fewer left, and vice-versa.
+- **Reads are cheap.** `get_hot_stocks` and `search_symbols` don't consume your analysis
+  quota; only `analyze_options` does (1 unit each).
+- **Resets daily** at **00:00 UTC**. Elite plans are effectively unlimited.
+
+---
+
+## Security best practices
+
+- Treat the API key like a password. **Never commit it** to git or paste it in chats.
+- If a key leaks, **revoke** it instantly in **Settings → Developer** — the agent stops working immediately.
+- **Rotate** keys periodically (rotation revokes the old key and issues a new one).
+- This server exposes **only** the three read/analysis tools above. It cannot change your
+  account, billing, watchlist, or any data — by design.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Server exits with `FATAL: STOCK2TREND_API_KEY ... required` | Key env var not set | Add `STOCK2TREND_API_KEY` to the client `env` block (or `.env`) |
+| `401 Invalid, expired, or revoked API key` | Wrong/old key, or it was revoked/rotated | Create a fresh key in **Settings → Developer** and update your config |
+| `403 API access requires an active Pro or Elite plan` | Account isn't Pro/Elite (or downgraded/lapsed) | Upgrade/renew, then the same key works |
+| `429 Daily limit reached for stock analyses` | You've hit your plan's daily `analyze_options` limit (shared with the app) | Wait for the 00:00 UTC reset, or upgrade to Elite |
+| `401 { "code": "UNAUTHORIZED_INVALID_JWT_FORMAT", "message": "Invalid JWT" }` | Only when **self-hosting**: the gateway was deployed with JWT verification ON | Redeploy `agent-gateway` with `--no-verify-jwt` (see below) |
+| Tools don't appear in Claude/Cursor | Wrong path, missing build, or client not restarted | Confirm `dist/index.js` exists (run `npm run build`), use an **absolute** path, restart the client |
+| `Error: Cannot find module '@modelcontextprotocol/sdk'` | Dependencies not installed | Run `npm install` in `packages/mcp-server` |
+| `SyntaxError` / unexpected token at startup | Node too old | Use **Node 18+** (`node --version`) |
+| `Network error contacting Stock2Trend` | No internet, or wrong `STOCK2TREND_API_URL` | Check connectivity; unset `STOCK2TREND_API_URL` to use the default |
+| Client shows the server "running" but no output | Normal | The server logs to **stderr**; `stdout` is reserved for the MCP protocol stream |
+| Windows: config fails to load | Single backslashes in JSON path | Use `/` or `\\` in the `args` path |
+
+**Where to see logs:** this server writes diagnostics to **stderr** (your MCP client's
+log panel), never to stdout. To debug in a terminal:
+`STOCK2TREND_API_KEY=... node dist/index.js` and watch stderr.
+
+---
+
+## Updating & rotating keys
+
+- **Rotate** (recommended periodically): Settings → Developer → **Rotate**. This issues a
+  new key and revokes the old one. Update `STOCK2TREND_API_KEY` in your client config.
+- **Update the server**: `git pull`, then `npm install && npm run build` again.
+
+---
+
+## FAQ
+
+**Does the agent see my password or account?** No. It only ever has the API key, which
+grants the three read/analysis tools — nothing else.
+
+**Can I run multiple agents?** Yes. Issue a separate key per agent (up to 5 active) so you
+can revoke one without affecting the others.
+
+**Is my data shared with the AI provider?** Only the tool results you request are returned
+to your AI client. The MCP server itself sends nothing extra and logs no key.
+
+**Why is `analyze_options` sometimes slow?** It runs a live options analysis upstream; a
+few seconds is normal.
+
+---
+
+## Advanced: self-hosting the gateway
+
+If you point `STOCK2TREND_API_URL` at your **own** deployment of `agent-gateway`, that
+function must be deployed with JWT verification **disabled**, because it authenticates with
+the API key (not a Supabase JWT):
+
+```bash
+npx supabase functions deploy agent-gateway --project-ref <your-ref> --no-verify-jwt
+```
+
+Forgetting `--no-verify-jwt` produces the `Invalid JWT` 401 listed in Troubleshooting.
+
+---
+
+## Support
+
+Found a bug or have a feature request? Contact Stock2Trend support, or revoke your key and
+open an issue. Never include your API key in a bug report.

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Stock2Trend MCP server
+ * ----------------------
+ * A thin, user-run Model Context Protocol server that exposes a few Stock2Trend
+ * capabilities to an AI agent. It forwards every request to the Stock2Trend
+ * `agent-gateway` Edge Function using the user's personal API key, so all plan
+ * gating and daily limits are enforced server-side by Stock2Trend.
+ *
+ * This process holds NO Supabase secrets — only the user's API key, read from
+ * the STOCK2TREND_API_KEY environment variable. The key is never logged.
+ *
+ * Environment:
+ *   STOCK2TREND_API_KEY   (required)  e.g. s2t_live_...
+ *   STOCK2TREND_API_URL   (optional)  full URL of the agent-gateway function.
+ *                                     Default: https://<project>.supabase.co/functions/v1/agent-gateway
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_KEY = process.env.STOCK2TREND_API_KEY;
+const API_URL = process.env.STOCK2TREND_API_URL ||
+    'https://fhtslnidlypkdclqjjme.supabase.co/functions/v1/agent-gateway';
+if (!API_KEY) {
+    // Write to stderr (stdout is reserved for the MCP protocol stream).
+    console.error('FATAL: STOCK2TREND_API_KEY environment variable is required.');
+    process.exit(1);
+}
+async function callGateway(action, params = {}) {
+    let resp;
+    try {
+        resp = await fetch(API_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${API_KEY}`,
+            },
+            body: JSON.stringify({ action, ...params }),
+        });
+    }
+    catch (err) {
+        return { success: false, error: `Network error contacting Stock2Trend: ${err.message}` };
+    }
+    const json = (await resp.json().catch(() => ({})));
+    if (!resp.ok && json.success === undefined) {
+        return { success: false, error: `Stock2Trend returned HTTP ${resp.status}` };
+    }
+    return json;
+}
+function textResult(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+const server = new McpServer({
+    name: 'stock2trend',
+    version: '0.1.0',
+});
+server.tool('get_hot_stocks', 'Get Stock2Trend\'s latest "Hot Stocks to Watch" (unusual options activity). Optionally filter by price range. Read-only; does not consume your daily analysis quota.', {
+    priceRange: z.enum(['under10', '10to50', 'over50']).optional().describe('Optional price band filter'),
+    limit: z.number().int().min(1).max(50).optional().describe('Max stocks per range (default 10)'),
+}, async ({ priceRange, limit }) => {
+    const res = await callGateway('hot_stocks.snapshot', { priceRange, limit });
+    if (!res.success)
+        return errorResult(res.error || 'Failed to fetch hot stocks');
+    return textResult(res.data);
+});
+server.tool('search_symbols', 'Search for US stock ticker symbols by company name or keyword. Read-only; does not consume your daily analysis quota.', {
+    query: z.string().min(1).describe('Company name or partial ticker, e.g. "apple" or "NVDA"'),
+}, async ({ query }) => {
+    const res = await callGateway('symbols.search', { query });
+    if (!res.success)
+        return errorResult(res.error || 'Symbol search failed');
+    return textResult(res.data);
+});
+server.tool('analyze_options', 'Run Stock2Trend\'s single-stock options analysis for a ticker (call/put flow, premium flow, implied volatility, max pain, signals). Consumes one stock-analysis unit from your daily plan limit.', {
+    ticker: z.string().min(1).max(12).describe('US stock ticker, e.g. "AAPL"'),
+}, async ({ ticker }) => {
+    const res = await callGateway('options.analyze', { ticker });
+    if (!res.success) {
+        const quotaNote = res.quota ? ` (quota: ${JSON.stringify(res.quota)})` : '';
+        return errorResult((res.error || 'Analysis failed') + quotaNote);
+    }
+    return textResult({ analysis: res.data, quota: res.quota });
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Stock2Trend MCP server running (stdio).');
+}
+main().catch((err) => {
+    console.error('Fatal error starting Stock2Trend MCP server:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@stock2trend/mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Model Context Protocol (MCP) server that lets an AI agent use a Stock2Trend account (Hot Stocks, symbol search, options analysis) with the user's own plan limits.",
+  "license": "MIT",
+  "bin": {
+    "stock2trend-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}