@kineviz/graphxr-mcp 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# @kineviz/graphxr-mcp
+
+> **ALPHA SOFTWARE - EXPERIMENTAL**
+>
+> This MCP server is in early alpha stage. APIs may change without notice. Do not use in production environments. Use at your own risk.
+
+MCP (Model Context Protocol) server for [GraphXR](https://graphxr.kineviz.com) - enables Claude and Cursor to create graph visualizations programmatically.
+
+## Features
+
+- Create and manage GraphXR projects
+- Execute JavaScript using the GraphXR API (`gxr`)
+- Take screenshots of graph visualizations
+- Export graph data
+- Clear and manipulate graph canvas
+
+## Prerequisites
+
+- Node.js 18 or later
+- A GraphXR account with an API key
+- Playwright Chromium browser (installed automatically or manually)
+
+## Quick Start
+
+### 1. Get Your API Key
+
+1. Log in to [GraphXR](https://graphxr.kineviz.com)
+2. Click your profile icon in the top right
+3. Select "API Key" from the dropdown
+4. Copy your API key
+
+### 2. Install Playwright Browser
+
+The MCP server uses Playwright to interact with GraphXR. You need to install the Chromium browser:
+
+```bash
+npx playwright install chromium
+```
+
+### 3. Configure Your MCP Client
+
+#### Cursor IDE
+
+Create or edit `.cursor/mcp.json` in your project or home directory:
+
+```json
+{
+  "mcpServers": {
+    "graphxr": {
+      "command": "npx",
+      "args": ["-y", "@kineviz/graphxr-mcp"],
+      "env": {
+        "GRAPHXR_API_KEY": "your-api-key-here",
+        "GRAPHXR_URL": "https://graphxr.kineviz.com"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "graphxr": {
+      "command": "npx",
+      "args": ["-y", "@kineviz/graphxr-mcp"],
+      "env": {
+        "GRAPHXR_API_KEY": "your-api-key-here",
+        "GRAPHXR_URL": "https://graphxr.kineviz.com"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GRAPHXR_API_KEY` | Yes | - | Your GraphXR API key |
+| `GRAPHXR_URL` | No | `https://graphxr.kineviz.com` | GraphXR server URL |
+| `HEADLESS` | No | `true` | Run browser in headless mode |
+| `DEBUG` | No | `false` | Enable debug logging |
+
+## Available Tools
+
+Once configured, you can ask Claude/Cursor to:
+
+- **list_projects** - List all your GraphXR projects
+- **create_project** - Create a new project
+- **open_project** - Open a project in the browser session
+- **run_javascript** - Execute JavaScript code using the `gxr` API
+- **screenshot** - Take a screenshot of the current graph
+- **export_graph** - Export graph data as JSON
+- **clear_graph** - Clear all nodes and edges from the graph
+- **close_browser** - Close the browser session
+
+## Example Usage
+
+Ask Claude or Cursor:
+
+> "Create a new GraphXR project called 'My Network' and add some sample nodes"
+
+> "Take a screenshot of the current graph"
+
+> "Run this JavaScript to create 5 connected nodes"
+
+## Troubleshooting
+
+### "Playwright browser not found"
+
+Run `npx playwright install chromium` to install the required browser.
+
+### "API key invalid"
+
+1. Verify your API key is correct
+2. Check that your GraphXR account is active
+3. Ensure the `GRAPHXR_URL` matches your GraphXR server
+
+### "Connection refused"
+
+1. Check your internet connection
+2. Verify the `GRAPHXR_URL` is accessible
+3. Check if GraphXR is experiencing downtime
+
+### Debug Mode
+
+Enable debug logging to see detailed output:
+
+```json
+{
+  "env": {
+    "DEBUG": "true"
+  }
+}
+```
+
+## GraphXR API Reference
+
+The `run_javascript` tool executes code with access to the `gxr` global object. Common operations:
+
+```javascript
+// Add a node
+gxr.add({ nodes: [{ category: 'Person', properties: { name: 'Alice' } }] });
+
+// Get all nodes
+const nodes = gxr.getNodes();
+
+// Run a layout
+gxr.layout.spring();
+
+// Take a screenshot (returns base64)
+const screenshot = await gxr.screenshot();
+```
+
+For full API documentation, see the [GraphXR API Reference](https://graphxr.kineviz.com/docs).
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, contact [Kineviz](https://kineviz.com).

package/dist/index.js

@@ -0,0 +1,870 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  GraphXRMCPServer: () => GraphXRMCPServer
+});
+module.exports = __toCommonJS(index_exports);
+var import_server = require("@modelcontextprotocol/sdk/server/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
+
+// graphxr-client.ts
+var import_node_fetch = __toESM(require("node-fetch"));
+var DEBUG = process.env.DEBUG === "true" || process.env.GRAPHXR_DEBUG === "true";
+function debug(...args) {
+  if (DEBUG) {
+    console.error("[GraphXR Client]", (/* @__PURE__ */ new Date()).toISOString(), ...args);
+  }
+}
+var GraphXRClient = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Make an authenticated request to the GraphXR API
+   */
+  async request(method, endpoint, body) {
+    const url = `${this.baseUrl}${endpoint}`;
+    debug("request:", method, url);
+    debug("request: body =", body ? JSON.stringify(body) : "(none)");
+    const headers = {
+      "Content-Type": "application/json",
+      "x-api-key": this.apiKey
+    };
+    const options = {
+      method,
+      headers
+    };
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+    debug("request: sending...");
+    const response = await (0, import_node_fetch.default)(url, options);
+    debug("request: response status =", response.status, response.statusText);
+    if (!response.ok) {
+      const errorText = await response.text();
+      debug("request: error response body =", errorText);
+      throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    debug("request: response data.status =", data.status, "message =", data.message);
+    if (data.status !== 0) {
+      throw new Error(`API error: ${data.message}`);
+    }
+    return data;
+  }
+  /**
+   * Verify the API key is valid by making a test request
+   */
+  async verifyApiKey() {
+    try {
+      await this.listProjects();
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * List all projects accessible to the authenticated user
+   */
+  async listProjects() {
+    debug("listProjects: calling API");
+    const response = await this.request(
+      "POST",
+      "/api/graph/neo4j/project/list",
+      {}
+    );
+    debug("listProjects: got", response.content?.length ?? 0, "projects");
+    return response.content || [];
+  }
+  /**
+   * Get detailed information about a specific project
+   */
+  async getProject(projectId) {
+    try {
+      const response = await this.request(
+        "GET",
+        `/api/graph/neo4j/project/getInfo?id=${encodeURIComponent(projectId)}`
+      );
+      return response.content || null;
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Create a new project
+   */
+  async createProject(options) {
+    const dbinfo = {
+      projectName: options.projectName,
+      databaseType: options.databaseType || "kuzu",
+      isShare: options.isShare ?? true,
+      hostname: "",
+      isLocal: false
+    };
+    const response = await this.request(
+      "POST",
+      "/api/graph/neo4j/project/add",
+      { dbinfo }
+    );
+    if (!response.content) {
+      throw new Error("Failed to create project: no content returned");
+    }
+    return response.content;
+  }
+  /**
+   * Delete a project
+   */
+  async deleteProject(projectId) {
+    await this.request(
+      "POST",
+      "/api/graph/neo4j/project/delete",
+      { id: projectId }
+    );
+  }
+  /**
+   * Get the URL to access a project in the browser
+   */
+  getProjectUrl(project) {
+    const encodedName = encodeURIComponent(project.projectName);
+    return `${this.baseUrl}/p/${project._id}/${encodedName}`;
+  }
+  /**
+   * Get the URL to access a project with API key authentication
+   */
+  getProjectUrlWithAuth(project) {
+    const baseProjectUrl = this.getProjectUrl(project);
+    return `${baseProjectUrl}?apiKey=${encodeURIComponent(this.apiKey)}`;
+  }
+  /**
+   * Get the base URL of the GraphXR instance
+   */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  /**
+   * Get the API key (for passing to browser sessions)
+   */
+  getApiKey() {
+    return this.apiKey;
+  }
+};
+
+// browser-session.ts
+var import_playwright = require("playwright");
+var DEBUG2 = process.env.DEBUG === "true" || process.env.GRAPHXR_DEBUG === "true";
+function debug2(...args) {
+  if (DEBUG2) {
+    console.error("[Browser Session]", (/* @__PURE__ */ new Date()).toISOString(), ...args);
+  }
+}
+var BrowserSession = class {
+  constructor(client, config = {}) {
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+    this.currentProject = null;
+    this.client = client;
+    this.config = {
+      headless: config.headless ?? true,
+      timeout: config.timeout ?? 6e4
+    };
+  }
+  /**
+   * Check if the browser session is active
+   */
+  isActive() {
+    return this.browser !== null && this.page !== null;
+  }
+  /**
+   * Get the currently open project
+   */
+  getCurrentProject() {
+    return this.currentProject;
+  }
+  /**
+   * Launch the browser and open a project
+   */
+  async openProject(project) {
+    if (this.isActive()) {
+      await this.close();
+    }
+    debug2("Launching browser, headless:", this.config.headless);
+    this.browser = await import_playwright.chromium.launch({
+      headless: this.config.headless
+    });
+    this.context = await this.browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      ignoreHTTPSErrors: true
+    });
+    this.page = await this.context.newPage();
+    await this.setupApiKeyInjection();
+    const projectUrl = this.client.getProjectUrl(project);
+    debug2("Navigating to project:", projectUrl);
+    await this.page.goto(projectUrl, {
+      waitUntil: "networkidle",
+      timeout: this.config.timeout
+    });
+    await this.waitForGraphXRReady();
+    this.currentProject = project;
+    debug2("Project opened successfully:", project.projectName);
+  }
+  /**
+   * Set up route interception to automatically inject API key for same-origin requests.
+   * This ensures all requests to the GraphXR server are authenticated without
+   * leaking the API key to external services.
+   */
+  async setupApiKeyInjection() {
+    if (!this.page) {
+      throw new Error("No active page");
+    }
+    const graphxrOrigin = new URL(this.client.getBaseUrl()).origin;
+    const apiKey = this.client.getApiKey();
+    debug2("Setting up API key injection for origin:", graphxrOrigin);
+    await this.page.route("**/*", async (route) => {
+      const request = route.request();
+      const requestUrl = request.url();
+      let requestOrigin;
+      try {
+        requestOrigin = new URL(requestUrl).origin;
+      } catch {
+        debug2("Could not parse URL, passing through:", requestUrl);
+        await route.continue();
+        return;
+      }
+      if (requestOrigin === graphxrOrigin) {
+        const existingHeaders = request.headers();
+        if (!existingHeaders["x-api-key"]) {
+          debug2("Injecting API key for:", requestUrl);
+          await route.continue({
+            headers: {
+              ...existingHeaders,
+              "x-api-key": apiKey
+            }
+          });
+        } else {
+          debug2("API key already present, passing through:", requestUrl);
+          await route.continue();
+        }
+      } else {
+        debug2("External request, passing through:", requestUrl);
+        await route.continue();
+      }
+    });
+  }
+  /**
+   * Wait for GraphXR to be fully loaded and ready
+   */
+  async waitForGraphXRReady() {
+    if (!this.page) {
+      throw new Error("No active page");
+    }
+    await this.page.waitForFunction(
+      () => {
+        const win = window;
+        return win.gxr && typeof win.gxr === "function";
+      },
+      { timeout: this.config.timeout }
+    );
+    await this.page.waitForFunction(
+      () => {
+        const win = window;
+        return win.gxr && win.gxr.isCanvasLoaded && win.gxr.isCanvasLoaded();
+      },
+      { timeout: this.config.timeout }
+    );
+    await this.page.waitForTimeout(1e3);
+  }
+  /**
+   * Execute JavaScript code in the GraphXR context
+   */
+  async executeJavaScript(code) {
+    if (!this.page) {
+      return {
+        success: false,
+        error: "No active browser session. Call openProject first."
+      };
+    }
+    try {
+      const result = await this.page.evaluate(async (jsCode) => {
+        const win = window;
+        const gxr = win.gxr;
+        if (!gxr) {
+          throw new Error("GraphXR API (gxr) not available");
+        }
+        const AsyncFunction = Object.getPrototypeOf(async function() {
+        }).constructor;
+        const fn = new AsyncFunction("gxr", jsCode);
+        return await fn(gxr);
+      }, code);
+      return {
+        success: true,
+        result
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  /**
+   * Take a screenshot of the GraphXR canvas
+   */
+  async screenshot(options = {}) {
+    if (!this.page) {
+      throw new Error("No active browser session. Call openProject first.");
+    }
+    const {
+      frameNodes = true,
+      hidePanels = true,
+      includeLegends = false,
+      format = "png",
+      quality = 1
+    } = options;
+    const base64Data = await this.page.evaluate(
+      async (opts) => {
+        const win = window;
+        const gxr = win.gxr;
+        if (!gxr || !gxr.screenshot) {
+          throw new Error("GraphXR screenshot API not available");
+        }
+        const blob = await gxr.screenshot({
+          frameNodes: opts.frameNodes,
+          hidePanels: opts.hidePanels,
+          includeLegends: opts.includeLegends,
+          format: opts.format,
+          quality: opts.quality
+        });
+        return new Promise((resolve, reject) => {
+          const reader = new FileReader();
+          reader.onloadend = () => {
+            const result = reader.result;
+            const base64 = result.split(",")[1];
+            resolve(base64);
+          };
+          reader.onerror = reject;
+          reader.readAsDataURL(blob);
+        });
+      },
+      { frameNodes, hidePanels, includeLegends, format, quality }
+    );
+    return Buffer.from(base64Data, "base64");
+  }
+  /**
+   * Export the graph data in the specified format
+   */
+  async exportGraph(options) {
+    if (!this.page) {
+      throw new Error("No active browser session. Call openProject first.");
+    }
+    const { format, filename } = options;
+    if (format === "json") {
+      const result = await this.executeJavaScript(`
+        const snapshot = gxr.snapshot();
+        return JSON.stringify(snapshot, null, 2);
+      `);
+      if (!result.success) {
+        throw new Error(`Export failed: ${result.error}`);
+      }
+      return {
+        data: result.result,
+        filename: filename || `graph-export-${Date.now()}.json`
+      };
+    }
+    const exportResult = await this.page.evaluate(
+      async (exportFormat) => {
+        const win = window;
+        const controller = win._app?.controller;
+        if (!controller || !controller.exportGraphXR) {
+          throw new Error("GraphXR export API not available");
+        }
+        const gxr = win.gxr;
+        const snapshot = gxr.snapshot();
+        return JSON.stringify(snapshot, null, 2);
+      },
+      format
+    );
+    return {
+      data: exportResult,
+      filename: filename || `graph-export-${Date.now()}.${format === "graphxr" ? "gxrf" : format}`
+    };
+  }
+  /**
+   * Clear the graph
+   */
+  async clearGraph() {
+    const result = await this.executeJavaScript("gxr.clear(); return true;");
+    if (!result.success) {
+      throw new Error(`Failed to clear graph: ${result.error}`);
+    }
+  }
+  /**
+   * Close the browser session
+   */
+  async close() {
+    if (this.page) {
+      await this.page.close();
+      this.page = null;
+    }
+    if (this.context) {
+      await this.context.close();
+      this.context = null;
+    }
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+    this.currentProject = null;
+  }
+};
+
+// index.ts
+var GRAPHXR_API_KEY = process.env.GRAPHXR_API_KEY || "";
+var GRAPHXR_URL = process.env.GRAPHXR_URL || "http://localhost:9000";
+var HEADLESS = process.env.GRAPHXR_HEADLESS !== "false";
+var DEBUG3 = process.env.DEBUG === "true" || process.env.GRAPHXR_DEBUG === "true";
+function debug3(...args) {
+  if (DEBUG3) {
+    console.error("[MCP DEBUG]", (/* @__PURE__ */ new Date()).toISOString(), ...args);
+  }
+}
+var tools = [
+  {
+    name: "list_projects",
+    description: "List all GraphXR projects accessible to the authenticated user",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: "create_project",
+    description: "Create a new GraphXR project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectName: {
+          type: "string",
+          description: "Name for the new project"
+        },
+        databaseType: {
+          type: "string",
+          description: "Database type (default: kuzu)",
+          enum: ["kuzu", "neo4j"]
+        }
+      },
+      required: ["projectName"]
+    }
+  },
+  {
+    name: "open_project",
+    description: "Open a GraphXR project in a headless browser session for interaction",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: {
+          type: "string",
+          description: "The project ID to open"
+        }
+      },
+      required: ["projectId"]
+    }
+  },
+  {
+    name: "run_javascript",
+    description: `Execute JavaScript code in the GraphXR canvas context using the gxr API.
+The code has access to the 'gxr' object which provides methods for:
+- Graph manipulation: gxr.addNode(), gxr.addEdge(), gxr.nodes(), gxr.edges(), gxr.clear()
+- Layout: gxr.forceLayout(), gxr.circle(), gxr.grid(), gxr.ego(), gxr.parametric()
+- Styling: gxr.colorNodesByProperty(), gxr.sizeNodesByProperty(), gxr.setCategoryColor()
+- Camera: gxr.flyToCenter(), gxr.zoomIn(), gxr.zoomOut()
+- Transform: gxr.extract(), gxr.link(), gxr.merge(), gxr.aggregate()
+- Query: gxr.query() for Cypher queries
+The code should return a value that can be serialized to JSON.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: {
+          type: "string",
+          description: "JavaScript code to execute. Has access to gxr API. Must return a value."
+        }
+      },
+      required: ["code"]
+    }
+  },
+  {
+    name: "screenshot",
+    description: "Take a screenshot of the GraphXR canvas",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frameNodes: {
+          type: "boolean",
+          description: "Whether to frame all nodes in view before capturing (default: true)"
+        },
+        hidePanels: {
+          type: "boolean",
+          description: "Whether to hide UI panels (default: true)"
+        },
+        includeLegends: {
+          type: "boolean",
+          description: "Whether to include legend overlays (default: false)"
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: "export_graph",
+    description: "Export the current graph data",
+    inputSchema: {
+      type: "object",
+      properties: {
+        format: {
+          type: "string",
+          description: "Export format",
+          enum: ["json", "graphxr", "csv"]
+        }
+      },
+      required: ["format"]
+    }
+  },
+  {
+    name: "close_project",
+    description: "Close the current browser session",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: []
+    }
+  }
+];
+var GraphXRMCPServer = class {
+  constructor() {
+    this.client = null;
+    this.browserSession = null;
+    this.server = new import_server.Server(
+      {
+        name: "graphxr-mcp-server",
+        version: "1.0.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupHandlers();
+  }
+  /**
+   * Initialize the GraphXR client with API key
+   */
+  initializeClient() {
+    if (!GRAPHXR_API_KEY) {
+      throw new Error(
+        "GRAPHXR_API_KEY environment variable is required. Generate an API key in GraphXR Settings > API Access."
+      );
+    }
+    if (!this.client) {
+      this.client = new GraphXRClient({
+        baseUrl: GRAPHXR_URL,
+        apiKey: GRAPHXR_API_KEY
+      });
+    }
+    return this.client;
+  }
+  /**
+   * Get or create the browser session
+   */
+  getBrowserSession() {
+    const client = this.initializeClient();
+    if (!this.browserSession) {
+      this.browserSession = new BrowserSession(client, {
+        headless: HEADLESS
+      });
+    }
+    return this.browserSession;
+  }
+  /**
+   * Setup MCP request handlers
+   */
+  setupHandlers() {
+    this.server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
+      return { tools };
+    });
+    this.server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      debug3("Tool call received:", name);
+      debug3("Tool arguments:", JSON.stringify(args));
+      try {
+        switch (name) {
+          case "list_projects":
+            return await this.handleListProjects();
+          case "create_project":
+            return await this.handleCreateProject(args);
+          case "open_project":
+            return await this.handleOpenProject(args);
+          case "run_javascript":
+            return await this.handleRunJavaScript(args);
+          case "screenshot":
+            return await this.handleScreenshot(args);
+          case "export_graph":
+            return await this.handleExportGraph(args);
+          case "close_project":
+            return await this.handleCloseProject();
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorStack = error instanceof Error ? error.stack : void 0;
+        debug3("Tool error:", errorMessage);
+        if (errorStack) {
+          debug3("Stack trace:", errorStack);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${errorMessage}`
+            }
+          ],
+          isError: true
+        };
+      }
+    });
+  }
+  /**
+   * Handle list_projects tool
+   */
+  async handleListProjects() {
+    debug3("handleListProjects: starting");
+    debug3("handleListProjects: GRAPHXR_URL =", GRAPHXR_URL);
+    debug3("handleListProjects: API key length =", GRAPHXR_API_KEY.length);
+    const client = this.initializeClient();
+    debug3("handleListProjects: client initialized");
+    debug3("handleListProjects: calling listProjects API...");
+    const projects = await client.listProjects();
+    debug3("handleListProjects: received", projects.length, "projects");
+    const projectList = projects.map((p) => ({
+      id: p._id,
+      name: p.projectName,
+      databaseType: p.databaseType,
+      isShare: p.isShare,
+      description: p.projectSettings?.description || ""
+    }));
+    debug3("handleListProjects: returning project list");
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(projectList, null, 2)
+        }
+      ]
+    };
+  }
+  /**
+   * Handle create_project tool
+   */
+  async handleCreateProject(args) {
+    const client = this.initializeClient();
+    const project = await client.createProject({
+      projectName: args.projectName,
+      databaseType: args.databaseType || "kuzu"
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: project._id,
+              name: project.projectName,
+              databaseType: project.databaseType,
+              url: client.getProjectUrl(project)
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+  /**
+   * Handle open_project tool
+   */
+  async handleOpenProject(args) {
+    const client = this.initializeClient();
+    const project = await client.getProject(args.projectId);
+    debug3("handleOpenProject: got project", project?._id, project?.projectName);
+    if (!project) {
+      throw new Error(`Project not found: ${args.projectId}`);
+    }
+    const session = this.getBrowserSession();
+    debug3("handleOpenProject: opening project in browser");
+    await session.openProject(project);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Opened project "${project.projectName}" (${project._id}). You can now run JavaScript code using the run_javascript tool.`
+        }
+      ]
+    };
+  }
+  /**
+   * Handle run_javascript tool
+   */
+  async handleRunJavaScript(args) {
+    const session = this.getBrowserSession();
+    if (!session.isActive()) {
+      throw new Error("No project is currently open. Use open_project first.");
+    }
+    const result = await session.executeJavaScript(args.code);
+    if (!result.success) {
+      throw new Error(result.error || "JavaScript execution failed");
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: result.result !== void 0 ? JSON.stringify(result.result, null, 2) : "Code executed successfully (no return value)"
+        }
+      ]
+    };
+  }
+  /**
+   * Handle screenshot tool
+   */
+  async handleScreenshot(args) {
+    const session = this.getBrowserSession();
+    if (!session.isActive()) {
+      throw new Error("No project is currently open. Use open_project first.");
+    }
+    const imageBuffer = await session.screenshot(args);
+    const base64Image = imageBuffer.toString("base64");
+    return {
+      content: [
+        {
+          type: "image",
+          data: base64Image,
+          mimeType: args.format === "jpeg" ? "image/jpeg" : "image/png"
+        }
+      ]
+    };
+  }
+  /**
+   * Handle export_graph tool
+   */
+  async handleExportGraph(args) {
+    const session = this.getBrowserSession();
+    if (!session.isActive()) {
+      throw new Error("No project is currently open. Use open_project first.");
+    }
+    const exportResult = await session.exportGraph({
+      format: args.format
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Export complete. Filename: ${exportResult.filename}
+
+Data:
+${exportResult.data}`
+        }
+      ]
+    };
+  }
+  /**
+   * Handle close_project tool
+   */
+  async handleCloseProject() {
+    if (this.browserSession) {
+      await this.browserSession.close();
+      this.browserSession = null;
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Browser session closed."
+        }
+      ]
+    };
+  }
+  /**
+   * Start the MCP server
+   */
+  async start() {
+    const transport = new import_stdio.StdioServerTransport();
+    await this.server.connect(transport);
+    process.on("SIGINT", async () => {
+      await this.cleanup();
+      process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+      await this.cleanup();
+      process.exit(0);
+    });
+  }
+  /**
+   * Cleanup resources
+   */
+  async cleanup() {
+    if (this.browserSession) {
+      await this.browserSession.close();
+    }
+  }
+};
+async function main() {
+  debug3("Starting GraphXR MCP Server");
+  debug3("Configuration:");
+  debug3("  GRAPHXR_URL:", GRAPHXR_URL);
+  debug3("  GRAPHXR_API_KEY:", GRAPHXR_API_KEY ? `(${GRAPHXR_API_KEY.length} chars)` : "(not set)");
+  debug3("  HEADLESS:", HEADLESS);
+  debug3("  DEBUG:", DEBUG3);
+  const server = new GraphXRMCPServer();
+  await server.start();
+  debug3("MCP Server started and listening on stdio");
+}
+main().catch((error) => {
+  console.error("Failed to start GraphXR MCP Server:", error);
+  process.exit(1);
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GraphXRMCPServer
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kineviz/graphxr-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for GraphXR - enables Claude/Cursor to create graph visualizations",
+  "bin": {
+    "graphxr-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build-package.js",
+    "prepublishOnly": "yarn build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "playwright": "^1.53.1",
+    "node-fetch": "^2.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineviz/graphxr.git"
+  },
+  "keywords": [
+    "mcp",
+    "graphxr",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "graph-visualization"
+  ],
+  "author": "Kineviz",
+  "license": "MIT"
+}