@nexvora/mcp-server 0.3.1

package/docs/setup/claude-code.md

@@ -0,0 +1,152 @@
+# Installing @nexvora/mcp-server in Claude Code
+
+This guide covers adding the NexVora MCP server to Claude Code so the 12 NexVora platform tools are available in every conversation.
+
+## Prerequisites
+
+- Claude Code installed (`npm install -g @anthropic-ai/claude-code` or the desktop app)
+- Node.js ≥ 18 on `PATH`
+- A NexVora account (free tier or above)
+
+## Step 1 — Authenticate
+
+### Option 1 — OAuth Device Grant (recommended)
+
+Run this once per machine to store your credentials in `~/.config/nexvora/config.json`:
+
+```bash
+npx @nexvora/mcp-server login
+```
+
+Follow the browser prompt to authorise. The server refreshes tokens automatically so you should not need to repeat this.
+
+### Option 2 — Personal Access Token
+
+If you cannot run an interactive browser flow (CI, headless servers, shared dev boxes), use a PAT instead:
+
+1. Open **https://app.nxvora.online/app/settings/mcp-tokens**.
+2. Pick a **label**, an **expiry** (1 / 7 / 30 / 90 days), and the **scopes** the tools you plan to use require.
+3. Click **Create token** and copy the resulting `nxv_pat_...` string — it is shown **once**.
+4. Paste it as `NEXVORA_ACCESS_TOKEN` in the `env` block of your `mcp.json` (see Step 2):
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"],
+      "env": {
+        "NEXVORA_ACCESS_TOKEN": "nxv_pat_..."
+      }
+    }
+  }
+}
+```
+
+The server auto-detects PATs by the `nxv_pat_` prefix — no other config change is needed. PATs do not auto-refresh; rotate them before they expire.
+
+## Step 2 — Add the server to Claude Code
+
+Claude Code reads MCP server configuration from two locations. Choose the one that fits your workflow:
+
+### Global (all projects)
+
+Create or edit `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"]
+    }
+  }
+}
+```
+
+### Per-project
+
+Create or edit `.claude/mcp.json` at the root of the repository:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"]
+    }
+  }
+}
+```
+
+Commit this file to share the configuration with your team.
+
+## Step 3 — Verify
+
+Start (or restart) Claude Code, then ask:
+
+```
+What NexVora tools do you have access to?
+```
+
+You should see a list of all 12 `nexvora_*` tools. Try a quick health check:
+
+```
+Check my NexVora wallet balance.
+```
+
+## Environment overrides
+
+Add an `env` object to the server entry for environment-specific settings:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"],
+      "env": {
+        "NEXVORA_API_URL": "https://staging.api.nxvora.online"
+      }
+    }
+  }
+}
+```
+
+## Using a local checkout instead of npm
+
+If you are developing the server itself or need an unreleased version:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "node",
+      "args": ["/absolute/path/to/nexvora-backend/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Run `npm run build` inside `mcp-server/` after any code changes.
+
+The same `env` block and token rules apply for the local-checkout path — set `NEXVORA_ACCESS_TOKEN` (PAT) or run `npx @nexvora/mcp-server login` (OAuth) exactly as for the npm path.
+
+## Troubleshooting
+
+**Tools do not appear after configuration**
+- Run `npx @nexvora/mcp-server` in a terminal to check for startup errors.
+- Confirm that `node --version` prints 18 or above.
+- On Windows, use the full path to `node.exe` if `npx` is not on `PATH` inside Claude Code.
+
+**"Not authenticated" errors**
+- Re-run `npx @nexvora/mcp-server login`.
+
+**"Your NexVora PAT was rejected — it has been revoked or expired"**
+- You're using a Personal Access Token and it's no longer valid. PATs do not auto-refresh — generate a new one at **https://app.nxvora.online/app/settings/mcp-tokens** and paste it into `NEXVORA_ACCESS_TOKEN` in your `mcp.json`.
+
+**"Your NexVora PAT is missing the required scope: `tool:...`"**
+- The PAT you're using does not include the scope the tool needs. The exact missing scope is in the error. Generate a new PAT with that scope ticked at **https://app.nxvora.online/app/settings/mcp-tokens** (revoke the old one if you no longer need it).
+
+**Multiple NexVora accounts**
+- Set `NEXVORA_CONFIG_PATH` to a different file path in the `env` block to point each project at a different credential file.

package/docs/setup/cursor.md

@@ -0,0 +1,129 @@
+# Installing @nexvora/mcp-server in Cursor
+
+This guide adds the NexVora MCP server to [Cursor](https://cursor.sh/) so the 12 NexVora platform tools are available in Cursor's AI chat.
+
+## Prerequisites
+
+- Cursor 0.40 or later (MCP support was introduced in 0.40)
+- Node.js ≥ 18 on `PATH`
+- A NexVora account (free tier or above)
+
+## Step 1 — Authenticate
+
+### Option 1 — OAuth Device Grant (recommended)
+
+Run this once per machine to store your credentials:
+
+```bash
+npx @nexvora/mcp-server login
+```
+
+### Option 2 — Personal Access Token
+
+If you cannot run an interactive browser flow (CI, headless servers, shared dev boxes), use a PAT instead:
+
+1. Open **https://app.nxvora.online/app/settings/mcp-tokens**.
+2. Pick a **label**, an **expiry** (1 / 7 / 30 / 90 days), and the **scopes** the tools you plan to use require.
+3. Click **Create token** and copy the resulting `nxv_pat_...` string — it is shown **once**.
+4. Paste it as `NEXVORA_ACCESS_TOKEN` in the `env` block of your `mcp.json` (see Step 3):
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"],
+      "env": {
+        "NEXVORA_ACCESS_TOKEN": "nxv_pat_..."
+      }
+    }
+  }
+}
+```
+
+The server auto-detects PATs by the `nxv_pat_` prefix — no other config change is needed. PATs do not auto-refresh; rotate them before they expire.
+
+## Step 2 — Open Cursor MCP settings
+
+1. Press `Cmd/Ctrl + Shift + P` and search for **"Open MCP Settings"**, or
+2. Go to **Cursor Settings → Features → MCP**.
+
+## Step 3 — Add the server
+
+In the MCP settings panel, click **Add new MCP server** and fill in:
+
+| Field | Value |
+|-------|-------|
+| Name | `nexvora` |
+| Type | `command` |
+| Command | `npx` |
+| Args | `-y @nexvora/mcp-server` |
+
+Or edit `~/.cursor/mcp.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"]
+    }
+  }
+}
+```
+
+### Per-project configuration
+
+Create `.cursor/mcp.json` at the root of your repository to scope the server to that project:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"]
+    }
+  }
+}
+```
+
+## Step 4 — Restart and verify
+
+1. Reload the Cursor window (`Cmd/Ctrl + Shift + P` → **Reload Window**).
+2. Open the Cursor Chat panel.
+3. Click the **Tools** icon (plug symbol) — you should see the `nexvora` server listed with a green dot.
+4. Test: ask Cursor to check your wallet balance.
+
+## Environment overrides
+
+```json
+{
+  "mcpServers": {
+    "nexvora": {
+      "command": "npx",
+      "args": ["-y", "@nexvora/mcp-server"],
+      "env": {
+        "NEXVORA_API_URL": "https://staging.api.nxvora.online"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**Server shows a red dot / error state**
+- Open Cursor's developer console (`Help → Toggle Developer Tools`) and check the MCP log tab.
+- Run `npx @nexvora/mcp-server` directly in a terminal to isolate startup errors.
+
+**"Not authenticated" errors**
+- Re-run `npx @nexvora/mcp-server login` and reload the window.
+
+**"Your NexVora PAT was rejected — it has been revoked or expired"**
+- You're using a Personal Access Token and it's no longer valid. PATs do not auto-refresh — generate a new one at **https://app.nxvora.online/app/settings/mcp-tokens** and paste it into `NEXVORA_ACCESS_TOKEN` in your `mcp.json`.
+
+**"Your NexVora PAT is missing the required scope: `tool:...`"**
+- The PAT you're using does not include the scope the tool needs. The exact missing scope is in the error. Generate a new PAT with that scope ticked at **https://app.nxvora.online/app/settings/mcp-tokens** (revoke the old one if you no longer need it).
+
+**Windows: `npx` not found**
+- Use the full path to `npx.cmd` or install Node.js and ensure `%AppData%\npm` is on `PATH`.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nexvora/mcp-server",
+  "version": "0.3.1",
+  "description": "NexVora MCP server — exposes platform tools to Claude and other LLM agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nexvora": "dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "nexvora",
+    "ai",
+    "agents"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "msw": "^2.14.4",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.4.0"
+  },
+  "jest": {
+    "preset": "ts-jest/presets/default-esm",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "testMatch": [
+      "**/*.test.ts",
+      "**/*.spec.ts"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "globals": {
+      "ts-jest": {
+        "useESM": true,
+        "isolatedModules": true
+      }
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/NexvoraClient.ts

@@ -0,0 +1,328 @@
+import { z } from "zod";
+
+import { type Config, type IConfigStore } from "./config.js";
+
+export type AuditOutcome = "success" | "error" | "rate_limited" | "unauthorized";
+
+const AuditPayloadSchema = z.object({
+  toolName: z.string().min(1),
+  outcome: z.enum(["success", "error", "rate_limited", "unauthorized"]),
+  agentId: z.string().uuid().optional(),
+  durationMs: z.number().int().positive().optional(),
+  errorCode: z.string().optional(),
+});
+
+export type AuditPayload = z.infer<typeof AuditPayloadSchema>;
+
+export interface NexvoraClientOptions {
+  /** Base URL of the NexVora backend (e.g. https://api.nxvora.online) */
+  baseUrl: string;
+  /** JWT access token for the authenticated user */
+  accessToken: string;
+  /** UUID of the donor agent making tool calls (optional) */
+  agentId?: string;
+  /**
+   * Optional config store for token-refresh support.
+   * When omitted the client uses the static accessToken only (no refresh).
+   */
+  configStore?: IConfigStore;
+}
+
+interface RefreshTokenResponse {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+/** Thrown when the refresh token itself is expired or revoked. */
+export class SessionExpiredError extends Error {
+  constructor() {
+    super(
+      "Your NexVora session has expired. Run `nexvora login` to reconnect.",
+    );
+    this.name = "SessionExpiredError";
+  }
+}
+
+/**
+ * Thrown when a PAT (Personal Access Token) is rejected as expired or revoked.
+ *
+ * <p>PATs do not refresh automatically — when one returns 401 the user must
+ * regenerate it from the web UI. The message includes the exact URL so the
+ * MCP host can surface it directly to the user without them having to dig.</p>
+ */
+export class PatRevokedOrExpiredError extends Error {
+  constructor() {
+    super(
+      "Your NexVora PAT was rejected — it has been revoked or expired. " +
+        "Generate a new one at https://app.nxvora.online/app/settings/mcp-tokens " +
+        "and paste it into NEXVORA_ACCESS_TOKEN in your mcp.json.",
+    );
+    this.name = "PatRevokedOrExpiredError";
+  }
+}
+
+/**
+ * Thrown when the backend returns 403 with type=pat-scope-missing, indicating
+ * the PAT is valid but is not authorised for the tool the user just invoked.
+ *
+ * <p>The exact missing scope is included so the MCP host can render an
+ * actionable "add tool:foo to your PAT" message.</p>
+ */
+export class PatScopeMissingError extends Error {
+  constructor(public readonly requiredScope: string) {
+    super(
+      `Your NexVora PAT is missing the required scope: ${requiredScope}. ` +
+        "Generate a new PAT with this scope checked at " +
+        "https://app.nxvora.online/app/settings/mcp-tokens.",
+    );
+    this.name = "PatScopeMissingError";
+  }
+}
+
+/** Wire-format prefix that identifies a PAT (as opposed to a session JWT). */
+const PAT_PREFIX = "nxv_pat_";
+
+/** {@code true} if the supplied access token is a Personal Access Token. */
+function isPat(accessToken: string): boolean {
+  return accessToken.startsWith(PAT_PREFIX);
+}
+
+/**
+ * Thin HTTP client for the NexVora backend.
+ *
+ * When constructed with a {@link IConfigStore} it automatically refreshes
+ * expired access tokens — proactively (60 s before expiry) and reactively
+ * (on a first 401). Only one refresh round-trip is made even when concurrent
+ * requests all receive a 401 at the same time.
+ */
+export class NexvoraClient {
+  private readonly baseUrl: string;
+  private accessToken: string;
+  readonly agentId?: string;
+  private readonly configStore?: IConfigStore;
+
+  /** Guards against concurrent refresh requests — shared across all in-flight calls. */
+  private refreshPromise: Promise<void> | null = null;
+
+  constructor(options: NexvoraClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.accessToken = options.accessToken;
+    this.agentId = options.agentId;
+    this.configStore = options.configStore;
+  }
+
+  private authHeaders(): Record<string, string> {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.accessToken}`,
+    };
+  }
+
+  // ── Token refresh ──────────────────────────────────────────────────────────
+
+  private async ensureTokenFresh(): Promise<void> {
+    // PATs never refresh — their lifetime is exactly the expiry on the
+    // mcp_pats row. Trying to /auth/refresh with a PAT would fail and
+    // confuse the user with a misleading "session expired" error.
+    if (isPat(this.accessToken)) return;
+    if (!this.configStore) return;
+    let config: Config;
+    try {
+      config = this.configStore.read();
+    } catch {
+      return; // no config file yet — continue with the static token
+    }
+    const nowSecs = Math.floor(Date.now() / 1000);
+    if (config.expiresAt < nowSecs + 60) {
+      await this.triggerRefresh(config);
+    }
+  }
+
+  /**
+   * Ensures only one refresh is in-flight at a time.
+   * Concurrent callers await the same promise.
+   */
+  private triggerRefresh(config?: Config): Promise<void> {
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.performRefresh(config).finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+    return this.refreshPromise;
+  }
+
+  private async performRefresh(existingConfig?: Config): Promise<void> {
+    if (!this.configStore) return;
+
+    let config: Config;
+    try {
+      config = existingConfig ?? this.configStore.read();
+    } catch {
+      throw new SessionExpiredError();
+    }
+
+    const response = await fetch(`${this.baseUrl}/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: config.refreshToken }),
+    });
+
+    if (!response.ok) {
+      throw new SessionExpiredError();
+    }
+
+    const { accessToken, refreshToken, expiresAt } =
+      (await response.json()) as RefreshTokenResponse;
+
+    this.accessToken = accessToken;
+    this.configStore.write({ ...config, accessToken, refreshToken, expiresAt });
+  }
+
+  // ── Core request dispatcher ────────────────────────────────────────────────
+
+  private async dispatchFetch(url: string, init: RequestInit): Promise<Response> {
+    await this.ensureTokenFresh();
+
+    let response = await fetch(url, { ...init, headers: this.authHeaders() });
+
+    if (response.status === 401) {
+      // PATs never refresh — a 401 means the token is revoked or expired.
+      // Surface a targeted error pointing at the regen URL rather than the
+      // generic "session expired, run nexvora login" message that suits
+      // JWT users.
+      if (isPat(this.accessToken)) {
+        throw new PatRevokedOrExpiredError();
+      }
+      // JWT path: try one refresh then retry the original request once.
+      if (this.configStore) {
+        await this.triggerRefresh();
+        response = await fetch(url, { ...init, headers: this.authHeaders() });
+      }
+    }
+
+    // 403 with type=pat-scope-missing carries the exact scope the PAT lacks.
+    // Pull it out so we can throw a typed error that downstream tools can
+    // render as "your PAT needs tool:foo — regenerate at <url>".
+    if (response.status === 403 && isPat(this.accessToken)) {
+      const scope = await readMissingScope(response);
+      if (scope != null) {
+        throw new PatScopeMissingError(scope);
+      }
+    }
+
+    return response;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Sends an audit event to {@code POST /mcp/audit} fire-and-forget.
+   * Errors are silently swallowed to prevent audit failures from affecting tool callers.
+   */
+  async sendAudit(payload: AuditPayload): Promise<void> {
+    try {
+      const validated = AuditPayloadSchema.parse(payload);
+      await fetch(`${this.baseUrl}/mcp/audit`, {
+        method: "POST",
+        headers: this.authHeaders(),
+        body: JSON.stringify(validated),
+      });
+    } catch {
+      // audit failures must not surface to the tool caller
+    }
+  }
+
+  /**
+   * Makes an authenticated POST request to the NexVora backend.
+   *
+   * @throws {NexvoraApiError} on non-2xx responses
+   * @throws {SessionExpiredError} when the refresh token is also expired
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    const response = await this.dispatchFetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new NexvoraApiError(response.status, text, path);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Makes an authenticated GET request to the NexVora backend.
+   *
+   * @throws {NexvoraApiError} on non-2xx responses
+   * @throws {SessionExpiredError} when the refresh token is also expired
+   */
+  async get<T>(path: string): Promise<T> {
+    const response = await this.dispatchFetch(`${this.baseUrl}${path}`, {});
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new NexvoraApiError(response.status, text, path);
+    }
+
+    return response.json() as Promise<T>;
+  }
+}
+
+/**
+ * Reads a 403 response body as RFC 7807 ProblemDetail and pulls the
+ * {@code required_scope} property out. Returns {@code null} for any other
+ * shape — the caller falls back to the generic error path.
+ *
+ * <p>The response body is consumed by this call; the dispatcher must not
+ * attempt to read it again. We clone first so the original {@link Response}
+ * remains usable if no scope is found.</p>
+ */
+async function readMissingScope(response: Response): Promise<string | null> {
+  try {
+    const cloned = response.clone();
+    const body = (await cloned.json()) as {
+      type?: string;
+      required_scope?: string;
+    };
+    if (
+      typeof body?.required_scope === "string" &&
+      body.type?.includes("pat-scope-missing")
+    ) {
+      return body.required_scope;
+    }
+  } catch {
+    // not JSON, or fetch couldn't be cloned — fall through
+  }
+  return null;
+}
+
+/**
+ * Represents a non-2xx response from the NexVora API.
+ */
+export class NexvoraApiError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    public readonly body: string,
+    public readonly path: string,
+  ) {
+    super(`NexVora API error ${statusCode} on ${path}: ${body}`);
+    this.name = "NexvoraApiError";
+  }
+
+  get isRateLimited(): boolean {
+    return this.statusCode === 429;
+  }
+
+  get isUnauthorized(): boolean {
+    return this.statusCode === 401 || this.statusCode === 403;
+  }
+
+  toAuditOutcome(): AuditOutcome {
+    if (this.isRateLimited) return "rate_limited";
+    if (this.isUnauthorized) return "unauthorized";
+    return "error";
+  }
+}