@nexvora/mcp-server 0.3.1 → 0.3.3

package/src/cache.ts

@@ -1,34 +0,0 @@
-/**
- * Minimal in-process TTL cache.
- *
- * Avoids hammering the backend when an LLM repeatedly calls the same read-only tool
- * within a short window. TTL is per-key; expired entries are evicted lazily on access.
- */
-export class TtlCache<V> {
-  private readonly store = new Map<string, { value: V; expiresAt: number }>();
-
-  constructor(private readonly ttlMs: number) {}
-
-  get(key: string): V | undefined {
-    const entry = this.store.get(key);
-    if (!entry) return undefined;
-    if (Date.now() > entry.expiresAt) {
-      this.store.delete(key);
-      return undefined;
-    }
-    return entry.value;
-  }
-
-  set(key: string, value: V): void {
-    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
-  }
-
-  /** Returns the cached value if fresh, otherwise calls {@code fn} and caches the result. */
-  async getOrFetch(key: string, fn: () => Promise<V>): Promise<V> {
-    const cached = this.get(key);
-    if (cached !== undefined) return cached;
-    const fresh = await fn();
-    this.set(key, fresh);
-    return fresh;
-  }
-}

package/src/cli.ts

@@ -1,171 +0,0 @@
-#!/usr/bin/env node
-/**
- * nexvora CLI
- *
- * Commands:
- *   nexvora login   [--server-url URL]              — OAuth Device Grant; stores tokens
- *   nexvora serve   [--transport stdio|sse]          — Start the MCP server
- *                   [--port PORT]                    — SSE listen port (default 7700)
- *                   [--server-url URL]               — NexVora API base URL
- *
- * When run with no arguments (or as a bin via "npx @nexvora/mcp-server") the
- * default behaviour is "serve --transport stdio", preserving backward compat
- * with existing Claude Code / Cursor configurations.
- */
-
-import { ConfigManager } from "./config.js";
-import { loginInteractive } from "./auth/oauth.js";
-
-// ── Argument parsing ──────────────────────────────────────────────────────────
-
-const args = process.argv.slice(2);
-
-function flag(name: string): string | undefined {
-  const idx = args.indexOf(name);
-  return idx >= 0 ? args[idx + 1] : undefined;
-}
-
-function hasFlag(name: string): boolean {
-  return args.includes(name);
-}
-
-const command = args[0] ?? "serve";
-
-// ── Command dispatch ──────────────────────────────────────────────────────────
-
-switch (command) {
-  case "login":
-    await runLogin();
-    break;
-
-  case "serve":
-  case "--transport": // allow "nexvora --transport sse" as shorthand
-    await runServe();
-    break;
-
-  case "--help":
-  case "-h":
-  case "help":
-    printHelp();
-    break;
-
-  default:
-    // Unknown first arg — treat the whole argv as a serve invocation
-    // (handles "nexvora" called with no subcommand from Claude Code)
-    await runServe();
-}
-
-// ── login ─────────────────────────────────────────────────────────────────────
-
-async function runLogin(): Promise<void> {
-  const serverUrl = flag("--server-url") ?? process.env["NEXVORA_BASE_URL"] ?? "https://api.nxvora.online";
-
-  console.error(`Authenticating with ${serverUrl} …`);
-
-  try {
-    const config = await loginInteractive(serverUrl);
-    const configManager = new ConfigManager();
-    configManager.write(config);
-    console.error(`\n✓ Logged in. Credentials stored in ~/.agentverse/config.json`);
-    console.error(`  User ID : ${config.userId || "(unknown)"}`);
-    console.error(`  Expires : ${new Date(config.expiresAt * 1000).toLocaleString()}`);
-  } catch (err) {
-    console.error(`\n✗ Login failed: ${(err as Error).message}`);
-    process.exit(1);
-  }
-}
-
-// ── serve ─────────────────────────────────────────────────────────────────────
-
-async function runServe(): Promise<void> {
-  const transport = flag("--transport") ?? "stdio";
-  const port = parseInt(flag("--port") ?? "7700", 10);
-  const serverUrl = flag("--server-url") ?? process.env["NEXVORA_BASE_URL"] ?? "https://api.nxvora.online";
-
-  if (transport === "sse") {
-    await serveSSE(serverUrl, port);
-  } else {
-    await serveStdio(serverUrl);
-  }
-}
-
-async function serveStdio(serverUrl: string): Promise<void> {
-  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
-  const { createServer } = await import("./createServer.js");
-
-  const accessToken = resolveToken();
-  const server = await createServer({ baseUrl: serverUrl, accessToken });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
-
-async function serveSSE(serverUrl: string, port: number): Promise<void> {
-  const { startSseServer } = await import("./server/sse.js");
-  const { createServer } = await import("./createServer.js");
-  const { ConfigManager } = await import("./config.js");
-
-  const accessToken = resolveToken();
-  const mcpServer = await createServer({ baseUrl: serverUrl, accessToken });
-
-  // Token validation: accept the token from config store or the env-var token
-  const configManager = new ConfigManager();
-  startSseServer({
-    port,
-    mcpServer,
-    nexvoraBaseUrl: serverUrl,
-    validateToken: async (bearerToken: string) => {
-      if (bearerToken === accessToken) return true;
-      try {
-        const config = configManager.read();
-        return config.accessToken === bearerToken;
-      } catch {
-        return false;
-      }
-    },
-  });
-}
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-/**
- * Resolve the access token in priority order:
- *   1. NEXVORA_ACCESS_TOKEN env var (CI / Docker)
- *   2. Token stored by `nexvora login` in ~/.agentverse/config.json
- */
-function resolveToken(): string {
-  const envToken = process.env["NEXVORA_ACCESS_TOKEN"];
-  if (envToken) return envToken;
-
-  try {
-    const config = new ConfigManager().read();
-    return config.accessToken;
-  } catch {
-    console.error(
-      "Error: no access token found.\n" +
-      "  • Run `nexvora login` to authenticate, or\n" +
-      "  • Set the NEXVORA_ACCESS_TOKEN environment variable.",
-    );
-    process.exit(1);
-  }
-}
-
-function printHelp(): void {
-  console.log(`
-nexvora — NexVora MCP server CLI
-
-Usage:
-  nexvora login   [--server-url URL]            Authenticate via OAuth (stores token)
-  nexvora serve   [--transport stdio|sse]        Start the MCP server (default: stdio)
-                  [--port PORT]                  SSE listen port (default: 7700)
-                  [--server-url URL]             NexVora API base URL
-
-Environment variables:
-  NEXVORA_ACCESS_TOKEN   Raw API token (bypasses stored credentials)
-  NEXVORA_BASE_URL       Override the default API base URL
-
-Examples:
-  nexvora login
-  nexvora serve --transport sse --port 7700
-  NEXVORA_ACCESS_TOKEN=tok nexvora serve --transport stdio
-`);
-}

package/src/config.ts

@@ -1,70 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-export interface Config {
-  accessToken: string;
-  refreshToken: string;
-  /** Unix epoch seconds */
-  expiresAt: number;
-  serverUrl: string;
-  userId: string;
-}
-
-/**
- * Abstraction over the config store so tools and tests can inject
- * an in-memory implementation without touching the filesystem.
- */
-export interface IConfigStore {
-  read(): Config;
-  write(config: Config): void;
-}
-
-/** Default path: ~/.agentverse/config.json */
-export function defaultConfigPath(): string {
-  return path.join(os.homedir(), ".agentverse", "config.json");
-}
-
-/**
- * Reads and writes ~/.agentverse/config.json.
- *
- * Writes are atomic on POSIX (write to .tmp, then rename).
- * On Windows the rename is not guaranteed atomic but is still safer than
- * a direct overwrite. File permissions are set to 0600 on POSIX after write.
- */
-export class ConfigManager implements IConfigStore {
-  constructor(private readonly configPath: string = defaultConfigPath()) {}
-
-  read(): Config {
-    const raw = fs.readFileSync(this.configPath, "utf8");
-    return JSON.parse(raw) as Config;
-  }
-
-  write(config: Config): void {
-    const dir = path.dirname(this.configPath);
-    fs.mkdirSync(dir, { recursive: true });
-
-    const content = JSON.stringify(config, null, 2);
-    const tmpPath = `${this.configPath}.tmp`;
-
-    fs.writeFileSync(tmpPath, content, { encoding: "utf8", mode: 0o600 });
-
-    try {
-      fs.renameSync(tmpPath, this.configPath);
-    } catch (err) {
-      // Windows: EEXIST when target exists (not atomic but acceptably safe)
-      if ((err as NodeJS.ErrnoException).code === "EEXIST") {
-        fs.rmSync(this.configPath, { force: true });
-        fs.renameSync(tmpPath, this.configPath);
-      } else {
-        fs.rmSync(tmpPath, { force: true });
-        throw err;
-      }
-    }
-
-    // Restrict permissions on POSIX (no-op on Windows)
-    if (process.platform !== "win32") {
-      fs.chmodSync(this.configPath, 0o600);
-    }
-  }
-}

package/src/createServer.ts

@@ -1,90 +0,0 @@
-/**
- * Factory that builds and returns a fully-configured McpServer with all 12
- * NexVora tools registered.
- *
- * Extracted from index.ts so it can be shared by both the stdio entry point
- * and the SSE HTTP server without duplication.
- */
-
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
-import { defineTool, type ToolDefinition } from "./defineTool.js";
-import { NexvoraClient } from "./NexvoraClient.js";
-import { DEFAULT_RATE_LIMITS, RateLimiterRegistry } from "./RateLimiter.js";
-import { nexvora_agentstack_answer } from "./tools/nexvora_agentstack_answer.js";
-import { nexvora_agentstack_ask } from "./tools/nexvora_agentstack_ask.js";
-import { nexvora_agentstack_search } from "./tools/nexvora_agentstack_search.js";
-import { nexvora_consulting_book } from "./tools/nexvora_consulting_book.js";
-import { nexvora_consulting_search } from "./tools/nexvora_consulting_search.js";
-import { nexvora_knowledge_search } from "./tools/nexvora_knowledge_search.js";
-import { nexvora_knowledge_subscribe } from "./tools/nexvora_knowledge_subscribe.js";
-import { nexvora_feed_post } from "./tools/nexvora_feed_post.js";
-import { nexvora_feed_react } from "./tools/nexvora_feed_react.js";
-import { nexvora_observatory } from "./tools/nexvora_observatory.js";
-import { nexvora_submit_task } from "./tools/nexvora_submit_task.js";
-import { nexvora_wallet_balance } from "./tools/nexvora_wallet_balance.js";
-
-const ALL_TOOLS = [
-  nexvora_submit_task,
-  nexvora_wallet_balance,
-  nexvora_observatory,
-  nexvora_agentstack_search,
-  nexvora_agentstack_ask,
-  nexvora_agentstack_answer,
-  nexvora_feed_post,
-  nexvora_feed_react,
-  nexvora_consulting_search,
-  nexvora_consulting_book,
-  nexvora_knowledge_search,
-  nexvora_knowledge_subscribe,
-];
-
-export interface CreateServerOptions {
-  baseUrl: string;
-  accessToken: string;
-  agentId?: string;
-}
-
-/**
- * Build a McpServer with all NexVora tools registered.
- * Fetches per-tool rate limits from the backend; silently falls back to
- * baked-in defaults if the network is unavailable.
- */
-export async function createServer(opts: CreateServerOptions): Promise<McpServer> {
-  const { baseUrl, accessToken, agentId } = opts;
-
-  const client = new NexvoraClient({ baseUrl, accessToken, agentId });
-
-  let rateLimitMap: Record<string, number> = DEFAULT_RATE_LIMITS;
-  try {
-    const fetched = await client.get<Record<string, number>>("/mcp/rate-limits");
-    rateLimitMap = { ...DEFAULT_RATE_LIMITS, ...fetched };
-  } catch {
-    // network failure or auth error — silently use defaults
-  }
-  const rateLimiter = new RateLimiterRegistry(rateLimitMap);
-
-  const server = new McpServer({
-    name: "@nexvora/mcp-server",
-    version: "0.3.1",
-  });
-
-  for (const tool of ALL_TOOLS) {
-    const wrappedHandler = defineTool(
-      tool as unknown as ToolDefinition<z.ZodTypeAny, unknown>,
-      client,
-      rateLimiter,
-    );
-    server.tool(
-      tool.name,
-      tool.description,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      tool.inputSchema.shape as any,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      wrappedHandler as any,
-    );
-  }
-
-  return server;
-}

package/src/defineTool.ts

@@ -1,120 +0,0 @@
-import { z } from "zod";
-
-import { NexvoraApiError, NexvoraClient } from "./NexvoraClient.js";
-import { type RateLimiterRegistry } from "./RateLimiter.js";
-
-export interface ToolDefinition<TInput extends z.ZodTypeAny, TOutput> {
-  name: string;
-  description: string;
-  inputSchema: TInput;
-  handler: (input: z.infer<TInput>, client: NexvoraClient) => Promise<TOutput>;
-}
-
-export interface ToolCallResult {
-  content: Array<{ type: "text"; text: string }>;
-  isError?: boolean;
-}
-
-/**
- * Wraps a raw tool handler with:
- * - Zod input validation
- * - Timing measurement
- * - Fire-and-forget audit to POST /mcp/audit
- * - Structured error handling with MCP-compatible result shape
- */
-export function defineTool<TInput extends z.ZodTypeAny, TOutput>(
-  definition: ToolDefinition<TInput, TOutput>,
-  client: NexvoraClient,
-  rateLimiter?: RateLimiterRegistry,
-): (rawInput: unknown) => Promise<ToolCallResult> {
-  return async (rawInput: unknown): Promise<ToolCallResult> => {
-    const start = Date.now();
-
-    if (rateLimiter) {
-      const result = rateLimiter.tryConsume(definition.name);
-      if (!result.allowed) {
-        const retrySec = (result.retryAfterMs / 1000).toFixed(1);
-        await client.sendAudit({
-          toolName: definition.name,
-          outcome: "rate_limited",
-          agentId: client.agentId,
-        });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Rate limit exceeded for ${definition.name}. Retry after ${retrySec} seconds.`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-
-    const parsed = definition.inputSchema.safeParse(rawInput);
-    if (!parsed.success) {
-      await client.sendAudit({
-        toolName: definition.name,
-        outcome: "error",
-        agentId: client.agentId,
-        errorCode: "VALIDATION_ERROR",
-      });
-      return {
-        content: [{ type: "text", text: `Invalid input: ${parsed.error.message}` }],
-        isError: true,
-      };
-    }
-
-    try {
-      const result = await definition.handler(parsed.data, client);
-      const durationMs = Date.now() - start;
-
-      await client.sendAudit({
-        toolName: definition.name,
-        outcome: "success",
-        agentId: client.agentId,
-        durationMs,
-      });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
-          },
-        ],
-      };
-    } catch (err) {
-      const durationMs = Date.now() - start;
-
-      if (err instanceof NexvoraApiError) {
-        await client.sendAudit({
-          toolName: definition.name,
-          outcome: err.toAuditOutcome(),
-          agentId: client.agentId,
-          durationMs,
-          errorCode: String(err.statusCode),
-        });
-
-        return {
-          content: [{ type: "text", text: err.message }],
-          isError: true,
-        };
-      }
-
-      await client.sendAudit({
-        toolName: definition.name,
-        outcome: "error",
-        agentId: client.agentId,
-        durationMs,
-        errorCode: "UNEXPECTED_ERROR",
-      });
-
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: `Unexpected error: ${message}` }],
-        isError: true,
-      };
-    }
-  };
-}

package/src/index.ts

@@ -1,36 +0,0 @@
-/**
- * Stdio entry point — backward-compatible with all existing Claude Code /
- * Cursor / ChatGPT Desktop configurations that launch the server as a
- * subprocess via "command" + "args".
- *
- * For the SSE (remote MCP) transport or the OAuth login command, use the
- * `nexvora` CLI (src/cli.ts → dist/cli.js).
- */
-
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-import { createServer } from "./createServer.js";
-
-const NEXVORA_BASE_URL = process.env["NEXVORA_BASE_URL"] ?? "https://api.nxvora.online";
-const NEXVORA_ACCESS_TOKEN = process.env["NEXVORA_ACCESS_TOKEN"] ?? "";
-const NEXVORA_AGENT_ID = process.env["NEXVORA_AGENT_ID"];
-
-if (!NEXVORA_ACCESS_TOKEN) {
-  console.error("Error: NEXVORA_ACCESS_TOKEN environment variable is required");
-  console.error("  Two ways to set it:");
-  console.error("    1. Run `nexvora login` (OAuth Device Grant — auto-refreshes)");
-  console.error("    2. Generate a Personal Access Token at");
-  console.error("       https://app.nxvora.online/app/settings/mcp-tokens and paste");
-  console.error("       the nxv_pat_... string into NEXVORA_ACCESS_TOKEN in your");
-  console.error("       mcp.json env block.");
-  process.exit(1);
-}
-
-const server = await createServer({
-  baseUrl: NEXVORA_BASE_URL,
-  accessToken: NEXVORA_ACCESS_TOKEN,
-  agentId: NEXVORA_AGENT_ID,
-});
-
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/src/server/sse.ts

@@ -1,149 +0,0 @@
-/**
- * HTTP + SSE transport for the NexVora MCP server.
- *
- * Exposes three endpoints:
- *   GET  /.well-known/oauth-authorization-server  — OAuth 2.0 discovery (RFC 8414)
- *   GET  /health                                  — liveness probe
- *   GET  /sse                                     — SSE stream (MCP transport)
- *   POST /messages?sessionId=<id>                 — MCP message delivery
- *
- * All /sse and /messages requests require a valid Bearer token in the
- * Authorization header.  The well-known and health endpoints are public.
- *
- * Usage:
- *   const server = startSseServer({ port: 7700, baseUrl, accessToken });
- *   // server is a Node http.Server — call server.close() to shut down
- */
-
-import * as http from "node:http";
-
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-export interface SseServerOptions {
-  port: number;
-  /** McpServer instance with all tools already registered. */
-  mcpServer: McpServer;
-  /** Base URL of the NexVora API — used to build OAuth discovery metadata. */
-  nexvoraBaseUrl: string;
-  /**
-   * Token validator.  Called with the raw Bearer token string on every
-   * authenticated request.  Return true to allow the request, false to 401.
-   *
-   * Default: always returns true (useful for local dev; override in production).
-   */
-  validateToken?: (token: string) => Promise<boolean>;
-}
-
-// ── OAuth 2.0 discovery metadata ──────────────────────────────────────────────
-
-function oauthMeta(nexvoraBaseUrl: string): Record<string, unknown> {
-  const base = nexvoraBaseUrl.replace(/\/$/, "");
-  return {
-    issuer: base,
-    authorization_endpoint: `${base}/oauth/authorize`,
-    token_endpoint: `${base}/oauth/token`,
-    response_types_supported: ["code"],
-    grant_types_supported: ["authorization_code", "refresh_token"],
-    code_challenge_methods_supported: ["S256"],
-    scopes_supported: ["mcp:tools", "offline_access"],
-    token_endpoint_auth_methods_supported: ["none"],
-  };
-}
-
-// ── Server factory ────────────────────────────────────────────────────────────
-
-export function startSseServer(opts: SseServerOptions): http.Server {
-  const { port, mcpServer, nexvoraBaseUrl } = opts;
-  const validateToken = opts.validateToken ?? (() => Promise.resolve(true));
-
-  // Map sessionId → SSEServerTransport (one entry per connected SSE client)
-  const sessions = new Map<string, SSEServerTransport>();
-
-  const server = http.createServer(async (req, res) => {
-    const origin = req.headers["origin"] ?? "*";
-    res.setHeader("Access-Control-Allow-Origin", origin);
-    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-
-    // Pre-flight
-    if (req.method === "OPTIONS") {
-      res.writeHead(204);
-      res.end();
-      return;
-    }
-
-    const url = new URL(req.url ?? "/", `http://localhost:${port}`);
-
-    // ── Public endpoints ───────────────────────────────────────────────────
-
-    if (url.pathname === "/.well-known/oauth-authorization-server" && req.method === "GET") {
-      const body = JSON.stringify(oauthMeta(nexvoraBaseUrl));
-      res.writeHead(200, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) });
-      res.end(body);
-      return;
-    }
-
-    if (url.pathname === "/health" && req.method === "GET") {
-      const body = JSON.stringify({ status: "ok", transport: "sse", sessions: sessions.size });
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(body);
-      return;
-    }
-
-    // ── Bearer-auth guard ──────────────────────────────────────────────────
-
-    const authHeader = req.headers["authorization"] ?? "";
-    if (!authHeader.startsWith("Bearer ")) {
-      jsonError(res, 401, "Bearer token required in Authorization header");
-      return;
-    }
-    const token = authHeader.slice(7);
-    const valid = await validateToken(token);
-    if (!valid) {
-      jsonError(res, 401, "Invalid or expired token");
-      return;
-    }
-
-    // ── SSE endpoint — one transport per client connection ─────────────────
-
-    if (url.pathname === "/sse" && req.method === "GET") {
-      const transport = new SSEServerTransport("/messages", res);
-      sessions.set(transport.sessionId, transport);
-      res.on("close", () => sessions.delete(transport.sessionId));
-      await mcpServer.connect(transport);
-      return;
-    }
-
-    // ── Message endpoint — client posts MCP messages here ─────────────────
-
-    if (url.pathname === "/messages" && req.method === "POST") {
-      const sessionId = url.searchParams.get("sessionId") ?? "";
-      const transport = sessions.get(sessionId);
-      if (!transport) {
-        jsonError(res, 404, `Session '${sessionId}' not found. Has the SSE connection been established?`);
-        return;
-      }
-      await transport.handlePostMessage(req, res);
-      return;
-    }
-
-    res.writeHead(404);
-    res.end();
-  });
-
-  server.listen(port, () => {
-    console.error(`NexVora MCP server (SSE) listening on http://localhost:${port}/sse`);
-    console.error(`OAuth discovery at http://localhost:${port}/.well-known/oauth-authorization-server`);
-  });
-
-  return server;
-}
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function jsonError(res: http.ServerResponse, status: number, message: string): void {
-  const body = JSON.stringify({ error: message });
-  res.writeHead(status, { "Content-Type": "application/json" });
-  res.end(body);
-}