@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/plugin-dev/skills/mcp-integration/references/tool-usage.md

@@ -0,0 +1,623 @@
+# Using MCP Tools in Commands and Agents
+
+Complete guide to using MCP tools effectively in Claude Code plugin commands and agents.
+
+## Overview
+
+Once an MCP server is configured, its tools become available with the prefix `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`. Use these tools in commands and agents just like built-in Claude Code tools.
+
+## Tool Naming Convention
+
+### Format
+
+```
+mcp__plugin_<plugin-name>_<server-name>__<tool-name>
+```
+
+### Examples
+
+**Asana plugin with asana server:**
+
+- `mcp__plugin_asana_asana__asana_create_task`
+- `mcp__plugin_asana_asana__asana_search_tasks`
+- `mcp__plugin_asana_asana__asana_get_project`
+
+**Custom plugin with database server:**
+
+- `mcp__plugin_myplug_database__query`
+- `mcp__plugin_myplug_database__execute`
+- `mcp__plugin_myplug_database__list_tables`
+
+### Discovering Tool Names
+
+**Use `/mcp` command:**
+
+```bash
+/mcp
+```
+
+This shows:
+
+- All available MCP servers
+- Tools provided by each server
+- Tool schemas and descriptions
+- Full tool names for use in configuration
+
+## Using Tools in Commands
+
+### Pre-Allowing Tools
+
+Specify MCP tools in command frontmatter:
+
+```markdown
+---
+description: Create a new Asana task
+allowed-tools: ["mcp__plugin_asana_asana__asana_create_task"]
+---
+
+# Create Task Command
+
+To create a task:
+
+1. Gather task details from user
+2. Use mcp__plugin_asana_asana__asana_create_task with the details
+3. Confirm creation to user
+```
+
+### Multiple Tools
+
+```markdown
+---
+allowed-tools:
+  [
+    "mcp__plugin_asana_asana__asana_create_task",
+    "mcp__plugin_asana_asana__asana_search_tasks",
+    "mcp__plugin_asana_asana__asana_get_project",
+  ]
+---
+```
+
+### Wildcard (Use Sparingly)
+
+```markdown
+---
+allowed-tools: ["mcp__plugin_asana_asana__*"]
+---
+```
+
+**Caution:** Only use wildcards if the command truly needs access to all tools from a server.
+
+### Tool Usage in Command Instructions
+
+**Example command:**
+
+```markdown
+---
+description: Search and create Asana tasks
+allowed-tools:
+  [
+    "mcp__plugin_asana_asana__asana_search_tasks",
+    "mcp__plugin_asana_asana__asana_create_task",
+  ]
+---
+
+# Asana Task Management
+
+## Searching Tasks
+
+To search for tasks:
+
+1. Use mcp__plugin_asana_asana__asana_search_tasks
+2. Provide search filters (assignee, project, etc.)
+3. Display results to user
+
+## Creating Tasks
+
+To create a task:
+
+1. Gather task details:
+   - Title (required)
+   - Description
+   - Project
+   - Assignee
+   - Due date
+2. Use mcp__plugin_asana_asana__asana_create_task
+3. Show confirmation with task link
+```
+
+## Using Tools in Agents
+
+### Agent Configuration
+
+Agents can use MCP tools autonomously without pre-allowing them:
+
+```markdown
+---
+name: asana-status-updater
+description: This agent should be used when the user asks to "update Asana status", "generate project report", or "sync Asana tasks"
+model: inherit
+color: blue
+---
+
+## Role
+
+Autonomous agent for generating Asana project status reports.
+
+## Process
+
+1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks
+2. **Analyze progress**: Calculate completion rates and identify blockers
+3. **Generate report**: Create formatted status update
+4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report
+
+## Available Tools
+
+The agent has access to all Asana MCP tools without pre-approval.
+```
+
+### Agent Tool Access
+
+Agents have broader tool access than commands:
+
+- Can use any tool Claude determines is necessary
+- Don't need pre-allowed lists
+- Should document which tools they typically use
+
+## Tool Call Patterns
+
+### Pattern 1: Simple Tool Call
+
+Single tool call with validation:
+
+```markdown
+Steps:
+
+1. Validate user provided required fields
+2. Call mcp__plugin_api_server__create_item with validated data
+3. Check for errors
+4. Display confirmation
+```
+
+### Pattern 2: Sequential Tools
+
+Chain multiple tool calls:
+
+```markdown
+Steps:
+
+1. Search for existing items: mcp__plugin_api_server__search
+2. If not found, create new: mcp__plugin_api_server__create
+3. Add metadata: mcp__plugin_api_server__update_metadata
+4. Return final item ID
+```
+
+### Pattern 3: Batch Operations
+
+Multiple calls with same tool:
+
+```markdown
+Steps:
+
+1. Get list of items to process
+2. For each item:
+   - Call mcp__plugin_api_server__update_item
+   - Track success/failure
+3. Report results summary
+```
+
+### Pattern 4: Error Handling
+
+Graceful error handling:
+
+```markdown
+Steps:
+
+1. Try to call mcp__plugin_api_server__get_data
+2. If error (rate limit, network, etc.):
+   - Wait and retry (max 3 attempts)
+   - If still failing, inform user
+   - Suggest checking configuration
+3. On success, process data
+```
+
+## Tool Parameters
+
+### Understanding Tool Schemas
+
+Each MCP tool has a schema defining its parameters. View with `/mcp`.
+
+**Example schema:**
+
+```json
+{
+  "name": "asana_create_task",
+  "description": "Create a new Asana task",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "Task title"
+      },
+      "notes": {
+        "type": "string",
+        "description": "Task description"
+      },
+      "workspace": {
+        "type": "string",
+        "description": "Workspace GID"
+      }
+    },
+    "required": ["name", "workspace"]
+  }
+}
+```
+
+### Calling Tools with Parameters
+
+Claude automatically structures tool calls based on schema:
+
+```typescript
+// Claude generates this internally
+{
+  toolName: "mcp__plugin_asana_asana__asana_create_task",
+  input: {
+    name: "Review PR #123",
+    notes: "Code review for new feature",
+    workspace: "12345",
+    assignee: "67890",
+    due_on: "2025-01-15"
+  }
+}
+```
+
+### Parameter Validation
+
+**In commands, validate before calling:**
+
+```markdown
+Steps:
+
+1. Check required parameters:
+   - Title is not empty
+   - Workspace ID is provided
+   - Due date is valid format (YYYY-MM-DD)
+2. If validation fails, ask user to provide missing data
+3. If validation passes, call MCP tool
+4. Handle tool errors gracefully
+```
+
+## Response Handling
+
+### Success Responses
+
+```markdown
+Steps:
+
+1. Call MCP tool
+2. On success:
+   - Extract relevant data from response
+   - Format for user display
+   - Provide confirmation message
+   - Include relevant links or IDs
+```
+
+### Error Responses
+
+```markdown
+Steps:
+
+1. Call MCP tool
+2. On error:
+   - Check error type (auth, rate limit, validation, etc.)
+   - Provide helpful error message
+   - Suggest remediation steps
+   - Don't expose internal error details to user
+```
+
+### Partial Success
+
+```markdown
+Steps:
+
+1. Batch operation with multiple MCP calls
+2. Track successes and failures separately
+3. Report summary:
+   - "Successfully processed 8 of 10 items"
+   - "Failed items: [item1, item2] due to [reason]"
+   - Suggest retry or manual intervention
+```
+
+## Performance Optimization
+
+### Batching Requests
+
+#### Good: Single query with filters
+
+```markdown
+Steps:
+
+1. Call mcp__plugin_api_server__search with filters:
+   - project_id: "123"
+   - status: "active"
+   - limit: 100
+2. Process all results
+```
+
+#### Avoid: Many individual queries
+
+```markdown
+Steps:
+
+1. For each item ID:
+   - Call mcp__plugin_api_server__get_item
+   - Process item
+```
+
+### Caching Results
+
+```markdown
+Steps:
+
+1. Call expensive MCP operation: mcp__plugin_api_server__analyze
+2. Store results in variable for reuse
+3. Use cached results for subsequent operations
+4. Only re-fetch if data changes
+```
+
+### Parallel Tool Calls
+
+When tools don't depend on each other, call in parallel:
+
+```markdown
+Steps:
+
+1. Make parallel calls (Claude handles this automatically):
+   - mcp__plugin_api_server__get_project
+   - mcp__plugin_api_server__get_users
+   - mcp__plugin_api_server__get_tags
+2. Wait for all to complete
+3. Combine results
+```
+
+## Integration Best Practices
+
+### User Experience
+
+**Provide feedback:**
+
+```markdown
+Steps:
+
+1. Inform user: "Searching Asana tasks..."
+2. Call mcp__plugin_asana_asana__asana_search_tasks
+3. Show progress: "Found 15 tasks, analyzing..."
+4. Present results
+```
+
+**Handle long operations:**
+
+```markdown
+Steps:
+
+1. Warn user: "This may take a minute..."
+2. Break into smaller steps with updates
+3. Show incremental progress
+4. Final summary when complete
+```
+
+### Error Messages
+
+**Good error messages:**
+
+```
+❌ "Could not create task. Please check:
+   1. You're logged into Asana
+   2. You have access to workspace 'Engineering'
+   3. The project 'Q1 Goals' exists"
+```
+
+**Poor error messages:**
+
+```
+❌ "Error: MCP tool returned 403"
+```
+
+### Documentation
+
+**Document MCP tool usage in command:**
+
+```markdown
+## MCP Tools Used
+
+This command uses the following Asana MCP tools:
+
+- **asana_search_tasks**: Search for tasks matching criteria
+- **asana_create_task**: Create new task with details
+- **asana_update_task**: Update existing task properties
+
+Ensure authentication to Asana before running this command.
+```
+
+## Testing Tool Usage
+
+### Local Testing
+
+1. **Configure MCP server** in `.mcp.json`
+2. **Install plugin locally** in `.claude-plugin/`
+3. **Verify tools available** with `/mcp`
+4. **Test command** that uses tools
+5. **Check debug output**: `claude --debug`
+
+### Test Scenarios
+
+**Test successful calls:**
+
+```markdown
+Steps:
+
+1. Create test data in external service
+2. Run command that queries this data
+3. Verify correct results returned
+```
+
+**Test error cases:**
+
+```markdown
+Steps:
+
+1. Test with missing authentication
+2. Test with invalid parameters
+3. Test with non-existent resources
+4. Verify graceful error handling
+```
+
+**Test edge cases:**
+
+```markdown
+Steps:
+
+1. Test with empty results
+2. Test with maximum results
+3. Test with special characters
+4. Test with concurrent access
+```
+
+## Common Patterns
+
+### Pattern: CRUD Operations
+
+```markdown
+---
+allowed-tools:
+  [
+    "mcp__plugin_api_server__create_item",
+    "mcp__plugin_api_server__read_item",
+    "mcp__plugin_api_server__update_item",
+    "mcp__plugin_api_server__delete_item",
+  ]
+---
+
+# Item Management
+
+## Create
+
+Use create_item with required fields...
+
+## Read
+
+Use read_item with item ID...
+
+## Update
+
+Use update_item with item ID and changes...
+
+## Delete
+
+Use delete_item with item ID (ask for confirmation first)...
+```
+
+### Pattern: Search and Process
+
+```markdown
+Steps:
+
+1. **Search**: mcp__plugin_api_server__search with filters
+2. **Filter**: Apply additional local filtering if needed
+3. **Transform**: Process each result
+4. **Present**: Format and display to user
+```
+
+### Pattern: Multi-Step Workflow
+
+```markdown
+Steps:
+
+1. **Setup**: Gather all required information
+2. **Validate**: Check data completeness
+3. **Execute**: Chain of MCP tool calls:
+   - Create parent resource
+   - Create child resources
+   - Link resources together
+   - Add metadata
+4. **Verify**: Confirm all steps succeeded
+5. **Report**: Provide summary to user
+```
+
+## Troubleshooting
+
+### Tools Not Available
+
+**Check:**
+
+- MCP server configured correctly
+- Server connected (check `/mcp`)
+- Tool names match exactly (case-sensitive)
+- Restart Claude Code after config changes
+
+### Tool Calls Failing
+
+**Check:**
+
+- Authentication is valid
+- Parameters match tool schema
+- Required parameters provided
+- Check `claude --debug` logs
+
+### Performance Issues
+
+**Check:**
+
+- Batching queries instead of individual calls
+- Caching results when appropriate
+- Not making unnecessary tool calls
+- Parallel calls when possible
+
+## Conclusion
+
+Effective MCP tool usage requires:
+
+1. **Understanding tool schemas** via `/mcp`
+2. **Pre-allowing tools** in commands appropriately
+3. **Handling errors gracefully**
+4. **Optimizing performance** with batching and caching
+5. **Providing good UX** with feedback and clear errors
+6. **Testing thoroughly** before deployment
+
+Follow these patterns for robust MCP tool integration in your plugin commands and agents.
+
+## MCP Prompts as Commands
+
+Beyond tools and resources, MCP servers can expose **prompts** — pre-defined instruction templates that appear as slash commands in Claude Code.
+
+### How Prompts Work
+
+When an MCP server declares prompts via the MCP protocol, Claude Code automatically registers them as slash commands:
+
+- **Format:** `/mcp__servername__promptname`
+- **Discovery:** Prompts appear in the `/` autocomplete menu alongside regular commands
+- **Arguments:** Prompts can accept arguments defined by the server's prompt schema
+
+### Integration with Plugin Commands
+
+If your plugin bundles an MCP server that exposes prompts, those prompts become available when the plugin is installed. This provides another mechanism for guided workflows:
+
+```markdown
+# Example: Plugin README documenting MCP prompts
+
+## Available MCP Prompts
+
+After installing this plugin, the following MCP prompts are available:
+
+- `/mcp__myserver__create-report` - Generate a structured report
+- `/mcp__myserver__analyze-data` - Run data analysis with guided inputs
+```
+
+### When to Use MCP Prompts vs Plugin Commands
+
+| Approach | Best For |
+| --- | --- |
+| MCP prompts | Server-defined workflows, dynamic templates from external services |
+| Plugin commands | Static workflows, plugin-specific logic, complex prompt composition |
+
+**Tip:** MCP prompts are ideal when the workflow logic lives on the server side and may change independently of the plugin. Plugin commands are better when you want full control over the prompt content.