veryfront 0.1.141 → 0.1.142

package/esm/src/issues/mcp.js

@@ -31,8 +31,11 @@ const issuesCreateInput = createIssueSchema.extend({
 }).merge(projectDirSchema);
 const issuesCreate = {
     name: "issues_create",
-    description: "Create a new issue, task, or plan as a markdown file. " +
-        "Use prefix 'TASK' for small work items, 'PLAN' for proposals/RFCs, 'ISSUE' for bugs/features.",
+    title: "Create Issue",
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    description: "Use this when you need to create a new issue, task, or plan as a markdown file. " +
+        "Use prefix 'TASK' for small work items, 'PLAN' for proposals/RFCs, 'ISSUE' for bugs/features. " +
+        "Returns the created issue. Do not use for updating — use issues_update instead.",
     inputSchema: issuesCreateInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);
@@ -54,7 +57,9 @@ const issuesGetInput = projectDirSchema.extend({
 });
 const issuesGet = {
     name: "issues_get",
-    description: "Get a specific issue by ID. Returns null if not found.",
+    title: "Get Issue",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to retrieve a specific issue by its ID. Returns the issue or null if not found. Do not use for listing — use issues_list instead.",
     inputSchema: issuesGetInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);
@@ -75,8 +80,15 @@ const issuesUpdateInput = updateIssueSchema.extend({
 }).merge(projectDirSchema);
 const issuesUpdate = {
     name: "issues_update",
-    description: "Update an existing issue. Only provided fields are updated. " +
-        "Returns the updated issue or null if not found.",
+    title: "Update Issue",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to modify an existing issue. Only provided fields are updated. " +
+        "Returns the updated issue or null if not found. Do not use to close — use issues_close instead.",
     inputSchema: issuesUpdateInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);
@@ -114,8 +126,10 @@ const issuesListInput = listIssuesSchema.extend({
 }).merge(projectDirSchema);
 const issuesList = {
     name: "issues_list",
-    description: "List issues with filtering and sorting. " +
-        "Returns matching issues and total count.",
+    title: "List Issues",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to find issues matching criteria. " +
+        "Returns matching issues and total count. Do not use to get a single known issue — use issues_get instead.",
     inputSchema: issuesListInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);
@@ -139,7 +153,14 @@ const issuesCloseInput = projectDirSchema.extend({
 });
 const issuesClose = {
     name: "issues_close",
-    description: "Close an issue. Returns the updated issue or null if not found.",
+    title: "Close Issue",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to close an issue. Returns the updated issue or null if not found. Do not use to delete — use issues_delete instead.",
     inputSchema: issuesCloseInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);
@@ -154,8 +175,16 @@ const issuesDeleteInput = projectDirSchema.extend({
 });
 const issuesDelete = {
     name: "issues_delete",
-    description: "Permanently delete an issue file. " +
-        "Use with caution - this cannot be undone.",
+    title: "Delete Issue",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to permanently delete an issue. Returns {deleted: true/false}. " +
+        "WARNING: this is irreversible and cannot be undone. Prefer issues_close unless permanent deletion is explicitly requested. " +
+        "Do not use to close — use issues_close instead.",
     inputSchema: issuesDeleteInput,
     execute: async (input) => {
         const manager = getManager(input.projectDir);

package/esm/src/mcp/index.d.ts

@@ -22,7 +22,7 @@
  * ```
  */
 import "../../_dnt.polyfills.js";
-export type { MCPServerConfig, MCPStats, MCPTool } from "./types.js";
+export type { MCPServerConfig, MCPStats, MCPTool, ToolAnnotations, ToolListEntry, } from "./types.js";
 export { clearMCPRegistry, getMCPRegistry, getMCPStats, registerPrompt, registerResource, registerTool, } from "./registry.js";
 export { createMCPServer, type IntegrationLoaderConfig, MCPServer } from "./server.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,KAAK,uBAAuB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,YAAY,EACV,eAAe,EACf,QAAQ,EACR,OAAO,EACP,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,KAAK,uBAAuB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/esm/src/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAG/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAWzE,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;AAoCzD,UAAU,cAAc;IACtB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAAC;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,iBAAiB,CAAC,CAA0B;IACpD,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAQnC;;;;;;OAMG;IACH,oBAAoB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAK3D,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBhG,OAAO,CAAC,QAAQ;IA8BhB,OAAO,CAAC,UAAU;YAYJ,SAAS;IA0BvB,OAAO,CAAC,QAAQ;IAmChB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,YAAY;IA6CpB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,SAAS;IAuCjB,iBAAiB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAiD5E,OAAO,CAAC,qBAAqB;YAgBf,YAAY;IAsB1B,OAAO,CAAC,cAAc;YAqBR,0BAA0B;CAqBzC;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAElE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAG/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,YAAY,CAAC;AAMjE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAWzE,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;AA4DzD,UAAU,cAAc;IACtB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAAC;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,iBAAiB,CAAC,CAA0B;IACpD,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAQnC;;;;;;OAMG;IACH,oBAAoB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAK3D,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAmBhG,OAAO,CAAC,QAAQ;IAgChB,OAAO,CAAC,UAAU;YA0BJ,SAAS;IA6BvB,OAAO,CAAC,QAAQ;IAgDhB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,YAAY;IA6CpB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,SAAS;IAuCjB,iBAAiB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAuD5E,OAAO,CAAC,qBAAqB;YAgBf,YAAY;IAsB1B,OAAO,CAAC,cAAc;YAqBR,0BAA0B;CAqBzC;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAElE"}

package/esm/src/mcp/server.js

@@ -16,6 +16,29 @@ const MAX_CONTEXT_HEADER_LENGTH = 255;
 const JSON_CONTENT_TYPE = "application/json";
 const END_USER_ID_PATTERN = /^[a-zA-Z0-9._@-]+$/;
 const PROJECT_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
+class JsonRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function errorCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        if (typeof code === "number")
+            return code;
+    }
+    return -32603;
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null && "message" in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
 function toParamsRecord(params) {
     if (!params || Array.isArray(params))
         return {};
@@ -40,6 +63,7 @@ function readAllowedHeader(request, headerName, pattern) {
     }
     return value;
 }
+const MCP_SUPPORTED_VERSIONS = ["2025-11-25", "2024-11-05"];
 export class MCPServer {
     config;
     integrationLoader;
@@ -71,10 +95,7 @@ export class MCPServer {
                 return {
                     jsonrpc: "2.0",
                     id: request.id,
-                    error: {
-                        code: -32603,
-                        message: error instanceof Error ? error.message : String(error),
-                    },
+                    error: { code: errorCode(error), message: errorMessage(error) },
                 };
             }
         }, { "mcp.method": request.method });
@@ -95,6 +116,8 @@ export class MCPServer {
                 return this.getPrompt(params);
             case "initialize":
                 return this.initialize(params);
+            case "notifications/initialized":
+                return Promise.resolve({});
             default:
                 throw toError(createError({
                     type: "agent",
@@ -102,15 +125,26 @@ export class MCPServer {
                 }));
         }
     }
-    initialize(_params) {
+    initialize(params) {
+        const p = toParamsRecord(params);
+        const requested = typeof p.protocolVersion === "string" ? p.protocolVersion : undefined;
+        const negotiated = requested && MCP_SUPPORTED_VERSIONS.includes(requested)
+            ? requested
+            : MCP_SUPPORTED_VERSIONS[0];
         return Promise.resolve({
-            protocolVersion: "2024-11-05",
-            serverInfo: { name: "veryfront-mcp", version: VERSION },
+            protocolVersion: negotiated,
+            serverInfo: {
+                name: "veryfront-mcp",
+                title: "Veryfront MCP Server",
+                version: VERSION,
+                description: "Veryfront development server tools for real-time errors, route preview, HMR control, and scaffolding",
+            },
             capabilities: {
-                tools: {},
-                resources: { subscribe: true },
-                prompts: {},
+                tools: { listChanged: true },
+                resources: { subscribe: true, listChanged: true },
+                prompts: { listChanged: true },
             },
+            instructions: "Veryfront MCP server provides development tools. Use vf_get_errors to check for code errors, vf_get_logs for server logs, vf_scaffold for code generation, and vf_get_project_context for project structure.",
         });
     }
     async listTools() {
@@ -128,33 +162,54 @@ export class MCPServer {
         for (const [id, tool] of registry.tools.entries()) {
             if (tool.mcp?.enabled === false)
                 continue;
-            tools.push({
+            const entry = {
                 name: id,
                 description: tool.description,
                 inputSchema: tool.inputSchemaJson ?? zodToJsonSchema(tool.inputSchema),
-            });
+            };
+            if (tool.mcp?.title)
+                entry.title = tool.mcp.title;
+            if (tool.mcp?.annotations)
+                entry.annotations = tool.mcp.annotations;
+            tools.push(entry);
         }
         return { tools };
     }
     callTool(params, context) {
         const { name, arguments: args } = toParamsRecord(params);
         if (!name) {
-            throw toError(createError({
-                type: "agent",
-                message: "Tool name is required",
-            }));
+            throw toError(createError({ type: "agent", message: "Tool name is required" }));
         }
         const toolName = String(name);
+        const registry = getMCPRegistry();
+        const tool = registry.tools.get(toolName);
+        if (!tool) {
+            throw new JsonRpcError(-32602, `Unknown tool: ${toolName}`);
+        }
+        if (tool.inputSchema && typeof tool.inputSchema.parse === "function") {
+            try {
+                tool.inputSchema.parse(args ?? {});
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new JsonRpcError(-32602, `Invalid arguments for tool ${toolName}: ${message}`);
+            }
+        }
         return withSpan("mcp.callTool", async () => {
-            const result = await executeTool(toolName, args, context);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            try {
+                const result = await executeTool(toolName, args, context);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    isError: false,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: "text", text: message }],
+                    isError: true,
+                };
+            }
         }, { "mcp.tool.name": toolName });
     }
     listResources() {
@@ -242,6 +297,11 @@ export class MCPServer {
             if (request.method === "OPTIONS") {
                 return new dntShim.Response(null, { status: 204, headers: this.getCORSHeaders(requestOrigin) });
             }
+            if (requestOrigin && this.config.cors?.enabled && this.config.cors.origins?.length) {
+                if (!this.config.cors.origins.includes(requestOrigin)) {
+                    return createJSONRPCErrorResponse(403, -32600, "Forbidden: Origin not allowed");
+                }
+            }
             if (this.config.auth?.type && this.config.auth.type !== "none") {
                 const authorized = await this.validateAuth(request);
                 if (!authorized)

package/esm/src/mcp/types.d.ts

@@ -2,6 +2,16 @@ import type { z } from "zod";
 import type { Tool } from "../tool/index.js";
 import type { Resource } from "../resource/index.js";
 import type { Prompt } from "../prompt/index.js";
+/**
+ * Behavioral hints for MCP clients (MCP 2025-11-25).
+ * Guides auto-approval, confirmation prompts, and caching.
+ */
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 /**
  * Generic MCP tool definition
  */
@@ -10,6 +20,18 @@ export interface MCPTool<TInput = any, TOutput = any> {
     description: string;
     inputSchema: z.ZodType<TInput, any, any>;
     execute: (input: TInput) => Promise<TOutput>;
+    title?: string;
+    annotations?: ToolAnnotations;
+}
+/**
+ * Wire format for a single tool in a tools/list response.
+ */
+export interface ToolListEntry {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    title?: string;
+    annotations?: ToolAnnotations;
 }
 export interface MCPRegistry {
     tools: Map<string, Tool>;

package/esm/src/mcp/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AAEH,MAAM,WAAW,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAGD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/mcp/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AAEH,MAAM,WAAW,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAGD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/esm/src/tool/types.d.ts

@@ -4,6 +4,7 @@
 import type { z } from "zod";
 import type { JsonSchema } from "./schema/json-schema.js";
 import type { BlobStorage } from "../workflow/blob/types.js";
+import type { ToolAnnotations } from "../mcp/types.js";
 /**
  * Tool configuration options
  */
@@ -31,6 +32,10 @@ export interface ToolConfig<TInput = any, TOutput = any> {
         requiresAuth?: boolean;
         /** Cache policy */
         cachePolicy?: "no-cache" | "cache" | "cache-first";
+        /** Human-readable title for display */
+        title?: string;
+        /** Behavioral hints for clients (MCP 2025-11-25) */
+        annotations?: ToolAnnotations;
     };
 }
 /**

package/esm/src/tool/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/tool/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;GAEG;AAEH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IACrD,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IAEpB,gCAAgC;IAChC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAEvF,wBAAwB;IACxB,GAAG,CAAC,EAAE;QACJ,qBAAqB;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB,6BAA6B;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;QAEvB,mBAAmB;QACnB,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;KACpD,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,sDAAsD;IACtD,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;GAIG;AACH,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvC;;GAEG;AAEH,MAAM,WAAW,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAC/C,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,IAAI,EAAE,QAAQ,CAAC;IAEf,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IAEpB,yBAAyB;IACzB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,eAAe,CAAC,EAAE,UAAU,CAAC;IAE7B;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7E,wBAAwB;IACxB,GAAG,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/tool/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;GAEG;AAEH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IACrD,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IAEpB,gCAAgC;IAChC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAEvF,wBAAwB;IACxB,GAAG,CAAC,EAAE;QACJ,qBAAqB;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB,6BAA6B;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;QAEvB,mBAAmB;QACnB,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;QAEnD,uCAAuC;QACvC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,oDAAoD;QACpD,WAAW,CAAC,EAAE,eAAe,CAAC;KAC/B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,sDAAsD;IACtD,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;GAIG;AACH,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvC;;GAEG;AAEH,MAAM,WAAW,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAC/C,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,IAAI,EAAE,QAAQ,CAAC;IAEf,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IAEpB,yBAAyB;IACzB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,eAAe,CAAC,EAAE,UAAU,CAAC;IAE7B;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7E,wBAAwB;IACxB,GAAG,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB"}

package/esm/src/utils/version-constant.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.141";
+export declare const VERSION = "0.1.142";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

@@ -1,3 +1,3 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.141";
+export const VERSION = "0.1.142";

package/esm/src/workflow/schemas/workflow.schema.d.ts

@@ -10,8 +10,8 @@ import { z } from "zod";
 export declare const WorkflowStatusSchema: z.ZodEnum<{
     waiting: "waiting";
     failed: "failed";
-    completed: "completed";
     pending: "pending";
+    completed: "completed";
     running: "running";
     cancelled: "cancelled";
 }>;
@@ -21,8 +21,8 @@ export declare const WorkflowStatusSchema: z.ZodEnum<{
 export declare const NodeStatusSchema: z.ZodEnum<{
     skipped: "skipped";
     failed: "failed";
-    completed: "completed";
     pending: "pending";
+    completed: "completed";
     running: "running";
 }>;
 /**
@@ -76,8 +76,8 @@ export declare const NodeStateSchema: z.ZodObject<{
     status: z.ZodEnum<{
         skipped: "skipped";
         failed: "failed";
-        completed: "completed";
         pending: "pending";
+        completed: "completed";
         running: "running";
     }>;
     input: z.ZodOptional<z.ZodUnknown>;
@@ -108,8 +108,8 @@ export declare const CheckpointSchema: z.ZodObject<{
         status: z.ZodEnum<{
             skipped: "skipped";
             failed: "failed";
-            completed: "completed";
             pending: "pending";
+            completed: "completed";
             running: "running";
         }>;
         input: z.ZodOptional<z.ZodUnknown>;
@@ -184,15 +184,15 @@ export declare const RunFilterSchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         waiting: "waiting";
         failed: "failed";
-        completed: "completed";
         pending: "pending";
+        completed: "completed";
         running: "running";
         cancelled: "cancelled";
     }>, z.ZodArray<z.ZodEnum<{
         waiting: "waiting";
         failed: "failed";
-        completed: "completed";
         pending: "pending";
+        completed: "completed";
         running: "running";
         cancelled: "cancelled";
     }>>]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.141",
+  "version": "0.1.142",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/cli/mcp/jsonrpc.ts

@@ -43,6 +43,18 @@ export const JSONRPC_ERRORS = {
   INTERNAL_ERROR: -32603,
 } as const;
 
+/**
+ * Error with a JSON-RPC error code attached.
+ * Preserves stack traces unlike throwing plain objects.
+ */
+export class JsonRpcError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
 /**
  * Create a JSON-RPC parse error response
  */
@@ -70,15 +82,71 @@ export function successResponse(id: string | number | undefined, result: unknown
 export function errorResponse(
   id: string | number | undefined,
   e: unknown,
-  code = JSONRPC_ERRORS.INTERNAL_ERROR,
+  code?: number,
 ): JSONRPCResponse {
+  const errorCode = typeof e === "object" && e !== null && "code" in e
+    ? (e as { code: unknown }).code
+    : undefined;
+  const resolvedCode = code ??
+    (typeof errorCode === "number" ? errorCode : JSONRPC_ERRORS.INTERNAL_ERROR);
+  const message = e instanceof Error
+    ? e.message
+    : typeof e === "object" && e !== null && "message" in e
+    ? String((e as { message: unknown }).message)
+    : String(e);
   return {
     jsonrpc: "2.0",
     id,
-    error: {
-      code,
-      message: e instanceof Error ? e.message : String(e),
+    error: { code: resolvedCode, message },
+  };
+}
+
+/**
+ * Supported MCP protocol versions (newest first).
+ * Shared across all CLI MCP servers so the version list is maintained in one place.
+ */
+export const MCP_SUPPORTED_VERSIONS: [string, ...string[]] = ["2025-11-25", "2024-11-05"];
+
+/**
+ * Safely extract a record from unknown params (mirrors src/mcp toParamsRecord).
+ */
+export function toParamsRecord(params: unknown): Record<string, unknown> {
+  if (params && typeof params === "object" && !Array.isArray(params)) {
+    return params as Record<string, unknown>;
+  }
+  return {};
+}
+
+/**
+ * Negotiate MCP protocol version: echo the client's version if supported,
+ * otherwise fall back to the newest supported version.
+ */
+export function negotiateVersion(params: unknown): string {
+  const p = toParamsRecord(params);
+  const requested = typeof p.protocolVersion === "string" ? p.protocolVersion : undefined;
+  return requested && MCP_SUPPORTED_VERSIONS.includes(requested)
+    ? requested
+    : MCP_SUPPORTED_VERSIONS[0];
+}
+
+/**
+ * Build a complete MCP initialize result with negotiated version,
+ * capabilities, serverInfo, and instructions.
+ */
+export function buildInitializeResult(
+  params: unknown,
+  serverInfo: { name: string; title: string; version: string; description: string },
+  instructions: string,
+): Record<string, unknown> {
+  return {
+    protocolVersion: negotiateVersion(params),
+    capabilities: {
+      tools: { listChanged: true },
+      resources: { listChanged: true },
+      prompts: { listChanged: true },
     },
+    serverInfo,
+    instructions,
   };
 }
 

package/src/cli/mcp/remote-file-tools.ts

@@ -200,6 +200,8 @@ interface RemoteListFilesOutput {
 
 export const vfRemoteListFiles: MCPTool<RemoteListFilesInput, RemoteListFilesOutput> = {
   name: "vf_remote_list_files",
+  title: "List Remote Files",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "List files in a remote Veryfront project. Returns file paths, types, and sizes. Use this to explore a project's structure.",
   inputSchema: remoteListFilesInput,
@@ -249,6 +251,8 @@ interface RemoteGetFileOutput {
 
 export const vfRemoteGetFile: MCPTool<RemoteGetFileInput, RemoteGetFileOutput> = {
   name: "vf_remote_get_file",
+  title: "Get Remote File",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "Read the content of a file from a remote Veryfront project. Always use this before modifying a file.",
   inputSchema: remoteGetFileInput,
@@ -296,6 +300,13 @@ interface RemoteUpdateFileOutput {
 
 export const vfRemoteUpdateFile: MCPTool<RemoteUpdateFileInput, RemoteUpdateFileOutput> = {
   name: "vf_remote_update_file",
+  title: "Update Remote File",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
     "Create or update a file in a remote Veryfront project. Always read the file first before updating to understand its current state.",
   inputSchema: remoteUpdateFileInput,
@@ -341,6 +352,13 @@ interface RemoteDeleteFileOutput {
 
 export const vfRemoteDeleteFile: MCPTool<RemoteDeleteFileInput, RemoteDeleteFileOutput> = {
   name: "vf_remote_delete_file",
+  title: "Delete Remote File",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description: "Delete a file from a remote Veryfront project.",
   inputSchema: remoteDeleteFileInput,
   execute: async (input) => {
@@ -378,6 +396,8 @@ interface RemoteSearchFilesOutput {
 
 export const vfRemoteSearchFiles: MCPTool<RemoteSearchFilesInput, RemoteSearchFilesOutput> = {
   name: "vf_remote_search_files",
+  title: "Search Remote Files",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
     "Search for text patterns within file contents in a remote Veryfront project. Supports regex and glob patterns.",
   inputSchema: remoteSearchFilesInput,
@@ -430,6 +450,8 @@ interface RemoteMoveFileOutput {
 
 export const vfRemoteMoveFile: MCPTool<RemoteMoveFileInput, RemoteMoveFileOutput> = {
   name: "vf_remote_move_file",
+  title: "Move Remote File",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: "Move or rename a file in a remote Veryfront project.",
   inputSchema: remoteMoveFileInput,
   execute: async (input) => {
@@ -477,6 +499,8 @@ interface RemoteListBranchesOutput {
 
 export const vfRemoteListBranches: MCPTool<RemoteListBranchesInput, RemoteListBranchesOutput> = {
   name: "vf_remote_list_branches",
+  title: "List Remote Branches",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description: "List branches in a remote Veryfront project.",
   inputSchema: remoteListBranchesInput,
   execute: async (input) => {
@@ -514,6 +538,8 @@ interface RemoteCreateBranchOutput {
 
 export const vfRemoteCreateBranch: MCPTool<RemoteCreateBranchInput, RemoteCreateBranchOutput> = {
   name: "vf_remote_create_branch",
+  title: "Create Remote Branch",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
     "Create a new branch in a remote Veryfront project. Branch from main by default, or specify a base branch.",
   inputSchema: remoteCreateBranchInput,
@@ -552,6 +578,8 @@ interface RemoteMergeBranchOutput {
 
 export const vfRemoteMergeBranch: MCPTool<RemoteMergeBranchInput, RemoteMergeBranchOutput> = {
   name: "vf_remote_merge_branch",
+  title: "Merge Remote Branch",
+  annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   description: "Merge a branch into the target branch (or main if not specified).",
   inputSchema: remoteMergeBranchInput,
   execute: async (input) => {
@@ -596,6 +624,13 @@ interface RemoteDeleteBranchOutput {
 
 export const vfRemoteDeleteBranch: MCPTool<RemoteDeleteBranchInput, RemoteDeleteBranchOutput> = {
   name: "vf_remote_delete_branch",
+  title: "Delete Remote Branch",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description: "Delete a branch from a remote Veryfront project.",
   inputSchema: remoteDeleteBranchInput,
   execute: async (input) => {
@@ -633,6 +668,8 @@ interface RemoteCreateProjectOutput {
 
 export const vfRemoteCreateProject: MCPTool<RemoteCreateProjectInput, RemoteCreateProjectOutput> = {
   name: "vf_remote_create_project",
+  title: "Create Remote Project",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description: "Create a new Veryfront project. Returns the project details including ID and slug.",
   inputSchema: remoteCreateProjectInput,
   execute: async (input) => {
@@ -671,6 +708,8 @@ interface RemoteCloneProjectOutput {
 
 export const vfRemoteCloneProject: MCPTool<RemoteCloneProjectInput, RemoteCloneProjectOutput> = {
   name: "vf_remote_clone_project",
+  title: "Clone Remote Project",
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   description:
     "Clone a Veryfront project by creating a new project and copying all files from the source.",
   inputSchema: remoteCloneProjectInput,