veryfront 0.1.141 → 0.1.142

package/src/cli/mcp/tools.ts

@@ -35,18 +35,24 @@ export function setServerStartTime(time: number): void {
 
 const getErrorsInput = z.object({
   type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe(
-    "Filter by error type",
+    "Filter by error type. Example: 'compile'. Omit to return all types.",
+  ),
+  file: z.string().optional().describe(
+    "Filter by file path. Example: 'app/page.tsx'. Omit to return errors from all files.",
+  ),
+  limit: z.number().optional().default(50).describe(
+    "Maximum number of errors to return. Defaults to 50.",
   ),
-  file: z.string().optional().describe("Filter by file path"),
-  limit: z.number().optional().default(50).describe("Maximum number of errors to return"),
 });
 
 type GetErrorsInput = z.infer<typeof getErrorsInput>;
 
 export const vfGetErrors: MCPTool<GetErrorsInput, DevError[]> = {
   name: "vf_get_errors",
+  title: "Get Errors",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get compilation, runtime, and build errors from the dev server. Use this to debug issues with your code.",
+    "Use this when you need to check for compilation, runtime, bundle, HMR, or module errors in the dev server. Returns error details including file path, line number, and message. Do not use for server logs — use vf_get_logs instead.",
   inputSchema: getErrorsInput,
   execute: async (input) => {
     const errors = getErrorCollector().getAll({
@@ -60,21 +66,31 @@ export const vfGetErrors: MCPTool<GetErrorsInput, DevError[]> = {
 };
 
 const getLogsInput = z.object({
-  level: z.enum(["debug", "info", "warn", "error"]).optional().describe("Filter by log level"),
+  level: z.enum(["debug", "info", "warn", "error"]).optional().describe(
+    "Filter by log level. Example: 'error'. Omit to return all levels.",
+  ),
   source: z.string().optional().describe(
-    "Filter by log source (e.g., 'server', 'hmr', 'transform')",
+    "Filter by log source. Example: 'server', 'hmr', 'transform'. Omit to return all sources.",
+  ),
+  pattern: z.string().optional().describe(
+    "Filter by pattern (case-insensitive substring match). Example: 'timeout'.",
+  ),
+  limit: z.number().optional().default(100).describe(
+    "Maximum number of log entries to return. Defaults to 100.",
+  ),
+  since: z.number().optional().describe(
+    "Only return logs after this Unix timestamp in milliseconds.",
   ),
-  pattern: z.string().optional().describe("Filter by pattern (case-insensitive substring match)"),
-  limit: z.number().optional().default(100).describe("Maximum number of log entries to return"),
-  since: z.number().optional().describe("Only return logs after this timestamp"),
 });
 
 type GetLogsInput = z.infer<typeof getLogsInput>;
 
 export const vfGetLogs: MCPTool<GetLogsInput, LogEntry[]> = {
   name: "vf_get_logs",
+  title: "Get Logs",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   description:
-    "Get recent server logs. Use this to understand what the server is doing and debug runtime issues.",
+    "Use this when you need to inspect server logs to understand runtime behavior or debug request handling. Returns log entries with timestamp, level, source, and message. Do not use for build/compile errors — use vf_get_errors instead.",
   inputSchema: getLogsInput,
   execute: async (input) => {
     return getLogBuffer().query({
@@ -89,7 +105,7 @@ export const vfGetLogs: MCPTool<GetLogsInput, LogEntry[]> = {
 
 const clearCacheInput = z.object({
   type: z.enum(["all", "modules", "mdx"]).optional().default("all").describe(
-    "Type of cache to clear",
+    "Type of cache to clear. Example: 'modules'. Defaults to 'all'.",
   ),
 });
 
@@ -102,8 +118,15 @@ interface ClearCacheOutput {
 
 export const vfClearCache: MCPTool<ClearCacheInput, ClearCacheOutput> = {
   name: "vf_clear_cache",
+  title: "Clear Cache",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   description:
-    "Clear module and build caches. Use this when changes aren't being reflected or to force a rebuild.",
+    "Use this when the dev server shows stale modules or MDX content. Returns the list of cleared cache directories. Do not use to fix code errors — those require code changes.",
   inputSchema: clearCacheInput,
   execute: async (input) => {
     const fs = createFileSystem();
@@ -143,7 +166,10 @@ export function createVfGetStatus(
 ): MCPTool<GetStatusInput, ServerStatus> {
   return {
     name: "vf_get_status",
-    description: "Get the current status of the dev server including error counts and uptime.",
+    title: "Server Status",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description:
+      "Use this when you need a quick summary of the dev server's uptime, error counts, and warning counts. Note: always reports running=true when the MCP server is reachable. Do not use for detailed error info — use vf_get_errors instead.",
     inputSchema: getStatusInput,
     execute: async () => {
       const errors = getErrorCollector();
@@ -167,9 +193,11 @@ export function createVfGetStatus(
 export const vfGetStatus = createVfGetStatus();
 
 const clearErrorsInput = z.object({
-  file: z.string().optional().describe("Clear errors for a specific file only"),
+  file: z.string().optional().describe(
+    "Clear errors for a specific file only. Example: 'app/page.tsx'. Omit to clear all files.",
+  ),
   type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe(
-    "Clear errors of a specific type only",
+    "Clear errors of a specific type only. Example: 'compile'. Omit to clear all types.",
   ),
 });
 
@@ -181,7 +209,15 @@ interface ClearErrorsOutput {
 
 export const vfClearErrors: MCPTool<ClearErrorsInput, ClearErrorsOutput> = {
   name: "vf_clear_errors",
-  description: "Clear errors from the error collector. Useful after fixing issues.",
+  title: "Clear Errors",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  description:
+    "Use this when you need to clear accumulated errors from the error collector, optionally filtering by file or type. Returns the number of cleared errors. Do not use for viewing errors — use vf_get_errors instead.",
   inputSchema: clearErrorsInput,
   execute: async (input) => {
     const collector = getErrorCollector();

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.141",
+  "version": "0.1.142",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/agent/runtime/index.ts

@@ -406,7 +406,7 @@ export class AgentRuntime {
           logger.error("Agent stream error", { error });
           sendSSE(controller, encoder, {
             type: "error",
-            error: "An internal error occurred",
+            error: error instanceof Error ? error.message : String(error),
           });
           closeSSEStream(controller);
         } finally {

package/src/src/agent/runtime/tool-helpers.ts

@@ -11,6 +11,7 @@ import { executeTool, toolRegistry } from "../../tool/index.js";
 import { toolToProviderDefinition } from "../../tool/registry.js";
 import { SKILL_TOOL_IDS } from "../../skill/types.js";
 import { serverLogger } from "../../utils/index.js";
+import { createError, toError } from "../../errors/veryfront-error.js";
 import {
   executeRemoteIntegrationTool,
   isRemoteIntegrationTool,
@@ -71,6 +72,52 @@ export function isDynamicTool(name: string): boolean {
 // deno-lint-ignore no-explicit-any -- generic erasure: accepts Tool with any input/output types
 export type ToolConfigEntry = Tool<any, any> | boolean;
 
+function formatAvailableToolNames(names: Iterable<string>): string {
+  const sorted = [...new Set(names)].sort();
+  return sorted.length > 0 ? sorted.join(", ") : "(none)";
+}
+
+function throwUnknownConfiguredToolsError(
+  unknownToolNames: string[],
+  availableLocalToolNames: Iterable<string>,
+  availableRemoteToolNames: Iterable<string>,
+): never {
+  const unknownList = unknownToolNames.sort().join(", ");
+  const availableNames = formatAvailableToolNames([
+    ...availableLocalToolNames,
+    ...availableRemoteToolNames,
+  ]);
+
+  throw toError(
+    createError({
+      type: "agent",
+      message:
+        `Unknown tool reference${unknownToolNames.length === 1 ? "" : "s"}: ${unknownList}. ` +
+        `Tool names must exactly match tool({ id: "..." }). Available tools: ${availableNames}`,
+    }),
+  );
+}
+
+async function getRemoteToolDefinitions(options?: {
+  includeIntegrationTools?: boolean;
+  allowedRemoteToolNames?: string[];
+}): Promise<ToolDefinition[]> {
+  if (options?.includeIntegrationTools === false) {
+    return [];
+  }
+
+  try {
+    const { getRemoteIntegrationToolDefinitions } = await import(
+      "../../integrations/remote-tools.js"
+    );
+    return (await getRemoteIntegrationToolDefinitions()).filter((def) =>
+      !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
+    );
+  } catch {
+    return [];
+  }
+}
+
 export function resolveConfiguredTool(
   toolsConfig: true | Record<string, ToolConfigEntry> | undefined,
   toolName: string,
@@ -179,32 +226,35 @@ export async function getAvailableTools(
     });
 
     // Append remote integration tools (per-request, project-scoped)
-    if (options?.includeIntegrationTools !== false) {
-      try {
-        const { getRemoteIntegrationToolDefinitions } = await import(
-          "../../integrations/remote-tools.js"
-        );
-        const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) =>
-          !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
-        );
-        for (const def of remoteDefs) {
-          logToolDefinition(def.name, def);
-        }
-        tools.push(...remoteDefs);
-      } catch {
-        // Integration tools unavailable — non-fatal
-      }
+    const remoteDefs = await getRemoteToolDefinitions(options);
+    for (const def of remoteDefs) {
+      logToolDefinition(def.name, def);
     }
+    tools.push(...remoteDefs);
 
     return tools;
   }
 
   const tools: ToolDefinition[] = [];
+  const remoteDefs = await getRemoteToolDefinitions(options);
+  const remoteToolNames = new Set(remoteDefs.map((def) => def.name));
+  const explicitlyRequestedRemoteToolNames = new Set<string>();
+  const unresolvedConfiguredToolNames: string[] = [];
 
   for (const [name, entry] of Object.entries(toolsConfig)) {
     if (entry === true) {
       const tool = toolRegistry.get(name);
-      if (tool) addToolDefinition(tools, name, tool);
+      if (tool) {
+        addToolDefinition(tools, name, tool);
+        continue;
+      }
+
+      if (remoteToolNames.has(name)) {
+        explicitlyRequestedRemoteToolNames.add(name);
+        continue;
+      }
+
+      unresolvedConfiguredToolNames.push(name);
       continue;
     }
 
@@ -213,28 +263,28 @@ export async function getAvailableTools(
     }
   }
 
-  // Also append remote integration tools for explicit-object configs.
-  // The internal streaming path converts `tools: true` to an explicit object
-  // from the local registry, so remote tools would be missed without this.
-  if (options?.includeIntegrationTools !== false) {
-    try {
-      const { getRemoteIntegrationToolDefinitions } = await import(
-        "../../integrations/remote-tools.js"
-      );
-      const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) =>
-        !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name)
-      );
-      for (const def of remoteDefs) {
-        // Skip if already present (e.g., explicitly configured by name)
-        if (!tools.some((t) => t.name === def.name)) {
-          logToolDefinition(def.name, def);
-          tools.push(def);
-        }
-      }
-    } catch {
-      // Integration tools unavailable — non-fatal
+  // Explicit-object configs should only expose remote definitions that were
+  // explicitly requested, except for the internal runtime path that expands
+  // `tools: true` into an explicit local-tool map and passes the remote allowlist.
+  const remoteDefsToAppend = explicitlyRequestedRemoteToolNames.size > 0
+    ? remoteDefs.filter((def) => explicitlyRequestedRemoteToolNames.has(def.name))
+    : remoteDefs.filter((def) => options?.allowedRemoteToolNames?.includes(def.name));
+
+  for (const def of remoteDefsToAppend) {
+    // Skip if already present (e.g., explicitly configured by name)
+    if (!tools.some((t) => t.name === def.name)) {
+      logToolDefinition(def.name, def);
+      tools.push(def);
     }
   }
 
+  if (unresolvedConfiguredToolNames.length > 0) {
+    throwUnknownConfiguredToolsError(
+      unresolvedConfiguredToolNames,
+      toolRegistry.getAll().keys(),
+      remoteToolNames,
+    );
+  }
+
   return tools;
 }

package/src/src/issues/mcp.ts

@@ -53,8 +53,11 @@ type IssuesCreateInput = z.infer<typeof issuesCreateInput>;
 
 const issuesCreate: MCPTool<IssuesCreateInput, Issue> = {
   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);
@@ -81,7 +84,10 @@ type IssuesGetInput = z.infer<typeof issuesGetInput>;
 
 const issuesGet: MCPTool<IssuesGetInput, Issue | null> = {
   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);
@@ -107,8 +113,16 @@ type IssuesUpdateInput = z.infer<typeof issuesUpdateInput>;
 
 const issuesUpdate: MCPTool<IssuesUpdateInput, Issue | null> = {
   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);
@@ -153,8 +167,10 @@ interface IssuesListOutput {
 
 const issuesList: MCPTool<IssuesListInput, IssuesListOutput> = {
   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);
@@ -183,7 +199,15 @@ type IssuesCloseInput = z.infer<typeof issuesCloseInput>;
 
 const issuesClose: MCPTool<IssuesCloseInput, Issue | null> = {
   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);
@@ -207,8 +231,17 @@ interface IssuesDeleteOutput {
 
 const issuesDelete: MCPTool<IssuesDeleteInput, IssuesDeleteOutput> = {
   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/src/src/mcp/index.ts

@@ -24,7 +24,13 @@
 import "../../_dnt.polyfills.js";
 
 
-export type { MCPServerConfig, MCPStats, MCPTool } from "./types.js";
+export type {
+  MCPServerConfig,
+  MCPStats,
+  MCPTool,
+  ToolAnnotations,
+  ToolListEntry,
+} from "./types.js";
 
 export {
   clearMCPRegistry,

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 {