veryfront 0.1.140 → 0.1.142

package/src/src/mcp/server.ts

@@ -5,7 +5,7 @@ import type { ToolExecutionContext } from "../tool/index.js";
 import { zodToJsonSchema } from "../tool/schema/index.js";
 import { resourceRegistry } from "../resource/index.js";
 import { promptRegistry } from "../prompt/index.js";
-import type { MCPServerConfig } from "./types.js";
+import type { MCPServerConfig, ToolListEntry } from "./types.js";
 import { createError, toError } from "../errors/veryfront-error.js";
 import { withSpan } from "../observability/tracing/otlp-setup.js";
 import { VERSION } from "../utils/version.js";
@@ -24,6 +24,30 @@ const PROJECT_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
 
 type JSONRPCParams = Record<string, unknown> | unknown[];
 
+class JsonRpcError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function errorCode(error: unknown): number {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const code = (error as { code: unknown }).code;
+    if (typeof code === "number") return code;
+  }
+  return -32603;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "object" && error !== null && "message" in error) {
+    return String((error as { message: unknown }).message);
+  }
+  return String(error);
+}
+
 function toParamsRecord(params: JSONRPCParams | undefined): Record<string, unknown> {
   if (!params || Array.isArray(params)) return {};
   return params;
@@ -82,6 +106,8 @@ export interface IntegrationLoaderConfig {
   apiToken?: string;
 }
 
+const MCP_SUPPORTED_VERSIONS = ["2025-11-25", "2024-11-05"];
+
 export class MCPServer {
   private config: MCPServerConfig;
   private integrationLoader?: IntegrationLoaderConfig;
@@ -118,10 +144,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) },
           };
         }
       },
@@ -149,6 +172,8 @@ export class MCPServer {
         return this.getPrompt(params);
       case "initialize":
         return this.initialize(params);
+      case "notifications/initialized":
+        return Promise.resolve({});
       default:
         throw toError(
           createError({
@@ -159,19 +184,33 @@ export class MCPServer {
     }
   }
 
-  private initialize(_params: JSONRPCParams | undefined): Promise<Record<string, unknown>> {
+  private initialize(params: JSONRPCParams | undefined): Promise<Record<string, unknown>> {
+    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.",
     });
   }
 
-  private async listTools(): Promise<{ tools: Array<Record<string, unknown>> }> {
+  private async listTools(): Promise<{ tools: ToolListEntry[] }> {
     // Sync integration config to API on first tools/list call
     if (this.integrationLoader && !this.integrationsLoaded) {
       try {
@@ -182,16 +221,19 @@ export class MCPServer {
     }
 
     const registry = getMCPRegistry();
-    const tools: Array<Record<string, unknown>> = [];
+    const tools: ToolListEntry[] = [];
 
     for (const [id, tool] of registry.tools.entries()) {
       if (tool.mcp?.enabled === false) continue;
 
-      tools.push({
+      const entry: ToolListEntry = {
         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 };
@@ -204,29 +246,42 @@ export class MCPServer {
     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 },
     );
@@ -353,6 +408,12 @@ export class MCPServer {
         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) return new dntShim.Response("Unauthorized", { status: 401 });

package/src/src/mcp/types.ts

@@ -3,6 +3,17 @@ 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
  */
@@ -13,6 +24,19 @@ export interface MCPTool<TInput = any, TOutput = any> {
   // deno-lint-ignore no-explicit-any -- ZodType Def/Input params require any for ZodDefault/ZodOptional compatibility
   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 {

package/src/src/server/handlers/request/agent-stream.handler.ts

@@ -31,6 +31,7 @@ import { BaseHandler } from "../response/base.js";
 import type { HandlerContext, HandlerMetadata, HandlerPriority, HandlerResult } from "../types.js";
 import { PRIORITY_MEDIUM_API } from "../../../utils/constants/index.js";
 import { getHostEnv } from "../../../platform/compat/process.js";
+import { serverLogger } from "../../../utils/index.js";
 
 export interface AgentStreamHandlerDeps
   extends RuntimeAgentDiscoveryDeps, RuntimeAgentStreamExecutionDeps {
@@ -42,6 +43,7 @@ const defaultDeps: AgentStreamHandlerDeps = {
   sessionManager: agentRunSessionManager,
   resolveRuntimeOwnerInvokeUrl,
 };
+const logger = serverLogger.component("agent-stream-handler");
 
 type SourceContextFsWrapper = {
   isMultiProjectMode?: () => boolean;
@@ -165,6 +167,16 @@ export class AgentStreamHandler extends BaseHandler {
           expectedSubject: payload.runId,
           expectedSurface: "studio",
         });
+        logger.info("Accepted internal agent stream request", {
+          runId: payload.runId,
+          threadId: payload.threadId,
+          agentId: payload.agentId,
+          projectId: ctx.projectId,
+          projectSlug: ctx.projectSlug,
+          messageCount: payload.messages.length,
+          toolCount: payload.tools.length,
+          hasAgentSource: Boolean(payload.agentSource),
+        });
 
         return await this.withAgentSourceContext(
           ctx,
@@ -174,6 +186,12 @@ export class AgentStreamHandler extends BaseHandler {
 
             const agent = this.deps.getAgent(payload.agentId);
             if (!agent) {
+              logger.warn("Internal agent stream request referenced unknown agent", {
+                runId: payload.runId,
+                agentId: payload.agentId,
+                projectId: ctx.projectId,
+                projectSlug: ctx.projectSlug,
+              });
               return this.respond(builder.json({ error: "Agent not found" }, 404));
             }
 
@@ -182,6 +200,13 @@ export class AgentStreamHandler extends BaseHandler {
               agent as Agent,
               this.deps,
             );
+            logger.info("Internal agent stream response created", {
+              runId: payload.runId,
+              threadId: payload.threadId,
+              agentId: payload.agentId,
+              projectId: ctx.projectId,
+              projectSlug: ctx.projectSlug,
+            });
             const runtimeOwnerInvokeUrl = await this.deps.resolveRuntimeOwnerInvokeUrl?.(req) ??
               null;
             const responseWithOwner = runtimeOwnerInvokeUrl
@@ -224,6 +249,11 @@ export class AgentStreamHandler extends BaseHandler {
           projectId: ctx.projectId,
           projectSlug: ctx.projectSlug,
         });
+        logger.error("Internal agent stream handler failed", {
+          projectId: ctx.projectId,
+          projectSlug: ctx.projectSlug,
+          error: error instanceof Error ? error.message : String(error),
+        });
         return this.respond(builder.json({ error: "Internal agent stream failed" }, 500));
       }
     });

package/src/src/tool/types.ts

@@ -5,6 +5,8 @@
 import type { z } from "zod";
 import type { JsonSchema } from "./schema/json-schema.js";
 import type { BlobStorage } from "../workflow/blob/types.js";
+// type-only import — no runtime circular dependency (tool ↔ mcp)
+import type { ToolAnnotations } from "../mcp/types.js";
 
 /**
  * Tool configuration options
@@ -41,6 +43,11 @@ export interface ToolConfig<TInput = any, TOutput = any> {
 
     /** 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/src/src/utils/version-constant.ts

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