feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all 10 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Added readOnlyHint: true to 9 read-only tools:

  • get_component - fetches component source code
  • get_component_demo - fetches demo code
  • list_components - lists available components
  • get_component_metadata - fetches component metadata
  • get_directory_structure - fetches repository structure
  • get_block - fetches block source code
  • list_blocks - lists available blocks
  • list_themes - lists TweakCN themes
  • get_theme - fetches theme details

• Added destructiveHint: true to apply_theme (writes files to filesystem)

• Added title annotations for human-readable display

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• MCP clients can make better decisions about when to use tools and in what order
• Enables safer tool execution by distinguishing read-only from destructive operations
• Clients like Claude Code can auto-approve read-only tools without user confirmation

Testing

• Server builds successfully (npm run build)
• TypeScript compilation passes (no errors)
• Live verification: Started server and confirmed tools/list returns annotations for all 10 tools
• Annotation values correctly match tool behavior (read-only vs destructive)

Verification Output

Total tools: 10

Tool Name                      Title                     ReadOnly   Destructive
---------------------------------------------------------------------------
get_component                  Get Component             True       N/A       
get_component_demo             Get Component Demo        True       N/A       
list_components                List Components           True       N/A       
get_component_metadata         Get Component Metadata    True       N/A       
get_directory_structure        Get Directory Structure   True       N/A       
get_block                      Get Block                 True       N/A       
list_blocks                    List Blocks               True       N/A       
apply_theme                    Apply Theme               N/A        True      
list_themes                    List Themes               True       N/A       
get_theme                      Get Theme                 True       N/A       

Before/After

Before:

{
  name: 'get_component',
  description: 'Get the source code for a specific shadcn/ui v4 component',
  inputSchema: { ... },
}

After:

{
  name: 'get_component',
  description: 'Get the source code for a specific shadcn/ui v4 component',
  inputSchema: { ... },
  annotations: {
    title: "Get Component",
    readOnlyHint: true,
  },
}

🤖 Generated with Claude Code

[github-actions]

Thanks for the pr,it's now under review

[Jpisnice]

Hey @triepod-ai thanks for the contribution.ill have a look at the changes and get back to you if i have any doubts.really appreciate the contribution

[Jpisnice]

Seems good