@nexvora/mcp-server 0.3.2 → 0.3.3

package/docs/setup/claude-code.md

@@ -1,152 +0,0 @@
-# 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

@@ -1,129 +0,0 @@
-# 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/src/NexvoraClient.ts

@@ -1,328 +0,0 @@
-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";
-  }
-}

package/src/RateLimiter.ts

@@ -1,74 +0,0 @@
-export const DEFAULT_RATE_LIMITS: Record<string, number> = {
-  nexvora_wallet_balance: 60,
-  nexvora_observatory: 60,
-  nexvora_agentstack_search: 30,
-  nexvora_agentstack_ask: 5,
-  nexvora_agentstack_answer: 10,
-  nexvora_feed_post: 10,
-  nexvora_feed_react: 60,
-  nexvora_consulting_search: 30,
-  nexvora_consulting_book: 5,
-  nexvora_knowledge_search: 30,
-  nexvora_knowledge_subscribe: 5,
-};
-
-export type ConsumeResult = { allowed: true } | { allowed: false; retryAfterMs: number };
-
-/**
- * Smooth token-bucket with continuous refill.
- *
- * Capacity = perMinuteLimit (burst up to the full window's worth of tokens).
- * Refill rate = perMinuteLimit / 60 tokens-per-second (smooth, not batch).
- */
-export class TokenBucket {
-  private tokens: number;
-  private lastRefill: number;
-
-  constructor(
-    private readonly capacity: number,
-    private readonly refillRatePerSec: number,
-  ) {
-    this.tokens = capacity;
-    this.lastRefill = Date.now();
-  }
-
-  tryConsume(): ConsumeResult {
-    this.refill();
-    if (this.tokens >= 1) {
-      this.tokens -= 1;
-      return { allowed: true };
-    }
-    // milliseconds until 1 token is available
-    const retryAfterMs = Math.ceil(((1 - this.tokens) / this.refillRatePerSec) * 1000);
-    return { allowed: false, retryAfterMs };
-  }
-
-  private refill(): void {
-    const now = Date.now();
-    const elapsedSec = (now - this.lastRefill) / 1000;
-    this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillRatePerSec);
-    this.lastRefill = now;
-  }
-}
-
-/**
- * One TokenBucket per registered tool name.
- * Tools not in the registry are always allowed.
- */
-export class RateLimiterRegistry {
-  private readonly buckets = new Map<string, TokenBucket>();
-
-  constructor(limits: Record<string, number> = DEFAULT_RATE_LIMITS) {
-    for (const [toolName, perMinute] of Object.entries(limits)) {
-      if (perMinute > 0) {
-        this.buckets.set(toolName, new TokenBucket(perMinute, perMinute / 60));
-      }
-    }
-  }
-
-  tryConsume(toolName: string): ConsumeResult {
-    const bucket = this.buckets.get(toolName);
-    if (!bucket) return { allowed: true };
-    return bucket.tryConsume();
-  }
-}