@getjack/jack 0.1.31 → 0.1.33

package/src/mcp/resources/index.ts

@@ -31,6 +31,13 @@ export function registerResources(
 					description: "Semantic information about jack's capabilities for AI agents",
 					mimeType: "application/json",
 				},
+				{
+					uri: "agents://workflows",
+					name: "Workflow Recipes",
+					description:
+						"Multi-step workflow templates for common tasks like creating APIs with databases, debugging production issues, and setting up cron jobs",
+					mimeType: "text/markdown",
+				},
 			],
 		};
 	});
@@ -67,30 +74,15 @@ export function registerResources(
 
 		if (uri === "agents://context") {
 			const projectPath = options.projectPath ?? process.cwd();
-			const jackPath = join(projectPath, "JACK.md");
 			const agentsPath = join(projectPath, "AGENTS.md");
 			const claudePath = join(projectPath, "CLAUDE.md");
 
 			const contents: string[] = [];
 
-			// Try to read JACK.md first (jack-specific context)
-			if (existsSync(jackPath)) {
-				try {
-					const jackContent = await Bun.file(jackPath).text();
-					contents.push("# JACK.md\n\n");
-					contents.push(jackContent);
-				} catch {
-					// Ignore read errors
-				}
-			}
-
 			// Try to read AGENTS.md
 			if (existsSync(agentsPath)) {
 				try {
 					const agentsContent = await Bun.file(agentsPath).text();
-					if (contents.length > 0) {
-						contents.push("\n\n---\n\n");
-					}
 					contents.push("# AGENTS.md\n\n");
 					contents.push(agentsContent);
 				} catch {
@@ -136,7 +128,7 @@ If connected, prefer \`mcp__jack__*\` tools over CLI:
 
 Full docs: https://docs.getjack.org/llms-full.txt
 
-Check for JACK.md in the project root for project-specific instructions.
+Check AGENTS.md in the project root for project-specific instructions.
 `;
 				return {
 					contents: [
@@ -160,6 +152,172 @@ Check for JACK.md in the project root for project-specific instructions.
 			};
 		}
 
+		if (uri === "agents://workflows") {
+			const workflows = `# Jack Workflow Recipes
+
+Multi-step workflows for common tasks. Each workflow can be executed by an agent team or a single agent working sequentially.
+
+---
+
+## 1. Create API with Database
+
+Goal: Scaffold a new API, add a database, create tables, and verify.
+
+\`\`\`
+Step 1: Create project
+  jack new my-api --template api
+
+Step 2: Add database
+  mcp__jack__create_database (or: jack services db create)
+
+Step 3: Create schema
+  mcp__jack__execute_sql
+    sql: "CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT NOT NULL, created_at TEXT DEFAULT CURRENT_TIMESTAMP)"
+    allow_write: true
+
+Step 4: Edit src/index.ts — add routes that use c.env.DB
+
+Step 5: Deploy
+  mcp__jack__deploy_project (or: jack ship)
+
+Step 6: Verify
+  curl https://<slug>.runjack.xyz/api/items
+\`\`\`
+
+---
+
+## 2. Debug Production Issue
+
+Goal: Identify and fix a bug reported in production.
+
+\`\`\`
+Step 1: Check current status
+  mcp__jack__get_project_status (or: jack info)
+
+Step 2: Collect recent logs
+  mcp__jack__tail_logs with max_events: 100, duration_ms: 5000
+
+Step 3: Inspect database state if relevant
+  mcp__jack__execute_sql
+    sql: "SELECT * FROM <table> WHERE <condition>"
+
+Step 4: Read and fix the source code
+
+Step 5: Deploy fix
+  mcp__jack__deploy_project (or: jack ship)
+
+Step 6: Verify fix via logs
+  mcp__jack__tail_logs with max_events: 20, duration_ms: 3000
+\`\`\`
+
+---
+
+## 3. Add Scheduled Task (Cron)
+
+Goal: Run code on a schedule (cleanup, sync, reports).
+
+\`\`\`
+Step 1: Add scheduled handler to src/index.ts
+  export default {
+    async fetch(request, env) { ... },
+    async scheduled(event, env, ctx) {
+      // your cron logic here
+    },
+  };
+
+  Or with Hono, add a POST /__scheduled route.
+
+Step 2: Deploy the handler
+  mcp__jack__deploy_project (or: jack ship)
+
+Step 3: Create cron schedule
+  mcp__jack__create_cron with expression: "0 * * * *"
+  (or: jack services cron create "0 * * * *")
+
+Step 4: Verify schedule
+  mcp__jack__test_cron with expression: "0 * * * *"
+  Shows next 5 scheduled times.
+
+Step 5: Monitor via logs
+  mcp__jack__tail_logs
+\`\`\`
+
+---
+
+## 4. Add File Storage
+
+Goal: Enable file uploads and downloads via R2.
+
+\`\`\`
+Step 1: Create storage bucket
+  mcp__jack__create_storage_bucket (or: jack services storage create)
+
+Step 2: Deploy to activate binding
+  mcp__jack__deploy_project (or: jack ship)
+
+Step 3: Add upload/download routes to src/index.ts
+  Upload:  c.env.BUCKET.put(key, body)
+  Download: c.env.BUCKET.get(key)
+  List:    c.env.BUCKET.list()
+
+Step 4: Deploy routes
+  mcp__jack__deploy_project (or: jack ship)
+\`\`\`
+
+---
+
+## 5. Add Semantic Search (Vectorize + AI)
+
+Goal: Enable vector similarity search using embeddings.
+
+\`\`\`
+Step 1: Create vector index
+  mcp__jack__create_vectorize_index (or: jack services vectorize create)
+  Default: 768 dimensions, cosine metric (matches bge-base-en-v1.5)
+
+Step 2: Deploy to activate binding
+  mcp__jack__deploy_project (or: jack ship)
+
+Step 3: Add indexing route
+  Generate embedding: c.env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [input] })
+  Insert: c.env.VECTORIZE_INDEX.insert([{ id, values, metadata }])
+
+Step 4: Add search route
+  Generate query embedding, then:
+  c.env.VECTORIZE_INDEX.query(embedding, { topK: 5, returnMetadata: "all" })
+
+Step 5: Deploy and test
+  mcp__jack__deploy_project (or: jack ship)
+\`\`\`
+
+---
+
+## Parallel Task Patterns (Agent Teams)
+
+For Opus 4.6 Agent Teams, these tasks can run in parallel:
+
+**Independent (run simultaneously):**
+- Creating database + creating storage bucket
+- Reading logs + checking project status
+- Multiple SQL queries on different tables
+
+**Sequential (must wait for previous):**
+- Create project → then add services
+- Create database → then create tables → then deploy
+- Edit code → then deploy → then verify
+`;
+
+			return {
+				contents: [
+					{
+						uri,
+						mimeType: "text/markdown",
+						text: workflows,
+					},
+				],
+			};
+		}
+
 		throw new Error(`Unknown resource URI: ${uri}`);
 	});
 }

package/src/mcp/server.ts

@@ -43,8 +43,31 @@ export async function createMcpServer(options: McpServerOptions = {}) {
 	return { server, debug };
 }
 
+/**
+ * Install runtime guards that prevent accidental stdout writes from corrupting
+ * the MCP JSON-RPC stdio transport. This catches console.log() and
+ * process.stdout.write() but NOT Bun.spawn({ stdout: "inherit" }) which writes
+ * directly to fd 1 — that case is handled by the `interactive` flag in hooks.
+ */
+function installStdoutGuards() {
+	// Redirect console.log to stderr so accidental calls don't corrupt the stream.
+	// We don't wrap process.stdout.write because the MCP SDK writes JSON-RPC
+	// messages through it — intercepting those risks breaking the protocol if
+	// messages are chunked or newlines are written separately.
+	console.log = (...args: unknown[]) => {
+		console.error(
+			"[jack-mcp] WARNING: console.log intercepted (would corrupt MCP protocol):",
+			...args,
+		);
+	};
+}
+
 export async function startMcpServer(options: McpServerOptions = {}) {
 	const { server, debug } = await createMcpServer(options);
+
+	// Install stdout guards BEFORE connecting transport to prevent corruption
+	installStdoutGuards();
+
 	const transport = new StdioServerTransport();
 
 	debug("Starting MCP server on stdio transport");

package/src/mcp/tools/index.ts

@@ -7,6 +7,10 @@ import { JackError, JackErrorCode } from "../../lib/errors.ts";
 import { getDeployMode, getProjectId } from "../../lib/project-link.ts";
 import { createProject, deployProject, getProjectStatus } from "../../lib/project-operations.ts";
 import { listAllProjects } from "../../lib/project-resolver.ts";
+import { createCronSchedule } from "../../lib/services/cron-create.ts";
+import { deleteCronSchedule } from "../../lib/services/cron-delete.ts";
+import { listCronSchedules } from "../../lib/services/cron-list.ts";
+import { testCronExpression } from "../../lib/services/cron-test.ts";
 import { createDatabase } from "../../lib/services/db-create.ts";
 import {
 	DestructiveOperationError,
@@ -15,10 +19,6 @@ import {
 	wrapResultsForMcp,
 } from "../../lib/services/db-execute.ts";
 import { listDatabases } from "../../lib/services/db-list.ts";
-import { createCronSchedule } from "../../lib/services/cron-create.ts";
-import { deleteCronSchedule } from "../../lib/services/cron-delete.ts";
-import { listCronSchedules } from "../../lib/services/cron-list.ts";
-import { testCronExpression } from "../../lib/services/cron-test.ts";
 import {
 	assignDomain,
 	connectDomain,
@@ -41,7 +41,12 @@ import { formatErrorResponse, formatSuccessResponse } from "../utils.ts";
 // Tool schemas
 const CreateProjectSchema = z.object({
 	name: z.string().optional().describe("Project name (auto-generated if not provided)"),
-	template: z.string().optional().describe("Template to use (e.g., 'miniapp', 'api')"),
+	template: z
+		.string()
+		.optional()
+		.describe(
+			"Template to use (e.g., 'miniapp', 'api'). Also supports forking: use 'username/slug' for published projects or 'my-project' to fork your own.",
+		),
 });
 
 const DeployProjectSchema = z.object({
@@ -49,6 +54,12 @@ const DeployProjectSchema = z.object({
 		.string()
 		.optional()
 		.describe("Path to project directory (defaults to current directory)"),
+	message: z
+		.string()
+		.optional()
+		.describe(
+			"Deploy message describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug')",
+		),
 });
 
 const GetProjectStatusSchema = z.object({
@@ -200,6 +211,19 @@ const TailLogsSchema = z.object({
 		.describe("How long to listen before returning (default: 2000ms, max: 10000ms)"),
 });
 
+const RollbackProjectSchema = z.object({
+	deployment_id: z
+		.string()
+		.optional()
+		.describe(
+			"Specific deployment ID to roll back to (defaults to previous successful deployment)",
+		),
+	project_path: z
+		.string()
+		.optional()
+		.describe("Path to project directory (defaults to current directory)"),
+});
+
 const ListDomainsSchema = z.object({});
 
 const ConnectDomainSchema = z.object({
@@ -220,7 +244,9 @@ const DisconnectDomainSchema = z.object({
 });
 
 const CreateCronSchema = z.object({
-	expression: z.string().describe("Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)"),
+	expression: z
+		.string()
+		.describe("Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)"),
 	project_path: z
 		.string()
 		.optional()
@@ -264,7 +290,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "create_project",
 					description:
-						"Create a new Cloudflare Workers project from a template. Automatically installs dependencies, deploys to Cloudflare, and registers the project.",
+						"Create a new project from a template. Automatically installs dependencies, deploys, and registers the project. Also supports forking: pass a 'username/slug' template to fork a published project, or a project slug to fork your own.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -274,7 +300,8 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 							},
 							template: {
 								type: "string",
-								description: "Template to use (e.g., 'miniapp', 'api')",
+								description:
+									"Template to use (e.g., 'miniapp', 'api'). Also supports forking: use 'username/slug' for published projects or 'my-project' to fork your own.",
 							},
 						},
 					},
@@ -282,7 +309,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "deploy_project",
 					description:
-						"Deploy an existing project to Cloudflare Workers. Builds the project if needed and pushes to production.",
+						"Deploy an existing project. Builds if needed and pushes to production. Always provide a 'message' describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug').",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -290,13 +317,18 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 								type: "string",
 								description: "Path to project directory (defaults to current directory)",
 							},
+							message: {
+								type: "string",
+								description:
+									"Deploy message describing what changed and why (e.g., 'Add user auth', 'Fix CORS bug')",
+							},
 						},
 					},
 				},
 				{
 					name: "get_project_status",
 					description:
-						"Get detailed status information for a specific project, including deployment status, local path, and backup status.",
+						"Get live deployment state: URL, last deploy time, deploy count, status (live/failed), and deploy source. Call this first to understand what's currently deployed before making changes.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -347,7 +379,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "tail_logs",
 					description:
-						"Collect a short sample of live log events (JSON) from a managed (jack cloud) project. Useful for agentic debugging.",
+						"Collect live log events from production. Use after deploying to verify changes work, or to debug errors. Returns JSON log entries with timestamps and messages.",
 					inputSchema: {
 						type: "object",
 						properties: {
@@ -370,6 +402,27 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						},
 					},
 				},
+				{
+					name: "rollback_project",
+					description:
+						"Roll back a managed (jack cloud) project to a previous deployment. " +
+						"Defaults to the previous successful deployment if no deployment_id is specified. " +
+						"Only rolls back code — database state and secrets are unchanged.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							deployment_id: {
+								type: "string",
+								description:
+									"Specific deployment ID to roll back to (defaults to previous successful deployment)",
+							},
+							project_path: {
+								type: "string",
+								description: "Path to project directory (defaults to current directory)",
+							},
+						},
+					},
+				},
 				{
 					name: "create_database",
 					description:
@@ -654,13 +707,14 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 				{
 					name: "create_cron",
 					description:
-						"Create a cron schedule for a managed (Jack Cloud) project. Minimum interval is 15 minutes. The worker must have a scheduled() handler or POST /__scheduled route.",
+						"Create a cron schedule for a managed (Jack Cloud) project. Minimum interval is 15 minutes. The worker must handle POST /__scheduled requests — Cloudflare's native scheduled() export does not work with Jack Cloud crons.",
 					inputSchema: {
 						type: "object",
 						properties: {
 							expression: {
 								type: "string",
-								description: "Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)",
+								description:
+									"Cron expression (e.g., '0 * * * *' for hourly, '*/15 * * * *' for every 15 min)",
 							},
 							project_path: {
 								type: "string",
@@ -719,7 +773,8 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 							trigger_production: {
 								type: "boolean",
 								default: false,
-								description: "Whether to trigger the cron handler on production (requires managed project)",
+								description:
+									"Whether to trigger the cron handler on production (requires managed project)",
 							},
 						},
 						required: ["expression"],
@@ -777,12 +832,13 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 
 					const wrappedDeployProject = withTelemetry(
 						"deploy_project",
-						async (projectPath?: string) => {
+						async (projectPath?: string, message?: string) => {
 							const result = await deployProject({
 								projectPath,
 								interactive: false,
 								includeSecrets: false,
 								includeSync: false,
+								message,
 							});
 
 							// Track business event
@@ -795,7 +851,7 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						{ platform: "mcp" },
 					);
 
-					const result = await wrappedDeployProject(args.project_path);
+					const result = await wrappedDeployProject(args.project_path, args.message);
 
 					return {
 						content: [
@@ -1046,6 +1102,60 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 					};
 				}
 
+				case "rollback_project": {
+					const args = RollbackProjectSchema.parse(request.params.arguments ?? {});
+					const projectPath = args.project_path ?? process.cwd();
+
+					const deployMode = await getDeployMode(projectPath);
+					if (deployMode !== "managed") {
+						throw new JackError(
+							JackErrorCode.VALIDATION_ERROR,
+							"Rollback is only available for managed (jack cloud) projects",
+							"For BYOC projects, use wrangler to manage deployments.",
+						);
+					}
+
+					const projectId = await getProjectId(projectPath);
+					if (!projectId) {
+						throw new JackError(
+							JackErrorCode.PROJECT_NOT_FOUND,
+							"Project not found",
+							"Run this from a linked jack cloud project directory (has .jack/project.json).",
+						);
+					}
+
+					// Import rollbackDeployment from control-plane
+					const { rollbackDeployment } = await import("../../lib/control-plane.ts");
+
+					const wrappedRollback = withTelemetry(
+						"rollback_project",
+						async (id: string, deploymentId?: string) => rollbackDeployment(id, deploymentId),
+						{ platform: "mcp" },
+					);
+
+					const result = await wrappedRollback(projectId, args.deployment_id);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(
+									formatSuccessResponse(
+										{
+											...result.deployment,
+											message:
+												"Code rolled back successfully. Database state and secrets are unchanged.",
+										},
+										startTime,
+									),
+									null,
+									2,
+								),
+							},
+						],
+					};
+				}
+
 				case "create_database": {
 					const args = CreateDatabaseSchema.parse(request.params.arguments ?? {});
 					const projectPath = args.project_path ?? process.cwd();
@@ -1268,7 +1378,13 @@ export function registerTools(server: McpServer, _options: McpServerOptions, deb
 						content: [
 							{
 								type: "text",
-								text: JSON.stringify(formatSuccessResponse(result, startTime), null, 2),
+								text: JSON.stringify(
+									formatSuccessResponse(result, startTime, [
+										"Vectorize indexes have eventual consistency. Newly inserted vectors typically take 2-3 minutes to become queryable.",
+									]),
+									null,
+									2,
+								),
 							},
 						],
 					};

package/src/mcp/types.ts

@@ -5,6 +5,7 @@
 export interface McpToolResponse<T = unknown> {
 	success: boolean;
 	data?: T;
+	notes?: string[]; // Situational context for AI agents (e.g. eventual consistency caveats)
 	error?: {
 		code: string; // Machine-readable: 'AUTH_FAILED', 'PROJECT_NOT_FOUND'
 		message: string; // Human-readable description

package/src/mcp/utils.ts

@@ -5,10 +5,11 @@ import { McpErrorCode, type McpToolResponse } from "./types.ts";
 /**
  * Format a successful MCP tool response
  */
-export function formatSuccessResponse<T>(data: T, startTime: number): McpToolResponse<T> {
+export function formatSuccessResponse<T>(data: T, startTime: number, notes?: string[]): McpToolResponse<T> {
 	return {
 		success: true,
 		data,
+		...(notes?.length && { notes }),
 		meta: {
 			duration_ms: Date.now() - startTime,
 			jack_version: packageJson.version,