feat: Add tool annotations for improved LLM tool understanding

Add readOnlyHint and destructiveHint annotations to all tools
to help LLMs better understand tool behavior and make safer decisions.

Changes:
- Added ToolAnnotations import from MCP SDK types
- Modified BaseTool class to support annotations property
- Added destructiveHint: true to CreateUiTool (creates/modifies files)
- Added readOnlyHint: true to FetchUiTool (read-only API call)
- Added destructiveHint: true to LogoSearchTool (writes to filesystem)
- Added destructiveHint: true to RefineUiTool (modifies components)
- Added openWorldHint: true to all tools (interact with external APIs)
- Added title annotations for human-readable display
- Bump MCP SDK from ^1.8.0 to ^1.25.1 for annotation support

This improves tool safety metadata for MCP clients.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

package-lock.json

@@ -38,7 +38,7 @@
   "author": "serafim@21st.dev",
   "license": "ISC",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.0",
     "cors": "^2.8.5",

package.json

@@ -1,6 +1,6 @@
 import open from "open";
 import { z } from "zod";
-import { BaseTool } from "../utils/base-tool.js";
+import { BaseTool, ToolAnnotations } from "../utils/base-tool.js";
 import { CallbackServer } from "../utils/callback-server.js";
 import { config } from "../utils/config.js";
 import { git } from "../utils/git-operations.js";
@@ -19,6 +19,11 @@ interface CreateUiResponse {
 export class CreateUiTool extends BaseTool {
   name = UI_TOOL_NAME;
   description = UI_TOOL_DESCRIPTION;
+  annotations: ToolAnnotations = {
+    title: "Create UI Component",
+    destructiveHint: true,
+    openWorldHint: true,
+  };
 
   schema = z.object({
     message: z.string().describe("Full users message"),

src/tools/create-ui.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { BaseTool } from "../utils/base-tool.js";
+import { BaseTool, ToolAnnotations } from "../utils/base-tool.js";
 import { twentyFirstClient } from "../utils/http-client.js";
 
 const FETCH_UI_TOOL_NAME = "21st_magic_component_inspiration";
@@ -15,6 +15,11 @@ interface FetchUiResponse {
 export class FetchUiTool extends BaseTool {
   name = FETCH_UI_TOOL_NAME;
   description = FETCH_UI_TOOL_DESCRIPTION;
+  annotations: ToolAnnotations = {
+    title: "Fetch UI Inspiration",
+    readOnlyHint: true,
+    openWorldHint: true,
+  };
 
   schema = z.object({
     message: z.string().describe("Full users message"),

src/tools/fetch-ui.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { promises as fs } from "fs";
-import { BaseTool } from "../utils/base-tool.js";
+import { BaseTool, ToolAnnotations } from "../utils/base-tool.js";
 
 // Types for SVGL API responses
 interface ThemeOptions {
@@ -49,6 +49,11 @@ Each result includes:
 export class LogoSearchTool extends BaseTool {
   name = LOGO_TOOL_NAME;
   description = LOGO_TOOL_DESCRIPTION;
+  annotations: ToolAnnotations = {
+    title: "Search Logos",
+    destructiveHint: true,
+    openWorldHint: true,
+  };
 
   schema = z.object({
     queries: z

src/tools/logo-search.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { BaseTool } from "../utils/base-tool.js";
+import { BaseTool, ToolAnnotations } from "../utils/base-tool.js";
 import { twentyFirstClient } from "../utils/http-client.js";
 import { getContentOfFile } from "../utils/get-content-of-file.js";
 
@@ -17,6 +17,11 @@ interface RefineUiResponse {
 export class RefineUiTool extends BaseTool {
   name = REFINE_UI_TOOL_NAME;
   description = REFINE_UI_TOOL_DESCRIPTION;
+  annotations: ToolAnnotations = {
+    title: "Refine UI Component",
+    destructiveHint: true,
+    openWorldHint: true,
+  };
 
   schema = z.object({
     userMessage: z.string().describe("Full user's message about UI refinement"),

src/tools/refine-ui.ts

@@ -1,16 +1,21 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
+export { ToolAnnotations };
+
 export abstract class BaseTool {
   abstract name: string;
   abstract description: string;
   abstract schema: z.ZodObject<any>;
+  abstract annotations: ToolAnnotations;
 
   register(server: McpServer) {
     server.tool(
       this.name,
       this.description,
       this.schema.shape,
+      this.annotations,
       this.execute.bind(this)
     );
   }