@kineviz/graphxr-mcp 0.1.0 → 0.2.1

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"
@@ -67,7 +67,7 @@ Add to your Claude Desktop configuration:
   "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,7 +82,7 @@ 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 |
+| `GRAPHXR_URL` | No | `http://localhost:9000` | GraphXR server URL |
 | `HEADLESS` | No | `true` | Run browser in headless mode |
 | `DEBUG` | No | `false` | Enable debug logging |
 
@@ -141,24 +141,258 @@ Enable debug logging to see detailed output:
 
 ## GraphXR API Reference
 
-The `run_javascript` tool executes code with access to the `gxr` global object. Common operations:
+The `run_javascript` tool executes code with access to the `gxr` global object. Here are common operations:
+
+### Adding Nodes and Edges
+
+```javascript
+// Add a single node
+gxr.addNode({ id: "A", category: "Person", properties: { name: "Alice", age: 30 } });
+
+// Add multiple nodes
+gxr.addNodes([
+  { id: "A", category: "Person", properties: { name: "Alice" } },
+  { id: "B", category: "Person", properties: { name: "Bob" } }
+]);
+
+// Add an edge between nodes
+gxr.addEdge({ sourceId: "A", targetId: "B", relationship: "KNOWS" });
+
+// Add multiple edges
+gxr.addEdges([
+  { sourceId: "A", targetId: "B", relationship: "KNOWS" },
+  { sourceId: "B", targetId: "C", relationship: "KNOWS" }
+]);
+```
+
+### Generating Random Graphs
+
+```javascript
+// Generate a random graph
+gxr.randomGraph({
+  nodeCount: 100,
+  edgeCount: 200,
+  categories: ["Person", "Company"],
+  relationships: ["WORKS_FOR", "KNOWS"]
+});
+gxr.forceLayout();
+```
+
+### Working with Nodes and Edges
 
 ```javascript
-// Add a node
-gxr.add({ nodes: [{ category: 'Person', properties: { name: 'Alice' } }] });
+// Iterate over all nodes
+gxr.nodes().forEach(n => console.log(n.properties));
 
-// Get all nodes
-const nodes = gxr.getNodes();
+// Filter nodes by category
+gxr.nodes({ category: "Person" }).forEach(console.log);
 
-// Run a layout
-gxr.layout.spring();
+// Filter nodes by property
+gxr.nodes({ properties: { age: (age) => age > 30 } }).style('selected', true);
 
-// Take a screenshot (returns base64)
-const screenshot = await gxr.screenshot();
+// Select nodes
+gxr.selectNodes({ category: "Person" });
+gxr.selectNodes((n) => n.properties.age > 30);
+
+// Deselect all nodes
+gxr.deselectNodes();
+
+// Clear the graph
+gxr.clear();
+```
+
+### Layouts
+
+```javascript
+// Force-directed layout
+gxr.forceLayout();
+
+// Arrange nodes in a circle
+await gxr.circle();
+
+// Arrange nodes on a sphere
+await gxr.sphere();
+
+// Arrange nodes in a grid
+await gxr.grid();
+
+// Arrange nodes in a line
+await gxr.line();
+
+// Hierarchical tree layout from selected nodes
+await gxr.nodes({ category: "Root" }).ego({
+  depth: 3,
+  mode: 'tree',
+  orientation: 'down'
+});
+
+// Parametric layout by property values
+await gxr.parametric({
+  x: 'year',
+  y: 'revenue',
+  z: 0
+});
+```
+
+### Styling
+
+```javascript
+// Color nodes by a property
+gxr.colorNodesByProperty({ property: 'age', scale: 'BuGn' });
+
+// Color specific values
+gxr.colorNodesByProperty({
+  property: 'status',
+  colorMap: {
+    'active': '#00FF00',
+    'inactive': '#FF0000'
+  }
+});
+
+// Size nodes by property
+gxr.sizeNodesByProperty({ category: "Person", property: 'age' });
+
+// Set category color and icon
+gxr.setCategoryColor("Person", "#00ff00");
+gxr.setCategoryIconByName("Person", "person");
+
+// Set relationship color
+gxr.setRelationshipColor("KNOWS", "#0000ff");
+```
+
+### Camera Controls
+
+```javascript
+// Fly to center of all nodes
+gxr.flyToCenter();
+
+// Zoom out to see all nodes
+gxr.flyOut();
+
+// Zoom in/out
+gxr.zoomIn(2.0);
+gxr.zoomOut(0.5);
+
+// Enable camera rotation
+gxr.setCameraRotating(true);
+```
+
+### Screenshots and Export
+
+```javascript
+// Take a screenshot (returns Blob)
+const blob = await gxr.screenshot();
+
+// Screenshot with options
+const blob = await gxr.screenshot({
+  frameNodes: true,
+  hidePanels: true,
+  includeLegends: true,
+  format: 'png',
+  quality: 1.0
+});
+
+// Get graph as JSON snapshot
+const snapshot = gxr.snapshot();
+
+// Apply a snapshot
+gxr.snapshot(previousSnapshot);
+```
+
+### Transform Operations
+
+```javascript
+// Link nodes by matching property values
+gxr.link({
+  sourceCategory: "Person",
+  sourceProperty: "company",
+  targetCategory: "Company",
+  targetProperty: "name",
+  relationship: "WORKS_AT"
+});
+
+// Merge nodes with same key property
+gxr.merge({
+  category: "Person",
+  keys: ['email']
+});
+
+// Extract property to new nodes
+gxr.extract({
+  sourceCategory: "Episodes",
+  targetCategory: "Season",
+  props: [{ name: "seasonNumber", isKey: true }],
+  relationship: "IN_SEASON"
+});
+```
+
+### Query
+
+```javascript
+// Execute a Cypher query (if connected to a database)
+await gxr.query("MATCH (n:Person) RETURN n LIMIT 10");
+```
+
+### Utilities
+
+```javascript
+// Display a toast message
+gxr.toast("Hello, world!");
+gxr.toast().success("Operation completed!");
+gxr.toast().error("Something went wrong");
+
+// Sleep for a duration
+await gxr.sleep(1000);
+
+// Get project info
+const projectId = gxr.getProjectId();
+const projectName = gxr.getProjectName();
 ```
 
 For full API documentation, see the [GraphXR API Reference](https://graphxr.kineviz.com/docs).
 
+## Publishing (for maintainers)
+
+### Prerequisites
+
+- npm account with access to the `@kineviz` scope
+- Node.js 18 or later
+
+### First-time Setup
+
+Log in to npm with the @kineviz scope:
+
+```bash
+npm login --scope=@kineviz
+```
+
+### Release Process
+
+From the `modules/mcp` directory:
+
+```bash
+cd modules/mcp
+
+# 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)
+npm version major && yarn release   # 0.1.0 → 1.0.0 (breaking changes)
+```
+
+Or step by step:
+
+```bash
+# 1. Bump version
+npm version patch  # or minor, or major
+
+# 2. Build and publish
+yarn release
+```
+
+The `yarn release` command will:
+1. Build the package (`yarn build`)
+2. Publish to npm with public access
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kineviz/graphxr-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MCP server for GraphXR - enables Claude/Cursor to create graph visualizations",
   "bin": {
     "graphxr-mcp": "./dist/index.js"
@@ -11,7 +11,8 @@
   ],
   "scripts": {
     "build": "node build-package.js",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "yarn build",
+    "release": "yarn build && npm publish --access public"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",