MCP Tool Behavior 宣言

コーディング入門

2025-06-18仕様に基づきツール動作アノテーションを追加し、クライアントが確認ダイアログや自動承認を適切に処理できるようにします。

トリガー/mcp-tool-attr

使用頻度per tool

MCP Server Authorなら？ Run /mcp-tool-attr to annotate all tools for safer client behavior

Security Engineerなら？ Ensure destructive tools are properly flagged for UI gating

MCPTool Behavior安全性UX

動作フロー

/mcp-tool-attr [server-dir] run

↓

Phase 1: scan and classify tools

tool-scan

List all registered tools

classify

Auto-classify read/write/destructive

annotate

Add behavior attributes

↓

Generate behavior summary table

↓

✓ All tools annotated with behavior attributes

スキルコード

# MCP Tool Behavior Declarator
## Trigger: /mcp-tool-attr [server-directory]

When invoked:

1. Scan tools and add behavior annotations:
```typescript
server.tool("list-files", {
  description: "List files in a directory",
  annotations: {
    readOnlyHint: true,        // Does not modify state
    destructiveHint: false,    // Cannot destroy data
    idempotentHint: true,      // Safe to retry
    openWorldHint: false,      // No external side effects
  },
  inputSchema: { /* ... */ }
}, handler);

server.tool("delete-record", {
  description: "Permanently delete a database record",
  annotations: {
    readOnlyHint: false,
    destructiveHint: true,     // Irreversible action
    idempotentHint: true,      // Deleting twice = same result
    openWorldHint: false,
  },
  inputSchema: { /* ... */ }
}, handler);

server.tool("send-email", {
  description: "Send email to a recipient",
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,     // Sending twice = two emails
    openWorldHint: true,       // External side effect (email sent)
  },
  inputSchema: { /* ... */ }
}, handler);
```

2. Behavior classification guide:
| Attribute | true | false |
|-----------|------|-------|
| readOnlyHint | Queries, listings, searches | Create, update, delete |
| destructiveHint | Delete, drop, purge, overwrite | Create, read, append |
| idempotentHint | GET-like, upsert, delete | POST-like, send, increment |
| openWorldHint | Email, API call, webhook | Local DB, file system |

3. Client behavior expectations:
 - readOnly: may auto-approve without user confirmation
 - destructive: should show confirmation dialog
 - idempotent: safe to retry on network errors
 - openWorld: warn about external side effects

コピーしてCLAUDE.mdに貼り付ければ、すぐに使えます。