@kineviz/graphxr-mcp 0.2.0 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ MCP (Model Context Protocol) server for [GraphXR](https://graphxr.kineviz.com) -
 
 ### 1. Get Your API Key
 
-1. Log in to [GraphXR](https://graphxr.kineviz.com)
+1. Log in to GraphXR
 2. Click your profile icon in the top right
 3. Select "API Key" from the dropdown
 4. Copy your API key
@@ -48,7 +48,7 @@ Create or edit `.cursor/mcp.json` in your project or home directory:
   "mcpServers": {
     "graphxr": {
       "command": "npx",
-      "args": ["-y", "@kineviz/graphxr-mcp"],
+      "args": ["-y", "@kineviz/graphxr-mcp", "graphxr-mcp"],
       "env": {
         "GRAPHXR_API_KEY": "your-api-key-here",
         "GRAPHXR_URL": "https://graphxr.kineviz.com"
@@ -60,14 +60,14 @@ Create or edit `.cursor/mcp.json` in your project or home directory:
 
 #### Claude Desktop
 
-Add to your Claude Desktop configuration:
+Add to your Claude Desktop configuration (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "graphxr": {
       "command": "npx",
-      "args": ["-y", "@kineviz/graphxr-mcp"],
+      "args": ["-y", "@kineviz/graphxr-mcp", "graphxr-mcp"],
       "env": {
         "GRAPHXR_API_KEY": "your-api-key-here",
         "GRAPHXR_URL": "https://graphxr.kineviz.com"
@@ -82,9 +82,9 @@ Add to your Claude Desktop configuration:
 | 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 |
+| `GRAPHXR_URL` | No | `http://localhost:9000` | GraphXR server URL |
+| `GRAPHXR_HEADLESS` | No | `true` | Run browser in headless mode (set to `false` to see the browser) |
+| `DEBUG` or `GRAPHXR_DEBUG` | No | `false` | Enable debug logging |
 
 ## Available Tools
 
@@ -95,9 +95,8 @@ Once configured, you can ask Claude/Cursor to:
 - **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
+- **export_graph** - Export graph data as JSON, GraphXR, or CSV
+- **close_project** - Close the browser session
 
 ## Example Usage
 
@@ -134,11 +133,13 @@ Enable debug logging to see detailed output:
 ```json
 {
   "env": {
-    "DEBUG": "true"
+    "GRAPHXR_DEBUG": "true"
   }
 }
 ```
 
+You can also use `DEBUG=true` which works the same way.
+
 ## GraphXR API Reference
 
 The `run_javascript` tool executes code with access to the `gxr` global object. Here are common operations:
@@ -351,6 +352,38 @@ const projectName = gxr.getProjectName();
 
 For full API documentation, see the [GraphXR API Reference](https://graphxr.kineviz.com/docs).
 
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+yarn install
+
+# Build for development (with sourcemaps)
+yarn build:dev
+
+# Build for npm package
+yarn build
+```
+
+### Project Structure
+
+```
+graphxr-mcp/
+├── src/
+│   ├── index.ts           # Main MCP server
+│   ├── browser-session.ts # Playwright browser manager
+│   └── graphxr-client.ts  # REST API client
+├── scripts/
+│   ├── build.ts           # Dev build script
+│   └── build-package.js   # npm package build
+├── dist/                  # Build output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
 ## Publishing (for maintainers)
 
 ### Prerequisites
@@ -360,19 +393,43 @@ For full API documentation, see the [GraphXR API Reference](https://graphxr.kine
 
 ### First-time Setup
 
-Log in to npm with the @kineviz scope:
+1. **Create an npm account** (if you don't have one): https://www.npmjs.com/signup
+
+2. **Request access** to the `@kineviz` scope from a team administrator
+
+3. **Log in to npm** with the @kineviz scope:
 
 ```bash
 npm login --scope=@kineviz
 ```
 
-### Release Process
+This will prompt you for your npm username, password, and email. If you have 2FA enabled, you'll also need to enter a one-time password.
 
-From the `modules/mcp` directory:
+4. **Verify you're logged in**:
 
 ```bash
-cd modules/mcp
+npm whoami
+```
+
+This should display your npm username.
+
+### Before Each Release
+
+Verify your npm session is still active:
+
+```bash
+npm whoami
+```
+
+If you get an error, log in again:
 
+```bash
+npm login --scope=@kineviz
+```
+
+### Release Process
+
+```bash
 # Bump version and publish in one command
 npm version patch && yarn release   # 0.1.0 → 0.1.1 (bug fixes)
 npm version minor && yarn release   # 0.1.0 → 0.2.0 (new features)

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -27,17 +28,17 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// index.ts
-var index_exports = {};
-__export(index_exports, {
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
   GraphXRMCPServer: () => GraphXRMCPServer
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_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
+// src/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) {
@@ -46,6 +47,8 @@ function debug(...args) {
   }
 }
 var GraphXRClient = class {
+  baseUrl;
+  apiKey;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.apiKey = config.apiKey;
@@ -180,7 +183,7 @@ var GraphXRClient = class {
   }
 };
 
-// browser-session.ts
+// src/browser-session.ts
 var import_playwright = require("playwright");
 var DEBUG2 = process.env.DEBUG === "true" || process.env.GRAPHXR_DEBUG === "true";
 function debug2(...args) {
@@ -189,11 +192,13 @@ function debug2(...args) {
   }
 }
 var BrowserSession = class {
+  client;
+  config;
+  browser = null;
+  context = null;
+  page = null;
+  currentProject = null;
   constructor(client, config = {}) {
-    this.browser = null;
-    this.context = null;
-    this.page = null;
-    this.currentProject = null;
     this.client = client;
     this.config = {
       headless: config.headless ?? true,
@@ -449,7 +454,7 @@ var BrowserSession = class {
   }
 };
 
-// index.ts
+// src/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";
@@ -572,9 +577,10 @@ The code should return a value that can be serialized to JSON.`,
   }
 ];
 var GraphXRMCPServer = class {
+  server;
+  client = null;
+  browserSession = null;
   constructor() {
-    this.client = null;
-    this.browserSession = null;
     this.server = new import_server.Server(
       {
         name: "graphxr-mcp-server",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kineviz/graphxr-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for GraphXR - enables Claude/Cursor to create graph visualizations",
   "bin": {
     "graphxr-mcp": "./dist/index.js"
@@ -10,7 +10,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "node build-package.js",
+    "build": "node scripts/build-package.js",
+    "build:dev": "tsx scripts/build.ts",
     "prepublishOnly": "yarn build",
     "release": "yarn build && npm publish --access public"
   },
@@ -19,6 +20,12 @@
     "playwright": "^1.53.1",
     "node-fetch": "^2.7.0"
   },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.20.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
@@ -27,7 +34,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kineviz/graphxr.git"
+    "url": "git+https://github.com/kineviz/graphxr-mcp.git"
   },
   "keywords": [
     "mcp",