Initial commit
This commit is contained in:
Zhongwei Li
538
skills/mcp-integration/references/tool-usage.md
Normal file
538
skills/mcp-integration/references/tool-usage.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# 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 you're authenticated 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.
|
||||
Reference in New Issue
Block a user