@graphite-atlas/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,440 @@
+# Graphite Atlas MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides Claude and other AI assistants with access to your Graphite Atlas knowledge graphs.
+
+## Features
+
+- 🗺️ **Atlas Management**: Create, read, update, and delete knowledge graphs
+- 📍 **Point Operations**: Add and manage nodes (entities) in your graphs
+- 🔗 **Path Operations**: Create and manage edges (relationships) between points
+- 🧠 **Brain Dump**: AI-powered graph generation from text
+- 🔍 **Search**: Find points and paths across your atlases
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g @graphite-atlas/mcp-server
+```
+
+### From source
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+## Quick Start
+
+### 1. Generate a JWT Token
+
+Before using the MCP server, you need a JWT access token from Graphite Atlas:
+
+1. **Log in** to https://graphiteatlas.com
+2. **Navigate** to Profile → API Apps tab
+3. **Create** a new API app:
+   - Click "New App"
+   - Name: "Claude Desktop MCP"
+   - Description: "MCP server for Claude Desktop integration"
+   - Click "Create App"
+4. **Generate a JWT token**:
+   - Click "Generate Token" on your new app
+   - Token Name: "Claude Desktop"
+   - Environment: Production (or Development for testing)
+   - Scopes: Select the permissions you need (see [Scopes](#jwt-scopes) below)
+     - Recommended: Select "*" (Full Access) for easiest setup
+     - Or select specific scopes like `read:points`, `write:points`, `read:paths`, `write:paths`, etc.
+   - Expires In: 90 days (recommended)
+   - Click "Generate Token"
+5. **Copy your JWT token**:
+   - The token will only be shown **once** - copy it immediately!
+   - You can also copy the auto-generated Claude Desktop config snippet
+
+### 2. Configure Claude Desktop
+
+Add the MCP server to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "graphite-atlas": {
+      "command": "npx",
+      "args": [
+        "@graphite-atlas/mcp-server"
+      ],
+      "env": {
+        "GRAPHITE_ACCESS_TOKEN": "your_access_token_here",
+        "GRAPHITE_API_URL": "https://graphiteatlas.com/api"
+      }
+    }
+  }
+}
+```
+
+Or if running from source:
+
+```json
+{
+  "mcpServers": {
+    "graphite-atlas": {
+      "command": "node",
+      "args": [
+        "/path/to/graphite_atlas/mcp/dist/index.js"
+      ],
+      "env": {
+        "GRAPHITE_ACCESS_TOKEN": "your_access_token_here",
+        "GRAPHITE_API_URL": "https://graphiteatlas.com/api"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+Restart Claude Desktop to load the new MCP server.
+
+### 4. Test It!
+
+Ask Claude:
+```
+"List my Graphite Atlas knowledge graphs"
+```
+
+Claude should use the `list_atlases` tool to fetch and display your atlases.
+
+## Available Tools
+
+### Atlas Management
+
+#### `list_atlases`
+List all knowledge graphs owned by the user.
+
+**Parameters**: None
+
+**Example**:
+```
+"Show me all my atlases"
+```
+
+#### `get_atlas`
+Get details of a specific atlas.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+
+**Example**:
+```
+"Show me details for atlas abc-123"
+```
+
+#### `create_atlas`
+Create a new knowledge graph.
+
+**Parameters**:
+- `name` (string, required): Atlas name
+- `description` (string, optional): Atlas description
+
+**Example**:
+```
+"Create a new atlas called 'Project Notes' for tracking my project ideas"
+```
+
+#### `update_atlas`
+Update an atlas name or description.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `name` (string, optional): New name
+- `description` (string, optional): New description
+
+#### `delete_atlas`
+Delete an atlas permanently.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+
+**⚠️ Warning**: This action cannot be undone.
+
+### Point (Node) Operations
+
+#### `list_points`
+List all points in an atlas.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+
+**Example**:
+```
+"Show me all points in my Project Notes atlas"
+```
+
+#### `get_point`
+Get details of a specific point.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `point_id` (string, required): The point ID
+
+#### `create_point`
+Create a new point (entity/concept).
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `name` (string, required): Point name
+- `type` (string, required): Point type (e.g., "Person", "Company", "Concept")
+- `properties` (object, optional): Additional properties
+
+**Example**:
+```
+"In my Project Notes atlas, create a new point called 'AI Integration' of type 'Feature' with property 'priority' set to 'high'"
+```
+
+#### `update_point`
+Update a point's name, type, or properties.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `point_id` (string, required): The point ID
+- `name` (string, optional): New name
+- `type` (string, optional): New type
+- `properties` (object, optional): Updated properties (merged)
+
+#### `delete_point`
+Delete a point from an atlas.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `point_id` (string, required): The point ID
+
+#### `search_points`
+Search for points by name or type.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `query` (string, required): Search query
+
+**Example**:
+```
+"Search for all points related to 'AI' in my Project Notes atlas"
+```
+
+### Path (Relationship) Operations
+
+#### `list_paths`
+List all paths (relationships) in an atlas.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+
+#### `get_path`
+Get details of a specific path.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `path_id` (string, required): The path ID
+
+#### `create_path`
+Create a new path between two points.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `name` (string, required): Path name
+- `type` (string, required): Path type (e.g., "KNOWS", "WORKS_AT", "DEPENDS_ON")
+- `source_id` (string, required): Source point ID
+- `target_id` (string, required): Target point ID
+- `properties` (object, optional): Additional properties
+
+**Example**:
+```
+"Create a 'DEPENDS_ON' relationship from 'AI Integration' feature to 'Database Upgrade' feature"
+```
+
+#### `update_path`
+Update a path's name, type, or properties.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `path_id` (string, required): The path ID
+- `name` (string, optional): New name
+- `type` (string, optional): New type
+- `properties` (object, optional): Updated properties
+
+#### `delete_path`
+Delete a path from an atlas.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `path_id` (string, required): The path ID
+
+#### `search_paths`
+Search for paths by name or type.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID
+- `query` (string, required): Search query
+
+### Brain Dump (AI Graph Generation)
+
+#### `brain_dump`
+Use AI to automatically generate a knowledge graph from text.
+
+**Parameters**:
+- `atlas_id` (string, required): The atlas ID to add generated graph to
+- `text` (string, required): Text to analyze (notes, articles, transcripts)
+- `process_name` (string, optional): Name for this brain dump process
+
+**Example**:
+```
+"Take this meeting transcript and create a knowledge graph in my Project Notes atlas:
+
+[Meeting notes about AI project planning, stakeholders, dependencies...]
+"
+```
+
+#### `get_brain_dump_status`
+Check the status of a brain dump operation.
+
+**Parameters**:
+- `operation_id` (string, required): Operation ID from brain_dump
+
+**Example**:
+```
+"Check the status of brain dump operation op-xyz-789"
+```
+
+## JWT Scopes
+
+When generating your JWT token, select the scopes you need:
+
+| Scope | Required For | Description |
+|-------|-------------|-------------|
+| `*` | All operations | Full access to all resources (recommended for personal use) |
+| `read:atlases` | List/get atlases | View your knowledge graphs |
+| `write:atlases` | Create/update atlases | Create and modify atlases |
+| `delete:atlases` | Delete atlases | Permanently delete atlases |
+| `read:points` | List/get points | View nodes in your graphs |
+| `write:points` | Create/update points | Add and modify nodes |
+| `delete:points` | Delete points | Remove nodes |
+| `read:paths` | List/get paths | View relationships |
+| `write:paths` | Create/update paths | Add and modify relationships |
+| `delete:paths` | Delete paths | Remove relationships |
+| `read:schema` | Get schemas | View atlas ontology schemas |
+| `use:llm` | Brain dump | AI-powered graph generation |
+| `use:embeddings` | Semantic search | AI-powered semantic search |
+
+**Recommended for personal use**:
+```
+* (Full Access)
+```
+
+**Recommended minimal scopes** for read-only access:
+```
+read:atlases read:points read:paths read:schema
+```
+
+**Recommended scopes** for full graph editing:
+```
+read:atlases write:atlases delete:atlases read:points write:points delete:points read:paths write:paths delete:paths read:schema use:llm
+```
+
+Or simply use wildcard patterns:
+```
+read:* write:* delete:*
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GRAPHITE_ACCESS_TOKEN` | OAuth access token (required) | - |
+| `GRAPHITE_API_URL` | Graphite Atlas API base URL | `https://graphiteatlas.com/api` |
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run watch
+```
+
+### Development Mode (with auto-reload)
+
+```bash
+npm run dev
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+## Troubleshooting
+
+### "GRAPHITE_ACCESS_TOKEN environment variable is required"
+
+You need to provide a valid OAuth access token. See [Quick Start](#quick-start) for instructions on getting one.
+
+### "Failed to connect to Graphite Atlas API"
+
+Check that:
+1. Your access token is valid (not expired)
+2. The API URL is correct
+3. You have network connectivity
+4. The Graphite Atlas API is operational
+
+### "API Error (401): Unauthorized"
+
+Your access token may be expired. Generate a new one using the refresh token flow or by reauthorizing.
+
+### Tools not appearing in Claude Desktop
+
+1. Check the Claude Desktop logs (Help → View Logs)
+2. Verify your config file syntax is valid JSON
+3. Restart Claude Desktop after config changes
+4. Check that the MCP server is executable (`chmod +x dist/index.js` if needed)
+
+## Security
+
+- **Never commit** your access token to version control
+- **Never share** your access token publicly
+- **Rotate tokens** regularly
+- **Use minimal scopes** required for your use case
+- **Revoke unused** OAuth apps from Settings → Developer
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## License
+
+MIT
+
+## Support
+
+- **Documentation**: https://docs.graphiteatlas.com
+- **Issues**: https://github.com/graphite-atlas/mcp-server/issues
+- **Email**: support@graphiteatlas.com
+
+---
+
+Built with ❤️ by the Graphite Atlas team

package/dist/client.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Graphite Atlas API Client
+ *
+ * Handles all HTTP communication with the Graphite Atlas API.
+ */
+export interface GraphiteAtlasClientConfig {
+    apiUrl: string;
+    accessToken: string;
+}
+export interface Atlas {
+    id: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Point {
+    id: string;
+    name: string;
+    type: string;
+    properties: Record<string, unknown>;
+    atlasId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Path {
+    id: string;
+    name: string;
+    type: string;
+    sourceId: string;
+    targetId: string;
+    source_name?: string;
+    target_name?: string;
+    properties: Record<string, unknown>;
+    atlasId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BrainDumpResult {
+    operationId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    points?: Point[];
+    paths?: Path[];
+}
+export interface View {
+    id: string;
+    atlasId: string;
+    name: string;
+    description?: string;
+    viewType: 'map' | 'table' | 'combo' | 'folder';
+    parentId?: string | null;
+    position?: number;
+    isPublic?: boolean;
+    isDefault?: boolean;
+    settings?: Record<string, unknown>;
+    filters?: Record<string, unknown>;
+    visibility?: Record<string, boolean>;
+    pointIds?: string[];
+    layout?: string;
+    groupBy?: string | null;
+    nodeStyles?: Record<string, unknown>;
+    edgeStyles?: Record<string, unknown>;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class GraphiteAtlasClient {
+    private axios;
+    constructor(config: GraphiteAtlasClientConfig);
+    /**
+     * Health check to verify API connectivity
+     */
+    healthCheck(): Promise<void>;
+    /**
+     * List all atlases for the authenticated user
+     */
+    listAtlases(): Promise<Atlas[]>;
+    /**
+     * Get a specific atlas by ID
+     */
+    getAtlas(atlasId: string): Promise<Atlas>;
+    /**
+     * Create a new atlas
+     */
+    createAtlas(params: {
+        name: string;
+        description?: string;
+        schema?: Record<string, unknown>;
+    }): Promise<Atlas>;
+    /**
+     * Update an existing atlas
+     */
+    updateAtlas(atlasId: string, params: {
+        name?: string;
+        description?: string;
+        schema?: Record<string, unknown>;
+    }): Promise<Atlas>;
+    /**
+     * Delete an atlas
+     */
+    deleteAtlas(atlasId: string): Promise<void>;
+    /**
+     * List all points in an atlas
+     */
+    listPoints(atlasId: string): Promise<Point[]>;
+    /**
+     * Get a specific point by searching all points
+     * Note: Backend doesn't have a single-point GET endpoint, so we filter the list
+     */
+    getPoint(atlasId: string, pointId: string): Promise<Point>;
+    /**
+     * Create a new point
+     */
+    createPoint(atlasId: string, params: {
+        name: string;
+        type: string;
+        description?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<Point>;
+    /**
+     * Update a point
+     */
+    updatePoint(atlasId: string, pointId: string, params: {
+        name?: string;
+        type?: string;
+        description?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<Point>;
+    /**
+     * Delete a point
+     */
+    deletePoint(atlasId: string, pointId: string): Promise<void>;
+    /**
+     * List all paths in an atlas
+     */
+    listPaths(atlasId: string): Promise<Path[]>;
+    /**
+     * Get a specific path by searching all paths
+     * Note: Backend doesn't have a single-path GET endpoint, so we filter the list
+     */
+    getPath(atlasId: string, pathId: string): Promise<Path>;
+    /**
+     * Create a new path
+     */
+    createPath(atlasId: string, params: {
+        name: string;
+        type: string;
+        sourceId: string;
+        targetId: string;
+        description?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<Path>;
+    /**
+     * Update a path
+     */
+    updatePath(atlasId: string, pathId: string, params: {
+        name?: string;
+        type?: string;
+        description?: string;
+        properties?: Record<string, unknown>;
+    }): Promise<Path>;
+    /**
+     * Delete a path
+     */
+    deletePath(atlasId: string, pathId: string): Promise<void>;
+    /**
+     * Batch create points and paths with name-based references
+     * Reduces multiple API calls to a single atomic operation
+     */
+    batchCreateGraph(atlasId: string, params: {
+        points?: Array<{
+            name: string;
+            type: string;
+            category?: string;
+            description?: string;
+            tags?: string[];
+            properties?: Record<string, unknown>;
+        }>;
+        paths?: Array<{
+            type: string;
+            source_name: string;
+            target_name: string;
+            description?: string;
+            properties?: Record<string, unknown>;
+        }>;
+    }): Promise<{
+        points: Point[];
+        paths: Path[];
+        pointCount: number;
+        pathCount: number;
+    }>;
+    /**
+     * Execute a read-only Cypher query
+     * Enables complex graph traversals in a single call
+     */
+    queryCypher(atlasId: string, params: {
+        query: string;
+        parameters?: Record<string, unknown>;
+    }): Promise<any[]>;
+    /**
+     * Execute a brain dump to generate graph from text
+     */
+    brainDump(atlasId: string, params: {
+        text: string;
+        processName?: string;
+    }): Promise<BrainDumpResult>;
+    /**
+     * Get brain dump operation status
+     */
+    getBrainDumpStatus(operationId: string): Promise<BrainDumpResult>;
+    /**
+     * Search for points by name or type
+     */
+    searchPoints(atlasId: string, query: string): Promise<Point[]>;
+    /**
+     * Search for paths by name or type
+     */
+    searchPaths(atlasId: string, query: string): Promise<Path[]>;
+    /**
+     * List all views in an atlas
+     */
+    listViews(atlasId: string): Promise<View[]>;
+    /**
+     * Get a specific view by ID
+     */
+    getView(atlasId: string, viewId: string): Promise<View>;
+    /**
+     * Create a new view
+     */
+    createView(atlasId: string, params: {
+        name: string;
+        description?: string;
+        viewType?: 'map' | 'table' | 'combo' | 'folder';
+        parentId?: string;
+        position?: number;
+        settings?: Record<string, unknown>;
+        filters?: Record<string, unknown>;
+        isPublic?: boolean;
+    }): Promise<View>;
+    /**
+     * Update an existing view
+     */
+    updateView(atlasId: string, viewId: string, params: {
+        name?: string;
+        description?: string;
+        viewType?: 'map' | 'table' | 'combo' | 'folder';
+        parentId?: string;
+        position?: number;
+        settings?: Record<string, unknown>;
+        filters?: Record<string, unknown>;
+        visibility?: Record<string, boolean>;
+        pointIds?: string[];
+        isPublic?: boolean;
+    }): Promise<View>;
+    /**
+     * Delete a view
+     */
+    deleteView(atlasId: string, viewId: string): Promise<void>;
+    /**
+     * Toggle point visibility in a view
+     */
+    togglePointVisibility(atlasId: string, viewId: string, pointId: string, visible: boolean): Promise<Record<string, boolean>>;
+    /**
+     * Add point to view
+     */
+    addPointToView(atlasId: string, viewId: string, pointId: string): Promise<string[]>;
+    /**
+     * Remove point from view
+     */
+    removePointFromView(atlasId: string, viewId: string, pointId: string): Promise<string[]>;
+}
+//# sourceMappingURL=client.d.ts.map