# 🔧 MCP Tool Library Guide - For AI Agents

## 📍 Location

**All MCP tool templates are in:** `templates/mcp-tool-library/`

## 🎯 What This Library Contains

This is a comprehensive reference library of **real MCP server integration templates**. Each template shows you how to interact with actual, production MCP servers that you can use RIGHT NOW.

## ⚡ Quick Access

| Category | Path | What's Inside |
|----------|------|---------------|
| **Database** | `templates/mcp-tool-library/database/` | MongoDB, Pinecone, Supabase, Neo4j, Postgres |
| **Cloud** | `templates/mcp-tool-library/cloud/` | AWS S3, Azure, Google Cloud, Render |
| **Productivity** | `templates/mcp-tool-library/productivity/` | Notion, Slack, Zapier, Taskade, Calendar |
| **Developer** | `templates/mcp-tool-library/developer/` | GitHub, JetBrains, Git, Filesystem, CI/CD |
| **Security** | `templates/mcp-tool-library/security/` | Semgrep, SonarQube, Sentry, Auth0 |
| **Search** | `templates/mcp-tool-library/search/` | Tavily, Exa, Perplexity, Kagi |
| **Blockchain** | `templates/mcp-tool-library/blockchain/` | Thirdweb, Token Metrics, Trading |

## 🚀 How to Use This Library

### Step 1: Find What You Need

**Example:** User asks "Can you create a GitHub issue for this bug?"

1. Open `templates/mcp-tool-library/MCP-TOOL-LIBRARY-INDEX.md`
2. Find `developer/github-operations.md`
3. Read the template

### Step 2: Read the Template

Each template has this structure:

```markdown
# IDENTITY and PURPOSE
[What this server does]

# REAL MCP SERVER
Name: github
Install: npx -y @modelcontextprotocol/server-github
Repository: [link]

# CAPABILITIES
- List of what it can do

# PARAMETERS
- Detailed parameters for each operation

# STEPS
1. How to use it
2. Authentication
3. Making requests

# OUTPUT
[Expected responses with examples]

# EXAMPLES
[10+ real-world use cases with code]

# USAGE
[Security, patterns, error handling]
```

### Step 3: Use the Real MCP Server

**IMPORTANT:** These templates show you HOW to use the servers, but you need to:

1. **Check if the server is already configured** in the user's project
2. **Read the template** to understand parameters and expected output
3. **Use the MCP protocol** to call the actual server
4. **Handle responses** as documented in the template

## 📚 Complete Template List

### Database Templates (5)
- ✅ **mongodb-query.md** - MongoDB database operations, queries, updates
- **pinecone-vector-search.md** - Vector similarity search, embeddings
- **supabase-realtime.md** - Realtime database, edge functions
- **postgres-schema.md** - PostgreSQL schema and query operations
- **neo4j-graph.md** - Graph database queries and relationships

### Cloud Templates (5)
- ✅ **aws-s3-operations.md** - S3 upload/download, bucket management
- **aws-lambda-deploy.md** - Lambda function deployment and invocation
- **azure-storage.md** - Azure blob storage operations
- **google-cloud-run.md** - Deploy containers to Cloud Run
- **render-service.md** - Render service deployment

### Productivity Templates (5)
- ✅ **notion-database.md** - Notion pages, databases, properties
- ✅ **slack-messaging.md** - Slack messages, channels, threads
- **zapier-workflow.md** - Zapier automation triggers
- **taskade-projects.md** - Task and project management
- **routine-calendar.md** - Calendar events and scheduling

### Developer Templates (5)
- ✅ **github-operations.md** - GitHub repos, issues, PRs, code search
- **jetbrains-ide.md** - JetBrains IDE integration
- **git-repository.md** - Git clone, commit, branch operations
- **filesystem-ops.md** - File read/write/delete operations
- **buildkite-ci.md** - CI/CD pipeline management

### Security Templates (4)
- **semgrep-scan.md** - Code security scanning
- **sonarqube-analysis.md** - Code quality analysis
- **sentry-monitoring.md** - Error tracking and monitoring
- **auth0-management.md** - Authentication and user management

### Search Templates (4)
- ✅ **tavily-ai-search.md** - AI-optimized web search
- **exa-semantic.md** - Semantic search engine
- **perplexity-research.md** - Web research API
- **kagi-search.md** - Kagi search integration

### Blockchain Templates (3)
- **thirdweb-contracts.md** - Smart contract interaction (2000+ blockchains)
- **token-metrics.md** - Crypto market data and analytics
- **trade-execution.md** - Stock and crypto trading operations

## 🎓 Example Workflows

### Workflow 1: Creating a GitHub Issue

User asks: *"Create an issue in the repo tracking this bug"*

**What you do:**

1. **Read template**: `developer/github-operations.md`
2. **Find example**: "Create Issue" section
3. **Extract pattern**:
   ```javascript
   {
     "server": "github",
     "operation": "createIssue",
     "params": {
       "owner": "username",
       "repo": "repository",
       "title": "Bug: Description",
       "body": "Detailed bug report",
       "labels": ["bug"]
     }
   }
   ```
4. **Use real server**: Call GitHub MCP server with these parameters
5. **Return result**: "Created issue #123 in username/repository"

### Workflow 2: Uploading to S3

User asks: *"Upload this log file to S3"*

**What you do:**

1. **Read template**: `cloud/aws-s3-operations.md`
2. **Find example**: "Upload File" section
3. **Extract pattern**:
   ```javascript
   {
     "server": "aws",
     "operation": "putObject",
     "params": {
       "Bucket": "my-logs",
       "Key": "logs/2025-10-05.log",
       "Body": fileContent,
       "ContentType": "text/plain"
     }
   }
   ```
4. **Use real server**: Call AWS MCP server
5. **Return result**: "Uploaded to s3://my-logs/logs/2025-10-05.log"

### Workflow 3: Querying MongoDB

User asks: *"Find all active users who logged in today"*

**What you do:**

1. **Read template**: `database/mongodb-query.md`
2. **Find example**: "Find with Filter" section
3. **Extract pattern**:
   ```javascript
   {
     "server": "mongodb",
     "operation": "find",
     "params": {
       "database": "app",
       "collection": "users",
       "filter": {
         "status": "active",
         "lastLogin": { "$gte": "2025-10-05T00:00:00Z" }
       }
     }
   }
   ```
4. **Use real server**: Call MongoDB MCP server
5. **Return results**: List of matching users

## 🔥 Pro Tips for AI Agents

### Tip 1: Always Read the Template First

DON'T guess the API. The templates have:
- ✅ Exact parameter names and types
- ✅ Real working examples
- ✅ Error handling patterns
- ✅ Security best practices

### Tip 2: Check for Existing Servers

Before suggesting a new server install, check if it's already configured in:
- `.claude.json` (mcpServers section)
- `.gemini/config.json`
- User's MCP configuration

### Tip 3: Use Examples as Starting Points

Each template has 8-10 examples. Copy the closest one and adapt it.

### Tip 4: Handle Errors Properly

Templates include common errors and solutions:
- Connection failures
- Authentication issues
- Rate limits
- Invalid parameters

### Tip 5: Follow Security Guidelines

Every template has a "Security Best Practices" section. ALWAYS:
- Use read-only credentials when possible
- Never expose API keys in responses
- Validate inputs before passing to MCP servers
- Log operations for audit trails

## 🚨 Common Mistakes to Avoid

### ❌ Mistake 1: Creating Your Own MCP Tools

**DON'T:**
```
"I'll create a custom MCP tool for GitHub operations..."
```

**DO:**
```
"I'll use the official GitHub MCP server. Let me check the template..."
[Reads templates/mcp-tool-library/developer/github-operations.md]
```

### ❌ Mistake 2: Guessing Parameters

**DON'T:**
```javascript
// Guessing the API
{
  "server": "github",
  "action": "make_issue",  // Wrong!
  "data": { "name": "Bug" } // Wrong structure!
}
```

**DO:**
```javascript
// Read from template
{
  "server": "github",
  "operation": "createIssue",  // Correct from template
  "params": {                   // Correct structure
    "owner": "...",
    "repo": "...",
    "title": "..."
  }
}
```

### ❌ Mistake 3: Ignoring Security

**DON'T:**
```javascript
// Exposing sensitive data
{
  "apiKey": "sk-123456789",  // NEVER expose keys!
  "password": "secret123"     // NEVER return passwords!
}
```

**DO:**
```javascript
// Use template security patterns
{
  "projection": { "password": 0, "apiKey": 0 },  // Exclude sensitive fields
  "redacted": true
}
```

## 📖 When to Add New Templates

Create a new template when:
1. **A popular MCP server isn't covered** (check awesome-mcp-servers list)
2. **You use a server frequently** and want to document patterns
3. **Users request a specific integration** multiple times

## 🔗 Resources

- **MCP Tool Library Index**: `templates/mcp-tool-library/MCP-TOOL-LIBRARY-INDEX.md`
- **Official MCP Servers**: https://github.com/modelcontextprotocol/servers
- **Awesome MCP List**: https://github.com/wong2/awesome-mcp-servers
- **MCP Documentation**: https://modelcontextprotocol.io/

---

## ✨ Quick Reference

**Need database operations?** → `templates/mcp-tool-library/database/`
**Need cloud storage?** → `templates/mcp-tool-library/cloud/`
**Need GitHub integration?** → `templates/mcp-tool-library/developer/github-operations.md`
**Need web search?** → `templates/mcp-tool-library/search/tavily-ai-search.md`

**Remember:** These are TEMPLATES for real MCP servers, not executable tools themselves. Read them, understand the patterns, then use the actual MCP servers!

---

*Part of FR3K v10.1.0 - Universal AI CLI Configuration System*
*Last Updated: 2025-10-05*