@getjack/jack 0.1.23 → 0.1.25

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}`);
 			}

package/templates/AI-BINDINGS.md

@@ -0,0 +1,181 @@
+# AI and Vectorize Bindings in Jack Cloud
+
+## Quick Reference for Coding Agents
+
+**DO NOT add `[ai]` or `[[vectorize]]` bindings directly for jack cloud projects.**
+
+Jack cloud uses metered proxies for AI and Vectorize calls. Use the patterns below:
+
+### AI Pattern
+
+```typescript
+import { createJackAI } from "./jack-ai";
+
+function getAI(env: Env) {
+  if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackAI(env);
+  }
+  if (env.AI) {
+    return env.AI;
+  }
+  throw new Error("No AI binding available");
+}
+
+// Usage:
+const ai = getAI(env);
+const result = await ai.run("@cf/meta/llama-3.2-1b-instruct", { messages });
+```
+
+### Vectorize Pattern
+
+```typescript
+import { createJackVectorize } from "./jack-vectorize";
+
+const INDEX_NAME = "my-vectors";
+
+function getVectorize(env: Env) {
+  if (env.__VECTORIZE_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackVectorize(env, INDEX_NAME);
+  }
+  if (env.VECTORS) {
+    return env.VECTORS;
+  }
+  throw new Error("No Vectorize binding available");
+}
+
+// Usage:
+const vectors = getVectorize(env);
+const results = await vectors.query(embedding, { topK: 10 });
+await vectors.insert([{ id: "doc1", values: embedding, metadata: {} }]);
+```
+
+## Why This Pattern?
+
+Jack cloud is multi-tenant. All users share Cloudflare's AI quota (10k neurons/day). Without metering:
+- One user could exhaust the daily quota for everyone
+- No visibility into per-project usage
+- No ability to bill for AI usage
+
+The proxy:
+1. Checks per-project quota
+2. Logs usage to Analytics Engine
+3. Forwards to real AI binding
+4. Returns response unchanged
+
+## Environment Bindings
+
+### Jack Cloud (Managed Deploy)
+
+Control plane injects these bindings:
+- `__AI_PROXY` - Service binding to jack-binding-proxy for AI
+- `__VECTORIZE_PROXY` - Service binding to jack-binding-proxy for Vectorize
+- `__JACK_PROJECT_ID` - Project ID for metering
+- `__JACK_ORG_ID` - Organization ID for billing
+
+`env.AI` and `env.VECTORS` are **NOT available** in jack cloud. Direct calls will fail.
+
+### Local Development
+
+wrangler.jsonc provides:
+- `AI` - Direct Cloudflare AI binding for local testing
+- `VECTORS` - Direct Vectorize binding for local testing
+
+The helper functions automatically use the right binding based on environment.
+
+## Template Pattern
+
+### AI Templates
+
+1. **src/jack-ai.ts** - Client wrapper (copy from ai-chat or semantic-search template)
+
+2. **Env interface** with optional bindings:
+```typescript
+interface Env {
+  AI?: Ai;                    // Local dev
+  __AI_PROXY?: Fetcher;       // Jack cloud
+  __JACK_PROJECT_ID?: string; // Jack cloud
+  __JACK_ORG_ID?: string;     // Jack cloud
+}
+```
+
+3. **getAI() helper** that handles both environments
+
+4. **wrangler.jsonc** with AI binding for local dev only:
+```jsonc
+{
+  "ai": { "binding": "AI" }
+}
+```
+
+### Vectorize Templates
+
+1. **src/jack-vectorize.ts** - Client wrapper (copy from semantic-search template)
+
+2. **Env interface** with optional bindings:
+```typescript
+interface Env {
+  VECTORS?: VectorizeIndex;      // Local dev
+  __VECTORIZE_PROXY?: Fetcher;   // Jack cloud
+  __JACK_PROJECT_ID?: string;    // Jack cloud
+  __JACK_ORG_ID?: string;        // Jack cloud
+}
+```
+
+3. **getVectorize() helper** that handles both environments
+
+4. **wrangler.jsonc** with Vectorize binding for local dev only:
+```jsonc
+{
+  "vectorize": [{
+    "binding": "VECTORS",
+    "index_name": "my-vectors",
+    "preset": "cloudflare"
+  }]
+}
+```
+
+## Error Handling
+
+Quota exceeded returns 429:
+
+### AI Quota
+```typescript
+try {
+  const result = await ai.run(model, inputs);
+} catch (error) {
+  if (error.code === "AI_QUOTA_EXCEEDED") {
+    // Daily limit (1000 requests) reached, resets at midnight UTC
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+}
+```
+
+### Vectorize Quota
+```typescript
+try {
+  const results = await vectors.query(embedding, { topK: 10 });
+} catch (error) {
+  if (error.code === "VECTORIZE_QUERY_QUOTA_EXCEEDED") {
+    // Query limit (33,000/day) reached
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+  if (error.code === "VECTORIZE_MUTATION_QUOTA_EXCEEDED") {
+    // Mutation limit (10,000/day) reached
+    console.log(`Retry in ${error.resetIn} seconds`);
+  }
+}
+```
+
+## BYOC Mode
+
+For Bring Your Own Cloud deployments:
+- User configures their own Cloudflare account
+- Direct AI binding is used (no proxy)
+- No metering (it's their account)
+- Standard Cloudflare docs apply
+
+## See Also
+
+- `/docs/internal/specs/binding-proxy-worker.md` - Full architecture spec
+- `apps/binding-proxy-worker/` - Proxy implementation
+- `apps/control-plane/src/deployment-service.ts` - Binding injection logic

package/templates/CLAUDE.md

@@ -6,6 +6,36 @@
 2. **Templates are for user code, not jack's tools** - wrangler is jack's responsibility (installed globally), not the template's
 3. **Ship a lockfile** - `bun.lock` provides 70% faster installs on cold cache
 
+## AI Bindings (IMPORTANT)
+
+**For jack cloud projects, DO NOT use direct AI bindings.**
+
+See [AI-BINDINGS.md](./AI-BINDINGS.md) for the full pattern.
+
+Quick summary:
+- Jack cloud uses a metered proxy (`__AI_PROXY`) instead of direct `env.AI`
+- Templates must include `src/jack-ai.ts` wrapper
+- Use `getAI(env)` helper instead of `env.AI` directly
+- wrangler.jsonc still declares `ai: { binding: "AI" }` for local dev only
+
+```typescript
+// WRONG for jack cloud:
+const result = await env.AI.run(model, inputs);
+
+// CORRECT (works for both local dev and jack cloud):
+import { createJackAI } from "./jack-ai";
+
+function getAI(env: Env) {
+  if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+    return createJackAI(env);
+  }
+  return env.AI;
+}
+
+const ai = getAI(env);
+const result = await ai.run(model, inputs);
+```
+
 ## Dependency Rules
 
 ### DO include in templates:

package/templates/ai-chat/.jack.json

@@ -4,7 +4,7 @@
 	"secrets": [],
 	"capabilities": ["ai"],
 	"intent": {
-		"keywords": ["ai", "chat", "llm", "mistral", "completion", "chatbot"],
+		"keywords": ["ai", "chat", "llm", "llama", "completion", "chatbot"],
 		"examples": ["AI chatbot", "chat interface", "LLM chat app"]
 	},
 	"hooks": {
@@ -16,12 +16,11 @@
 			},
 			{
 				"action": "box",
-				"title": "AI Chat: {{name}}",
+				"title": "{{name}}",
 				"lines": [
 					"{{url}}",
 					"",
-					"Open in browser to start chatting!",
-					"Rate limit: 10 requests/minute"
+					"jack open  to view in browser"
 				]
 			}
 		]

package/templates/ai-chat/src/index.ts

@@ -1,13 +1,46 @@
+import { createJackAI } from "./jack-ai";
+
 interface Env {
-	AI: Ai;
+	// Direct AI binding (for local dev with wrangler)
+	AI?: Ai;
+	// Jack proxy bindings (injected in jack cloud)
+	__AI_PROXY?: Fetcher;
+	__JACK_PROJECT_ID?: string;
+	__JACK_ORG_ID?: string;
+	// Assets binding
 	ASSETS: Fetcher;
 }
 
+function getAI(env: Env) {
+	// Prefer jack cloud proxy if available (for metering)
+	if (env.__AI_PROXY && env.__JACK_PROJECT_ID && env.__JACK_ORG_ID) {
+		return createJackAI(env as Required<Pick<Env, "__AI_PROXY" | "__JACK_PROJECT_ID" | "__JACK_ORG_ID">>);
+	}
+	// Fallback to direct binding for local dev
+	if (env.AI) {
+		return env.AI;
+	}
+	throw new Error("No AI binding available");
+}
+
 interface ChatMessage {
 	role: "user" | "assistant" | "system";
 	content: string;
 }
 
+// System prompt - customize this to change the AI's personality
+const SYSTEM_PROMPT = `You are a helpful AI assistant built with jack (getjack.sh).
+
+jack helps developers ship ideas fast - from "what if" to a live URL in seconds. You're running on Cloudflare's edge network, close to users worldwide.
+
+Be concise, friendly, and helpful. If asked about jack:
+- jack new creates projects from templates
+- jack ship deploys to production
+- jack open opens your app in browser
+- Docs: https://docs.getjack.sh
+
+Focus on being useful. Keep responses short unless detail is needed.`;
+
 // Rate limiting: 10 requests per minute per IP
 const RATE_LIMIT = 10;
 const RATE_WINDOW_MS = 60_000;
@@ -65,7 +98,7 @@ export default {
 
 			try {
 				const body = (await request.json()) as { messages?: ChatMessage[] };
-				const messages = body.messages;
+				let messages = body.messages;
 
 				if (!messages || !Array.isArray(messages)) {
 					return Response.json(
@@ -74,9 +107,16 @@ export default {
 					);
 				}
 
-				// Stream response using SSE
-				const stream = await env.AI.run(
-					"@cf/mistral/mistral-7b-instruct-v0.1",
+				// Prepend system prompt if not already present
+				if (messages.length === 0 || messages[0].role !== "system") {
+					messages = [{ role: "system", content: SYSTEM_PROMPT }, ...messages];
+				}
+
+				// Stream response using Llama 3.2 1B - cheapest model with good quality
+				// See: https://developers.cloudflare.com/workers-ai/models/
+				const ai = getAI(env);
+				const stream = await ai.run(
+					"@cf/meta/llama-3.2-1b-instruct",
 					{
 						messages,
 						stream: true,