@getjack/jack 0.1.24 → 0.1.26

package/src/lib/services/vectorize-create.ts

@@ -0,0 +1,166 @@
+/**
+ * Vectorize index creation logic for jack MCP tools
+ *
+ * Uses wrangler CLI to create Vectorize indexes.
+ */
+
+import { join } from "node:path";
+import { $ } from "bun";
+import { getProjectNameFromDir } from "../storage/index.ts";
+import { addVectorizeBinding, getExistingVectorizeBindings } from "./vectorize-config.ts";
+
+export type VectorizeMetric = "cosine" | "euclidean" | "dot-product";
+
+export interface CreateVectorizeOptions {
+	name?: string;
+	dimensions?: number;
+	metric?: VectorizeMetric;
+}
+
+export interface CreateVectorizeResult {
+	indexName: string;
+	bindingName: string;
+	dimensions: number;
+	metric: VectorizeMetric;
+	created: boolean; // false if reused existing
+}
+
+/**
+ * Convert an index name to SCREAMING_SNAKE_CASE for the binding name.
+ * Special case: first index in a project gets "VECTORS" as the binding.
+ */
+function toBindingName(indexName: string, isFirst: boolean): string {
+	if (isFirst) {
+		return "VECTORS";
+	}
+	// Convert kebab-case/snake_case to SCREAMING_SNAKE_CASE
+	return indexName
+		.replace(/-/g, "_")
+		.replace(/[^a-zA-Z0-9_]/g, "")
+		.toUpperCase();
+}
+
+/**
+ * Generate a unique index name for a project.
+ * First index: {project}-vectors
+ * Subsequent: {project}-vectors-{n}
+ */
+function generateIndexName(projectName: string, existingCount: number): string {
+	if (existingCount === 0) {
+		return `${projectName}-vectors`;
+	}
+	return `${projectName}-vectors-${existingCount + 1}`;
+}
+
+interface ExistingIndex {
+	name: string;
+	dimensions?: number;
+	metric?: string;
+}
+
+/**
+ * List all Vectorize indexes in the Cloudflare account via wrangler
+ */
+async function listIndexesViaWrangler(): Promise<ExistingIndex[]> {
+	const result = await $`wrangler vectorize list --json`.nothrow().quiet();
+
+	if (result.exitCode !== 0) {
+		// If wrangler fails, return empty list (might not be logged in)
+		return [];
+	}
+
+	try {
+		const output = result.stdout.toString().trim();
+		const data = JSON.parse(output);
+		// wrangler vectorize list --json returns array: [{ "name": "...", ... }]
+		return Array.isArray(data) ? data : [];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Find an existing Vectorize index by name
+ */
+async function findExistingIndex(indexName: string): Promise<ExistingIndex | null> {
+	const indexes = await listIndexesViaWrangler();
+	return indexes.find((idx) => idx.name === indexName) ?? null;
+}
+
+/**
+ * Create a Vectorize index via wrangler
+ */
+async function createIndexViaWrangler(
+	indexName: string,
+	dimensions: number,
+	metric: VectorizeMetric,
+): Promise<{ created: boolean }> {
+	// Check if index already exists
+	const existing = await findExistingIndex(indexName);
+	if (existing) {
+		return { created: false };
+	}
+
+	const result =
+		await $`wrangler vectorize create ${indexName} --dimensions=${dimensions} --metric=${metric}`.nothrow().quiet();
+
+	if (result.exitCode !== 0) {
+		const stderr = result.stderr.toString().trim();
+		throw new Error(stderr || `Failed to create Vectorize index ${indexName}`);
+	}
+
+	return { created: true };
+}
+
+/**
+ * Create a Vectorize index for the current project.
+ *
+ * Uses wrangler vectorize create to create the index, then updates
+ * wrangler.jsonc with the new binding.
+ */
+export async function createVectorizeIndex(
+	projectDir: string,
+	options: CreateVectorizeOptions = {},
+): Promise<CreateVectorizeResult> {
+	// Get project name from wrangler config
+	const projectName = await getProjectNameFromDir(projectDir);
+
+	// Get existing Vectorize bindings to determine naming
+	const wranglerPath = join(projectDir, "wrangler.jsonc");
+	const existingBindings = await getExistingVectorizeBindings(wranglerPath);
+	const existingCount = existingBindings.length;
+
+	// Determine index name
+	const indexName = options.name ?? generateIndexName(projectName, existingCount);
+
+	// Determine binding name
+	const isFirst = existingCount === 0;
+	const bindingName = toBindingName(indexName, isFirst);
+
+	// Check if binding name already exists
+	const bindingExists = existingBindings.some((b) => b.binding === bindingName);
+	if (bindingExists) {
+		throw new Error(`Binding "${bindingName}" already exists. Choose a different index name.`);
+	}
+
+	// Use omakase defaults: 768 dimensions (for bge-base-en-v1.5), cosine metric
+	const dimensions = options.dimensions ?? 768;
+	const metric = options.metric ?? "cosine";
+
+	// Create via wrangler
+	const result = await createIndexViaWrangler(indexName, dimensions, metric);
+
+	// Update wrangler.jsonc with the new binding
+	await addVectorizeBinding(wranglerPath, {
+		binding: bindingName,
+		index_name: indexName,
+	});
+
+	return {
+		indexName,
+		bindingName,
+		dimensions,
+		metric,
+		created: result.created,
+	};
+}

package/src/lib/services/vectorize-delete.ts

@@ -0,0 +1,54 @@
+/**
+ * Vectorize index deletion logic for jack MCP tools
+ *
+ * Uses wrangler CLI to delete Vectorize indexes.
+ */
+
+import { join } from "node:path";
+import { $ } from "bun";
+import { removeVectorizeBinding } from "./vectorize-config.ts";
+
+export interface DeleteVectorizeResult {
+	indexName: string;
+	deleted: boolean;
+	bindingRemoved: boolean;
+}
+
+/**
+ * Delete a Vectorize index via wrangler
+ */
+async function deleteIndexViaWrangler(indexName: string): Promise<void> {
+	const result = await $`wrangler vectorize delete ${indexName} --force`.nothrow().quiet();
+
+	if (result.exitCode !== 0) {
+		const stderr = result.stderr.toString().trim();
+		// Ignore "not found" errors - the index might already be deleted
+		if (!stderr.includes("not found") && !stderr.includes("does not exist")) {
+			throw new Error(stderr || `Failed to delete Vectorize index ${indexName}`);
+		}
+	}
+}
+
+/**
+ * Delete a Vectorize index for the current project.
+ *
+ * Uses wrangler vectorize delete to delete the index, then removes
+ * the binding from wrangler.jsonc.
+ */
+export async function deleteVectorizeIndex(
+	projectDir: string,
+	indexName: string,
+): Promise<DeleteVectorizeResult> {
+	// Delete via wrangler
+	await deleteIndexViaWrangler(indexName);
+
+	// Remove binding from wrangler.jsonc
+	const wranglerPath = join(projectDir, "wrangler.jsonc");
+	const bindingRemoved = await removeVectorizeBinding(wranglerPath, indexName);
+
+	return {
+		indexName,
+		deleted: true,
+		bindingRemoved,
+	};
+}

package/src/lib/services/vectorize-info.ts

@@ -0,0 +1,52 @@
+/**
+ * Vectorize index info logic for jack MCP tools
+ *
+ * Uses wrangler CLI to get information about Vectorize indexes.
+ */
+
+import { $ } from "bun";
+
+export interface VectorizeInfo {
+	name: string;
+	dimensions: number;
+	metric: string;
+	vectorCount: number;
+	createdOn?: string;
+	modifiedOn?: string;
+}
+
+/**
+ * Get Vectorize index info via wrangler vectorize info
+ */
+export async function getVectorizeInfo(indexName: string): Promise<VectorizeInfo | null> {
+	const result = await $`wrangler vectorize info ${indexName} --json`.nothrow().quiet();
+
+	if (result.exitCode !== 0) {
+		return null;
+	}
+
+	try {
+		const output = result.stdout.toString().trim();
+		const data = JSON.parse(output);
+
+		// wrangler vectorize info --json returns:
+		// {
+		//   "name": "...",
+		//   "config": { "dimensions": N, "metric": "..." },
+		//   "vectorsCount": N,
+		//   "created_on": "...",
+		//   "modified_on": "..."
+		// }
+		return {
+			name: data.name || indexName,
+			dimensions: data.config?.dimensions || 0,
+			metric: data.config?.metric || "unknown",
+			vectorCount: data.vectorsCount || 0,
+			createdOn: data.created_on,
+			modifiedOn: data.modified_on,
+		};
+	} catch {
+		// Failed to parse JSON output
+		return null;
+	}
+}

package/src/lib/services/vectorize-list.ts

@@ -0,0 +1,56 @@
+/**
+ * Vectorize index listing logic for jack MCP tools
+ *
+ * Lists Vectorize indexes configured in wrangler.jsonc with their metadata.
+ */
+
+import { join } from "node:path";
+import { getExistingVectorizeBindings } from "./vectorize-config.ts";
+import { getVectorizeInfo } from "./vectorize-info.ts";
+
+export interface VectorizeListEntry {
+	name: string;
+	binding: string;
+	dimensions?: number;
+	metric?: string;
+	vectorCount?: number;
+}
+
+/**
+ * List all Vectorize indexes configured for a project.
+ *
+ * Reads bindings from wrangler.jsonc and fetches additional metadata
+ * (dimensions, metric, vector count) via wrangler vectorize info for each index.
+ */
+export async function listVectorizeIndexes(projectDir: string): Promise<VectorizeListEntry[]> {
+	const wranglerPath = join(projectDir, "wrangler.jsonc");
+
+	// Get existing Vectorize bindings from wrangler.jsonc
+	const bindings = await getExistingVectorizeBindings(wranglerPath);
+
+	if (bindings.length === 0) {
+		return [];
+	}
+
+	// Fetch detailed info for each index
+	const entries: VectorizeListEntry[] = [];
+
+	for (const binding of bindings) {
+		const entry: VectorizeListEntry = {
+			name: binding.index_name,
+			binding: binding.binding,
+		};
+
+		// Try to get additional metadata via wrangler
+		const info = await getVectorizeInfo(binding.index_name);
+		if (info) {
+			entry.dimensions = info.dimensions;
+			entry.metric = info.metric;
+			entry.vectorCount = info.vectorCount;
+		}
+
+		entries.push(entry);
+	}
+
+	return entries;
+}

package/src/mcp/tools/index.ts

@@ -12,6 +12,10 @@ import {
 	wrapResultsForMcp,
 } from "../../lib/services/db-execute.ts";
 import { listDatabases } from "../../lib/services/db-list.ts";
+import { createVectorizeIndex } from "../../lib/services/vectorize-create.ts";
+import { deleteVectorizeIndex } from "../../lib/services/vectorize-delete.ts";
+import { getVectorizeInfo } from "../../lib/services/vectorize-info.ts";
+import { listVectorizeIndexes } from "../../lib/services/vectorize-list.ts";
 import { Events, track, withTelemetry } from "../../lib/telemetry.ts";
 import type { DebugLogger, McpServerOptions } from "../types.ts";
 import { formatErrorResponse, formatSuccessResponse } from "../utils.ts";
@@ -78,6 +82,43 @@ const ExecuteSqlSchema = z.object({
 		.describe("Database name (auto-detect from wrangler.jsonc if not provided)"),
 });
 
+const CreateVectorizeIndexSchema = z.object({
+	name: z.string().optional().describe("Index name (auto-generated if not provided)"),
+	dimensions: z.number().optional().default(768).describe("Vector dimensions (default: 768)"),
+	metric: z
+		.enum(["cosine", "euclidean", "dot-product"])
+		.optional()
+		.default("cosine")
+		.describe("Distance metric (default: cosine)"),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
+const ListVectorizeIndexesSchema = z.object({
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
+const DeleteVectorizeIndexSchema = z.object({
+	name: z.string().describe("Index name to delete"),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
+const GetVectorizeInfoSchema = z.object({
+	name: z.string().describe("Index name"),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
 export function registerTools(server: McpServer, _options: McpServerOptions, debug: DebugLogger) {
 	// Register tool list handler
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -212,6 +253,85 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						required: ["sql"],
 					},
 				},
+				{
+					name: "create_vectorize_index",
+					description:
+						"Create a new Vectorize index for vector similarity search. Returns deploy_required=true since binding needs deploy to activate.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "Index name (auto-generated if not provided)",
+							},
+							dimensions: {
+								type: "number",
+								default: 768,
+								description: "Vector dimensions (default: 768 for bge-base-en-v1.5)",
+							},
+							metric: {
+								type: "string",
+								enum: ["cosine", "euclidean", "dot-product"],
+								default: "cosine",
+								description: "Distance metric (default: cosine)",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
+				{
+					name: "list_vectorize_indexes",
+					description: "List all Vectorize indexes for a project.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
+				{
+					name: "delete_vectorize_index",
+					description: "Delete a Vectorize index.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "Index name to delete",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+						required: ["name"],
+					},
+				},
+				{
+					name: "get_vectorize_info",
+					description:
+						"Get information about a Vectorize index (dimensions, metric, vector count).",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "Index name",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+						required: ["name"],
+					},
+				},
 			],
 		};
 	});
@@ -550,6 +670,168 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 					};
 				}
 
+				case "create_vectorize_index": {
+					const args = CreateVectorizeIndexSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const wrappedCreateVectorizeIndex = withTelemetry(
+						"create_vectorize_index",
+						async (
+							projectDir: string,
+							name?: string,
+							dimensions?: number,
+							metric?: "cosine" | "euclidean" | "dot-product",
+						) => {
+							const result = await createVectorizeIndex(projectDir, {
+								name,
+								dimensions,
+								metric,
+							});
+
+							// Track business event
+							track(Events.SERVICE_CREATED, {
+								service_type: "vectorize",
+								platform: "mcp",
+							});
+
+							return {
+								index_name: result.indexName,
+								binding_name: result.bindingName,
+								dimensions: result.dimensions,
+								metric: result.metric,
+								created: result.created,
+								deploy_required: true,
+							};
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedCreateVectorizeIndex(
+						projectPath,
+						args.name,
+						args.dimensions,
+						args.metric,
+					);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "list_vectorize_indexes": {
+					const args = ListVectorizeIndexesSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const wrappedListVectorizeIndexes = withTelemetry(
+						"list_vectorize_indexes",
+						async (projectDir: string) => {
+							const indexes = await listVectorizeIndexes(projectDir);
+							return {
+								indexes: indexes.map((idx) => ({
+									name: idx.name,
+									binding: idx.binding,
+									dimensions: idx.dimensions,
+									metric: idx.metric,
+									vector_count: idx.vectorCount,
+								})),
+							};
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedListVectorizeIndexes(projectPath);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "delete_vectorize_index": {
+					const args = DeleteVectorizeIndexSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const wrappedDeleteVectorizeIndex = withTelemetry(
+						"delete_vectorize_index",
+						async (projectDir: string, indexName: string) => {
+							const result = await deleteVectorizeIndex(projectDir, indexName);
+
+							// Track business event
+							track(Events.SERVICE_DELETED, {
+								service_type: "vectorize",
+								platform: "mcp",
+							});
+
+							return {
+								index_name: result.indexName,
+								deleted: result.deleted,
+								binding_removed: result.bindingRemoved,
+							};
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedDeleteVectorizeIndex(projectPath, args.name);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
+				case "get_vectorize_info": {
+					const args = GetVectorizeInfoSchema.parse(request.params.arguments ?? {});
+
+					const wrappedGetVectorizeInfo = withTelemetry(
+						"get_vectorize_info",
+						async (indexName: string) => {
+							const info = await getVectorizeInfo(indexName);
+
+							if (!info) {
+								throw new JackError(
+									JackErrorCode.RESOURCE_NOT_FOUND,
+									`Vectorize index '${indexName}' not found`,
+									"Use list_vectorize_indexes to see available indexes",
+								);
+							}
+
+							return {
+								name: info.name,
+								dimensions: info.dimensions,
+								metric: info.metric,
+								vector_count: info.vectorCount,
+								created_on: info.createdOn,
+								modified_on: info.modifiedOn,
+							};
+						},
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedGetVectorizeInfo(args.name);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+							},
+						],
+					};
+				}
+
 				default:
 					throw new Error(`Unknown tool: ${toolName}`);
 			}