@coreviz/cli 1.0.12 → 1.2.0

package/README.md

@@ -138,6 +138,73 @@ Check login status:
 npx @coreviz/cli whoami
 ```
 
+## MCP Server (Claude Code Integration)
+
+`@coreviz/cli` includes a built-in MCP server that exposes your CoreViz visual library as tools for Claude Code and other MCP-compatible AI agents — turning CoreViz into a **visual memory** for your AI workflows.
+
+### Setup
+
+1. Login (if you haven't already):
+   ```bash
+   npx @coreviz/cli login
+   ```
+
+2. Add to your project's `.mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "coreviz": {
+         "command": "npx",
+         "args": ["coreviz-mcp"]
+       }
+     }
+   }
+   ```
+
+3. In Claude Code, run `/mcp` to confirm the server is connected.
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_collections` | List all collections in your workspace |
+| `create_collection` | Create a new collection |
+| `browse_media` | Navigate folders and list media items |
+| `search_media` | Semantic search across all your media |
+| `get_media` | Get full details, tags, and detected objects for an item |
+| `get_tags` | Aggregate all tags across a collection |
+| `find_similar` | Find visually similar images by object ID |
+| `analyze_image` | Run AI vision analysis on an image URL |
+| `create_folder` | Create a new folder |
+| `move_item` | Move a file or folder |
+| `rename_item` | Rename a file or folder |
+| `add_tag` | Add a tag to a media item |
+| `remove_tag` | Remove a tag from a media item |
+| `upload_media` | Upload a local photo or video file to a collection |
+
+### Local development override
+
+```json
+{
+  "mcpServers": {
+    "coreviz": {
+      "command": "node",
+      "args": ["/path/to/@coreviz/cli/bin/mcp.js"],
+      "env": {
+        "COREVIZ_API_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+You can also authenticate via environment variable instead of `coreviz login`:
+```bash
+COREVIZ_API_KEY=your_key npx coreviz-mcp
+```
+
+---
+
 ## Development
 
 1. Install dependencies:
@@ -149,4 +216,9 @@ npx @coreviz/cli whoami
 2. Run local CLI:
    ```bash
    node bin/cli.js --help
+   ```
+
+3. Run local MCP server:
+   ```bash
+   node bin/mcp.js
    ```

package/bin/mcp.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * CoreViz MCP Server
+ *
+ * Exposes your CoreViz visual library as tools for Claude Code and other MCP clients.
+ * Authentication is read from the session stored by `coreviz login`.
+ *
+ * Usage (after `coreviz login`):
+ *   Add to .mcp.json:
+ *   {
+ *     "mcpServers": {
+ *       "coreviz": { "command": "npx", "args": ["coreviz-mcp"] }
+ *     }
+ *   }
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import Conf from 'conf';
+import { CoreViz } from '@coreviz/sdk';
+import { registerTools } from '../lib/mcp-tools.js';
+
+const config = new Conf({ projectName: 'coreviz-cli' });
+
+async function main() {
+    // Read stored session from `coreviz login`
+    const session = config.get('session');
+    const token = session?.access_token;
+
+    // Also support explicit env var overrides for CI/scripting
+    const apiKey = process.env.COREVIZ_API_KEY;
+    const baseUrl = process.env.COREVIZ_API_URL || 'https://lab.coreviz.io';
+
+    if (!token && !apiKey) {
+        process.stderr.write(
+            '[coreviz-mcp] Not authenticated. Run `coreviz login` first, ' +
+            'or set COREVIZ_API_KEY environment variable.\n'
+        );
+        process.exit(1);
+    }
+
+    const sdk = new CoreViz({
+        ...(token ? { token } : { apiKey }),
+        baseUrl,
+    });
+
+    const server = new McpServer({
+        name: 'coreviz',
+        version: '1.0.0',
+    });
+
+    registerTools(server, sdk);
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    process.stderr.write('[coreviz-mcp] Server ready\n');
+}
+
+main().catch((err) => {
+    process.stderr.write(`[coreviz-mcp] Fatal error: ${err?.message || err}\n`);
+    process.exit(1);
+});

package/lib/mcp-tools.js

@@ -0,0 +1,225 @@
+/**
+ * CoreViz MCP tool definitions.
+ * Each tool maps 1:1 to a @coreviz/sdk method.
+ */
+
+import { z } from 'zod';
+
+/** Build a text result object for MCP */
+function text(value) {
+    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+}
+
+/** Wrap an async tool handler with consistent error handling */
+function safe(fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        } catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err?.message || String(err)}` }], isError: true };
+        }
+    };
+}
+
+/**
+ * Register all CoreViz tools on the given MCP server.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@coreviz/sdk').CoreViz} sdk
+ */
+export function registerTools(server, sdk) {
+
+    // ── Read-only tools ───────────────────────────────────────────────────────
+
+    server.tool(
+        'list_collections',
+        'List all collections in your CoreViz workspace. Returns collection IDs and names.',
+        {},
+        safe(async () => {
+            const collections = await sdk.collections.list();
+            return text(collections);
+        })
+    );
+
+    server.tool(
+        'create_collection',
+        'Create a new collection in your CoreViz workspace.',
+        {
+            name: z.string().describe('Name for the new collection'),
+            icon: z.string().optional().describe('Optional icon for the collection (emoji or icon name)'),
+        },
+        safe(async ({ name, icon }) => {
+            const collection = await sdk.collections.create(name, icon);
+            return text(collection);
+        })
+    );
+
+    server.tool(
+        'browse_media',
+        'Browse or list media items and folders inside a collection. Use the ltree path to navigate subfolders (e.g. "collectionId.folderId"). Returns file/folder IDs, names, types, blob URLs, and metadata.',
+        {
+            collectionId: z.string().describe('The collection ID to browse (from list_collections)'),
+            path: z.string().optional().describe('ltree path to list (e.g. "collectionId" for root, "collectionId.folderId" for a subfolder). Defaults to the collection root.'),
+            limit: z.number().optional().default(50).describe('Max number of items to return (default 50)'),
+            offset: z.number().optional().default(0).describe('Pagination offset'),
+            type: z.enum(['image', 'video', 'folder', 'all']).optional().describe('Filter by item type'),
+            dateFrom: z.string().optional().describe('Filter by creation date from (YYYY-MM-DD)'),
+            dateTo: z.string().optional().describe('Filter by creation date to (YYYY-MM-DD)'),
+            sortBy: z.string().optional().describe('Sort field: name, createdAt, type'),
+            sortDirection: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+        },
+        safe(async ({ collectionId, ...opts }) => {
+            const result = await sdk.media.browse(collectionId, opts);
+            return text(result);
+        })
+    );
+
+    server.tool(
+        'search_media',
+        'Semantically search across all media in your CoreViz workspace using natural language. Returns ranked results with image URLs, detected objects, and metadata. Use this to find specific images, scenes, or subjects.',
+        {
+            query: z.string().describe('Natural language search query (e.g. "red shoes", "sunset over mountains", "person wearing glasses")'),
+            limit: z.number().optional().default(10).describe('Max number of results to return (default 10, max 50)'),
+        },
+        safe(async ({ query, limit }) => {
+            const results = await sdk.media.search(query, { limit });
+            return text(results);
+        })
+    );
+
+    server.tool(
+        'get_media',
+        'Get full details for a specific media item: blob URL, dimensions, tags, detected objects, version history, and metadata.',
+        {
+            mediaId: z.string().describe('The media item ID (from browse_media or search_media results)'),
+        },
+        safe(async ({ mediaId }) => {
+            const media = await sdk.media.get(mediaId);
+            return text(media);
+        })
+    );
+
+    server.tool(
+        'get_tags',
+        'Get all tag groups and their values aggregated across an entire collection. Useful for understanding how a collection is categorized.',
+        {
+            collectionId: z.string().describe('The collection ID (from list_collections)'),
+        },
+        safe(async ({ collectionId }) => {
+            const tags = await sdk.tags.list(collectionId);
+            return text(tags);
+        })
+    );
+
+    server.tool(
+        'find_similar',
+        'Find media items that are visually similar to a specific detected object. Provide an object ID from a previous get_media or search_media result. Useful for face recognition, product matching, or pattern finding.',
+        {
+            collectionId: z.string().describe('The collection ID to search within'),
+            objectId: z.string().describe('The object ID from a detected object (from get_media frames[].objects[].id or search_media objects[].id)'),
+            limit: z.number().optional().default(10).describe('Max number of similar items to return'),
+            model: z.string().optional().describe('Similarity model to use: "faces", "objects", or "shoeprints"'),
+        },
+        safe(async ({ collectionId, objectId, limit, model }) => {
+            const result = await sdk.media.findSimilar(collectionId, objectId, { limit, model });
+            return text(result);
+        })
+    );
+
+    // ── Write tools ───────────────────────────────────────────────────────────
+
+    server.tool(
+        'analyze_image',
+        'Analyze an image using AI vision. Provide a blob URL (from browse_media or search_media results). Returns a detailed description of the image contents.',
+        {
+            imageUrl: z.string().describe('The blob URL of the image to analyze (must be a real URL from browse_media or search_media, never guessed)'),
+            prompt: z.string().optional().default('Describe this image in detail.').describe('Optional question or prompt to ask about the image'),
+        },
+        safe(async ({ imageUrl, prompt }) => {
+            const description = await sdk.describe(imageUrl, { prompt });
+            return text(description);
+        })
+    );
+
+    server.tool(
+        'create_folder',
+        'Create a new folder inside a collection.',
+        {
+            collectionId: z.string().describe('The collection ID where the folder will be created'),
+            name: z.string().describe('Name of the new folder'),
+            path: z.string().optional().describe('Parent ltree path for the folder (e.g. "collectionId" for root, "collectionId.parentFolderId" for a subfolder). Defaults to collection root.'),
+        },
+        safe(async ({ collectionId, name, path }) => {
+            const folder = await sdk.folders.create(collectionId, name, path);
+            return text(folder);
+        })
+    );
+
+    server.tool(
+        'move_item',
+        'Move a media item or folder to a different location within the same collection. Both sourceId and destinationPath must come from previous browse_media results — never construct paths manually.',
+        {
+            mediaId: z.string().describe('The ID of the media item or folder to move'),
+            destinationPath: z.string().describe('The ltree path of the destination folder (from browse_media results, e.g. "collectionId.folderId")'),
+        },
+        safe(async ({ mediaId, destinationPath }) => {
+            const result = await sdk.media.move(mediaId, destinationPath);
+            return text(result);
+        })
+    );
+
+    server.tool(
+        'rename_item',
+        'Rename a media item or folder.',
+        {
+            mediaId: z.string().describe('The ID of the media item to rename'),
+            name: z.string().describe('The new name for the item'),
+        },
+        safe(async ({ mediaId, name }) => {
+            const media = await sdk.media.rename(mediaId, name);
+            return text(media);
+        })
+    );
+
+    server.tool(
+        'add_tag',
+        'Add a tag to a media item. Tags are organized as label (group) + value pairs, e.g. label="color", value="red".',
+        {
+            mediaId: z.string().describe('The media item ID'),
+            label: z.string().describe('Tag group name (e.g. "color", "category", "quality")'),
+            value: z.string().describe('Tag value (e.g. "red", "product", "high")'),
+        },
+        safe(async ({ mediaId, label, value }) => {
+            await sdk.media.addTag(mediaId, label, value);
+            return text({ success: true, mediaId, tag: { label, value } });
+        })
+    );
+
+    server.tool(
+        'remove_tag',
+        'Remove a specific tag from a media item.',
+        {
+            mediaId: z.string().describe('The media item ID'),
+            label: z.string().describe('Tag group name to remove'),
+            value: z.string().describe('Tag value to remove'),
+        },
+        safe(async ({ mediaId, label, value }) => {
+            await sdk.media.removeTag(mediaId, label, value);
+            return text({ success: true, mediaId, removed: { label, value } });
+        })
+    );
+
+    server.tool(
+        'upload_media',
+        'Upload a local photo or video file to a CoreViz collection. Provide the absolute path to the file and the target collection ID. Optionally specify a folder path and a custom name.',
+        {
+            filePath: z.string().describe('Absolute path to the local file to upload (e.g. /Users/you/photo.jpg)'),
+            collectionId: z.string().describe('The collection ID to upload into (from list_collections)'),
+            path: z.string().optional().describe('ltree folder path to upload into (e.g. "collectionId.folderId"). Defaults to collection root.'),
+            name: z.string().optional().describe('Custom name for the file in CoreViz. Defaults to the original filename.'),
+        },
+        safe(async ({ filePath, collectionId, path, name }) => {
+            const result = await sdk.media.upload(filePath, { collectionId, path, name });
+            return text(result);
+        })
+    );
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@coreviz/cli",
-  "version": "1.0.12",
+  "version": "1.2.0",
   "type": "module",
   "description": "CoreViz CLI tool",
   "main": "index.js",
   "bin": {
-    "coreviz": "./bin/cli.js"
+    "coreviz": "./bin/cli.js",
+    "coreviz-mcp": "./bin/mcp.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -27,7 +28,8 @@
   "homepage": "https://github.com/CoreViz/cli#readme",
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@coreviz/sdk": "^1.0.11",
+    "@coreviz/sdk": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "better-auth": "^1.4.2",
     "better-sqlite3": "^12.4.6",
     "chalk": "^5.6.2",