feat: Add tool annotations to scaffolding templates

[triepod-ai]

Summary

Adds MCP tool annotations support to all framework templates (Go, TypeScript, Python, Java) to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

Go (modelcontextprotocol/go-sdk)

• Bump SDK from v0.2.0 to v1.2.0 for annotation support
• Add Annotations field to MCPTool struct
• Add annotations to echo.go.tmpl and tool.go.tmpl

TypeScript (@modelcontextprotocol/sdk)

• Import ToolAnnotations type
• Add annotations field to Tool interface
• Add annotations to echo.ts.tmpl and tool.ts.tmpl
• Include annotations in tools/list response

Python (FastMCP)

• Import ToolAnnotations from mcp.types
• Add annotations parameter to @mcp.tool() decorator
• Add annotations to echo.py.tmpl and tool.py.tmpl

Java (io.modelcontextprotocol.sdk)

• Add getAnnotations() method to Tool interface
• Add annotations to Echo.java.tmpl and ToolTemplate.java.tmpl
• Update MCPServer to include annotations in both stdio and HTTP responses

Why This Matters

Tool annotations are part of the MCP specification that enable:

• Clients to auto-approve safe (read-only) operations
• Better user prompts for destructive operations
• Improved tool discovery and filtering
• Semantic metadata that helps LLMs understand tool behavior

This change benefits all users who scaffold new MCP servers with kmcp, ensuring their generated projects include proper tool annotations from the start.

Testing

• make lint passes
• make test passes
• Changes are limited to template files

Before/After

Before (generated tool):

const echo = {
  name: 'echo',
  description: 'Echo back the provided message',
  inputSchema: echoSchema,
  handler: async (params) => { ... }
};

After (generated tool):

const echo = {
  name: 'echo',
  description: 'Echo back the provided message',
  inputSchema: echoSchema,
  annotations: {
    title: 'Echo Message',
    readOnlyHint: true,
  },
  handler: async (params) => { ... }
};

References

• MCP Tool Annotations Spec