@wisewandtools/mcp-server 2.0.0

package/README.md

@@ -0,0 +1,727 @@
+# Wisewand MCP Server
+
+Production-ready Model Context Protocol (MCP) server for Wisewand API, enabling AI assistants like Claude to generate SEO-optimized content through natural conversation.
+
+> **📚 Choose Your Guide:**
+> - 🏁 [**Getting Started (5 min)**](./GETTING_STARTED.md) - Quickest path to your first article
+> - 🚀 [**Installation Guide**](./INSTALL.md) - Detailed step-by-step for beginners
+> - ⚡ [**Quick Reference**](./QUICK_REFERENCE.md) - Cheat sheet for common tasks
+> - 📖 **Full Documentation** - See below
+
+## Features
+
+- 🚀 **Complete API Coverage**: All Wisewand API endpoints wrapped as MCP tools
+- 🔄 **Robust Error Handling**: Automatic retries with exponential backoff
+- 💾 **Intelligent Caching**: Multi-tier caching (memory + Redis)
+- 🔒 **Security First**: Rate limiting, API key management, input validation
+- 📊 **Comprehensive Monitoring**: Prometheus metrics, health checks, logging
+- 🎯 **SEO Optimization**: Built-in support for all Wisewand SEO features
+- 📦 **Bulk Operations**: Efficient batch processing for large-scale content
+- 🌍 **Multi-language**: Support for French and English with localization
+- 📱 **Social Media**: Generate posts for Instagram, Facebook, X, LinkedIn
+- 🎨 **Image Generation**: Custom images with color palettes and ratios
+
+## Quick Start
+
+> 👉 **New to MCP servers?** Start with the [Step-by-Step Installation Guide (INSTALL.md)](./INSTALL.md) - it's beginner-friendly!
+
+### Prerequisites
+
+- **Node.js 20+** (check with `node --version`)
+- **npm** (comes with Node.js)
+- **Wisewand API key** ([Get yours here](https://wisewand.ai))
+- **Claude Desktop** (for using with Claude AI)
+
+### NPM Installation (Easiest) ⭐
+
+Install globally via npm:
+
+```bash
+npm install -g @wisewand/mcp-server
+```
+
+Or use with **npx** (no installation needed - recommended):
+
+#### Configure Claude Desktop
+
+**Find your configuration file:**
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Add this configuration:**
+
+```json
+{
+  "mcpServers": {
+    "wisewand": {
+      "command": "npx",
+      "args": ["-y", "@wisewand/mcp-server"],
+      "env": {
+        "WISEWAND_API_KEY": "sk_live_YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+**Restart Claude Desktop** and you're ready to go! 🎉
+
+> 💡 **Tip**: With npx, the package is always downloaded fresh, so you automatically get the latest version.
+
+---
+
+### Local Installation (For Development)
+
+#### Step 1: Clone and Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/wisewand/mcp-wisewand.git
+cd mcp-wisewand
+
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+```
+
+#### Step 2: Configure Your API Key
+
+Edit `.env` file and add your Wisewand API key:
+
+```bash
+# Required
+WISEWAND_API_KEY=sk_live_YOUR_API_KEY_HERE
+
+# Optional (recommended for production)
+NODE_ENV=production
+LOG_LEVEL=error
+ENABLE_CACHE=true
+CACHE_STRATEGY=memory
+```
+
+#### Step 3: Build the Project
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `dist/` folder.
+
+#### Step 4: Configure Claude Desktop
+
+**Find your Claude configuration file:**
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Add this configuration** (see [claude-desktop-config-example.json](./claude-desktop-config-example.json)):
+
+```json
+{
+  "mcpServers": {
+    "wisewand": {
+      "command": "npx",
+      "args": ["tsx", "/absolute/path/to/mcp-wisewand/src/index.ts"],
+      "env": {
+        "WISEWAND_API_KEY": "sk_live_YOUR_API_KEY_HERE",
+        "NODE_ENV": "production",
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "ENABLE_CACHE": "true",
+        "ENABLE_METRICS": "false"
+      }
+    }
+  }
+}
+```
+
+**⚠️ IMPORTANT REPLACEMENTS:**
+1. Replace `/absolute/path/to/mcp-wisewand/src/index.ts` with your actual path (use `pwd` to get it)
+2. Replace `sk_live_YOUR_API_KEY_HERE` with your Wisewand API key
+
+**💡 Pro Tip**: Use `npx tsx` instead of `node dist/index.js` for development - it automatically recompiles on changes!
+
+#### Step 5: Restart Claude Desktop
+
+1. **Quit Claude Desktop completely** (Cmd+Q on macOS)
+2. **Reopen Claude Desktop**
+3. Look for the **🔌 MCP icon** at the bottom of the chat window
+4. You should see **"wisewand"** listed as a connected server
+
+#### Step 6: Verify Installation
+
+In Claude Desktop, type:
+
+```
+Can you list all available Wisewand tools?
+```
+
+You should see 43 tools including `create_article`, `generate_article`, `publish_to_wordpress`, etc.
+
+---
+
+## Installation Verification Checklist
+
+After installation, verify everything works:
+
+- [ ] **Dependencies installed**: `npm install` completed without errors
+- [ ] **Build successful**: `npm run build` completed
+- [ ] **Server starts**: `npx tsx src/index.ts` runs without errors (Ctrl+C to stop)
+- [ ] **Claude Desktop config**: File exists and has wisewand entry
+- [ ] **Absolute path**: Path in config points to your installation directory
+- [ ] **API key set**: Both `.env` and `claude_desktop_config.json` have valid key
+- [ ] **Claude restarted**: Fully quit and reopened Claude Desktop
+- [ ] **MCP connected**: 🔌 icon shows wisewand server in Claude
+- [ ] **Tools available**: Ask Claude "List Wisewand tools" shows 43 tools
+
+### Need Help?
+
+If any checkbox fails, see the [Troubleshooting](#troubleshooting) section below.
+
+### Docker Installation (Alternative)
+
+```bash
+# Using Docker Compose
+docker-compose up -d
+
+# Or using Docker directly
+docker build -t wisewand-mcp .
+docker run -p 3000:3000 -p 9090:9090 \
+  -e WISEWAND_API_KEY=your_key \
+  wisewand-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `WISEWAND_API_KEY` | Your Wisewand API key (required) | - |
+| `NODE_ENV` | Environment (development/production) | production |
+| `LOG_LEVEL` | Logging level (error/warn/info/debug) | info |
+| `ENABLE_CACHE` | Enable caching | true |
+| `CACHE_STRATEGY` | Cache strategy (memory/redis/hybrid) | memory |
+| `REDIS_HOST` | Redis host | localhost |
+| `REDIS_PORT` | Redis port | 6379 |
+| `MAX_REQUESTS_PER_MINUTE` | Rate limit | 60 |
+| `ENABLE_METRICS` | Enable Prometheus metrics | true |
+| `METRICS_PORT` | Metrics server port | 9090 |
+
+---
+
+## How to Use
+
+### Basic Workflow
+
+Once installed, you can use Wisewand through natural conversation with Claude:
+
+#### **1. Create an Article**
+
+Simply ask Claude:
+```
+Create a blog article about "10 Best SEO Tips for 2024" targeting the keyword "SEO tips 2024" with FAQ and table of contents
+```
+
+Claude will use the `create_article` tool with the appropriate parameters.
+
+#### **2. Generate Content**
+
+```
+Generate the article we just created and wait for completion
+```
+
+Claude will use `generate_article` to process your content (takes 30-180 seconds).
+
+#### **3. Get the Content**
+
+```
+Show me the full article content
+```
+
+Claude will use `get_article_output` to retrieve the generated markdown/HTML.
+
+#### **4. Publish to WordPress** (optional)
+
+```
+Publish this article to WordPress as a draft
+```
+
+Claude will use `publish_to_wordpress` if you have a WordPress connection configured.
+
+### Advanced Usage
+
+#### **Create Project for Organization**
+```
+Create a project called "My Tech Blog" for website techblog.com with English as default language
+```
+
+#### **Define Custom Writing Style**
+```
+Create a persona called "Tech Expert" with an authoritative tone, technical style, and first-person plural voice
+```
+
+#### **Bulk Content Generation**
+```
+Create 5 blog articles about: AI basics, Machine Learning, Neural Networks, Deep Learning, and Computer Vision. Auto-generate all of them.
+```
+
+#### **Social Media Generation** (NEW!)
+```
+Create an article about "AI in Healthcare 2024" with social media posts for Instagram and LinkedIn
+```
+
+#### **Custom Image Generation**
+```
+Create an article with a featured image using color palette #FF6B6B and #4ECDC4, and inline images with landscape ratio
+```
+
+---
+
+## Complete Workflow Example
+
+Here's a complete example of creating and publishing an article:
+
+### Conversation with Claude:
+
+```
+You: "I need to create an SEO article about '10 Best AI Tools for Content Creation'
+     targeting the keyword 'AI content tools 2024'. Include FAQ, table of contents,
+     and generate a featured image with inline images."
+
+Claude: [Uses create_article tool]
+        ✅ Article created with ID: abc-123-def
+
+You: "Great! Now generate the content and wait until it's ready."
+
+Claude: [Uses generate_article tool with wait_for_completion: true]
+        ⏳ Generating... (this takes ~60-120 seconds)
+        ✅ Article generated successfully!
+        - Word count: 2,847 words
+        - SEO score: 94/100
+        - FAQ: 8 questions generated
+        - Images: 1 featured + 3 inline images
+
+You: "Show me the title and excerpt"
+
+Claude: [Uses get_article_output tool]
+        📄 Title: "10 Best AI Tools for Content Creation in 2024"
+        📝 Excerpt: "Discover the most powerful AI tools transforming
+            content creation. From writing assistants to image generators..."
+
+You: "Perfect! Publish this to WordPress as a draft."
+
+Claude: [Uses publish_to_wordpress tool]
+        ✅ Published to WordPress as draft
+        🔗 URL: https://yourblog.com/wp-admin/post.php?post=456
+```
+
+### What Just Happened?
+
+1. **Created** an article with SEO configuration
+2. **Generated** content using Wisewand AI (with FAQ, TOC, images)
+3. **Retrieved** the output to preview
+4. **Published** to WordPress automatically
+
+All through natural conversation! 🎉
+
+---
+
+## Alternative Installation Methods
+
+## Available Tools (43 Total - Complete API Coverage!)
+
+### 📝 Content Generation (7 tools)
+- `create_article` - Create SEO-optimized articles with 54 configuration options
+- `generate_article` - Generate content for articles (async, waits for completion)
+- `get_article` - Retrieve article details and status
+- `list_articles` - List and search articles with filtering
+- `update_article` - Update article settings
+- `get_article_output` - Get generated content (markdown/HTML)
+- `estimate_article_cost` - Calculate generation costs before creating
+
+### 📁 Project Management (5 tools)
+- `create_project` - Create content projects for organization
+- `get_project` - Get project details
+- `list_projects` - List all projects
+- `update_project` - Update project settings
+- `delete_project` - Delete projects (requires confirmation)
+
+### ✍️ Personas & Style (5 tools)
+- `create_persona` - Define custom writing styles and voices
+- `get_persona` - Get persona details
+- `list_personas` - List all personas
+- `update_persona` - Update persona settings
+- `delete_persona` - Delete personas (requires confirmation)
+
+### 🔌 Connections (5 tools)
+- `list_connections` - List all WordPress and webhook connections
+- `get_connection` - Get connection details by ID
+- `create_connection` - Create new WordPress or webhook connection
+- `update_connection` - Update existing connection configuration
+- `delete_connection` - Delete connection (requires confirmation)
+
+### 🚀 Publishing (2 tools)
+- `publish_to_wordpress` - Publish to WordPress sites
+- `trigger_webhook` - Send content via webhooks
+
+### 📦 Bulk Operations (2 tools)
+- `bulk_create_articles` - Create multiple articles at once (up to 100)
+- `bulk_estimate_cost` - Estimate costs for bulk generation
+
+### 🏪 E-commerce Content (8 tools)
+
+**Category Pages:**
+- `create_category_page` - Create SEO-optimized category landing pages
+- `get_category_page` - Get category page details and status
+- `generate_category_page` - Generate category page content
+- `get_category_page_output` - Get generated category page content
+
+**Product Pages:**
+- `create_product_page` - Create product description pages
+- `get_product_page` - Get product page details and status
+- `generate_product_page` - Generate product page content
+- `get_product_page_output` - Get generated product page content
+
+### 🔍 Content Discovery & Automation (6 tools)
+
+**Content Discovery:**
+- `discover_content` - AI-powered content topic and keyword discovery
+- `get_discover_result` - Get discovery results and suggestions
+- `run_discovery` - Execute content discovery process
+
+**RSS Automation:**
+- `create_rss_trigger` - Create automated RSS-to-content trigger
+- `get_rss_trigger` - Get RSS trigger configuration and status
+- `run_rss_trigger` - Manually execute RSS feed processing
+
+### 🛠️ Utility Tools (3 tools)
+- `get_authors` - Get available WordPress authors for publishing
+- `get_categories` - Get available WordPress categories
+- `get_usage_summary` - Get account usage statistics and limits
+
+## Usage Examples
+
+### Create and Generate an Article
+
+```javascript
+// Create article
+const article = await create_article({
+  subject: "10 Best SEO Tips for 2024",
+  target_keyword: "SEO tips 2024",
+  lang: "en",
+  seo_features: {
+    use_faq: true,
+    use_toc: true,
+    use_boldkeywords: true
+  }
+});
+
+// Generate content
+await generate_article({
+  article_id: article.article_id,
+  wait_for_completion: true
+});
+
+// Get output
+const output = await get_article_output({
+  article_id: article.article_id
+});
+```
+
+### Bulk Content Generation
+
+```javascript
+// Create multiple articles
+await bulk_create_articles({
+  articles: [
+    { subject: "Topic 1", target_keyword: "keyword1" },
+    { subject: "Topic 2", target_keyword: "keyword2" },
+    { subject: "Topic 3", target_keyword: "keyword3" }
+  ],
+  auto_generate: true
+});
+```
+
+## API Documentation
+
+### Tool Response Format
+
+All tools return responses in this format:
+
+```json
+{
+  "success": true,
+  "data": {},
+  "message": "Operation completed successfully"
+}
+```
+
+Error responses:
+
+```json
+{
+  "error": true,
+  "message": "Error description",
+  "details": {}
+}
+```
+
+## Monitoring
+
+### Health Check
+```bash
+curl http://localhost:9090/health
+```
+
+### Metrics
+```bash
+curl http://localhost:9090/metrics
+```
+
+### Available Metrics
+- `mcp_tool_calls_total` - Total tool calls
+- `mcp_tool_call_duration_ms` - Tool execution time
+- `wisewand_api_calls_total` - API calls to Wisewand
+- `cache_hits_total` - Cache hit rate
+- `mcp_active_connections` - Active connections
+
+## Development
+
+### Running in Development Mode
+```bash
+npm run dev
+```
+
+### Running Tests
+```bash
+npm test
+npm run test:coverage
+```
+
+### Linting
+```bash
+npm run lint
+npm run format
+```
+
+### Type Checking
+```bash
+npm run typecheck
+```
+
+## Architecture
+
+```
+src/
+├── server/              # Core MCP server
+│   └── WisewandMCPServer.ts
+├── clients/             # API clients
+│   └── WisewandAPIClient.ts
+├── handlers/            # Request handlers
+│   ├── tools/          # Tool implementations
+│   ├── resources/      # Resource handlers
+│   └── prompts/        # Prompt templates
+├── services/           # Core services
+│   ├── CacheManager.ts
+│   └── RateLimiter.ts
+├── monitoring/         # Monitoring & metrics
+│   ├── MetricsCollector.ts
+│   └── HealthChecker.ts
+├── types/              # TypeScript definitions
+└── utils/              # Utilities
+```
+
+## Performance
+
+- **Response Time**: < 2s for standard operations
+- **Throughput**: 60 requests/minute (configurable)
+- **Caching**: 5-minute TTL for frequently accessed data
+- **Concurrency**: Handles 100+ simultaneous connections
+- **Memory Usage**: < 500MB typical, < 1GB peak
+
+## Security
+
+- ✅ API key authentication
+- ✅ Rate limiting per client
+- ✅ Input validation with Zod
+- ✅ Secure error handling
+- ✅ No sensitive data in logs
+- ✅ Docker security best practices
+- ✅ Non-root container execution
+
+## Troubleshooting
+
+### Claude Desktop Integration Issues
+
+#### **Problem: MCP server not showing up in Claude**
+
+**Solutions:**
+1. **Verify configuration file location**
+   ```bash
+   # macOS - check if file exists
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
+
+   # Should show your wisewand configuration
+   ```
+
+2. **Check absolute path**
+   ```bash
+   # Get absolute path of your installation
+   cd /path/to/mcp-wisewand
+   pwd
+   # Use this EXACT path in claude_desktop_config.json
+   ```
+
+3. **Verify API key format**
+   - Must start with `sk_live_`
+   - No extra spaces or quotes
+   - Check at [wisewand.ai/dashboard](https://wisewand.ai/dashboard)
+
+4. **Check server logs**
+   ```bash
+   # Test server manually
+   MCP_MODE=stdio LOG_LEVEL=error npx tsx src/index.ts
+   # Should start without errors
+   ```
+
+5. **Restart Claude Desktop properly**
+   - Fully quit (Cmd+Q, not just close window)
+   - Wait 5 seconds
+   - Reopen Claude Desktop
+   - Check MCP icon 🔌 at bottom
+
+#### **Problem: "Module not found" errors**
+
+**Solution:**
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+
+# Rebuild
+npm run build
+```
+
+#### **Problem: API key authentication fails**
+
+**Solutions:**
+1. Verify key in `.env` matches `claude_desktop_config.json`
+2. Check key hasn't expired at Wisewand dashboard
+3. Test API key directly:
+   ```bash
+   curl https://api.wisewand.ai/v1/articles/ \
+     -H "Authorization: Bearer sk_live_YOUR_KEY"
+   ```
+
+#### **Problem: Tools not appearing in Claude**
+
+**Solutions:**
+1. Check MCP connection status in Claude Desktop
+2. Look for error messages in Claude's developer console:
+   - **macOS**: `~/Library/Logs/Claude/mcp*.log`
+3. Verify all 43 tools are loaded:
+   ```bash
+   # Ask Claude: "List all Wisewand tools"
+   # Should show: create_article, generate_article, etc.
+   ```
+
+### General Issues
+
+1. **Rate Limiting (429 errors)**
+   - Wisewand API: 60 requests/minute
+   - Adjust `MAX_REQUESTS_PER_MINUTE` in `.env`
+   - Use bulk operations for multiple articles
+
+2. **Connection Timeouts**
+   - Article generation takes 30-180 seconds
+   - Increase `WISEWAND_TIMEOUT` in `.env` (default: 30000ms)
+   - Use `wait_for_completion: true` in generate_article
+
+3. **Cache Issues**
+   - Clear cache: Restart MCP server (restart Claude Desktop)
+   - Disable cache: Set `ENABLE_CACHE=false` in config
+   - Check Redis connection if using Redis strategy
+
+4. **Memory Usage**
+   - Monitor with: Ask Claude "Check Wisewand server health"
+   - Reduce `MAX_CACHE_SIZE_MB` if needed
+   - Use Redis instead of memory cache for large operations
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to the branch
+5. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Support
+
+- **Documentation**: [https://api.wisewand.ai/docs](https://api.wisewand.ai/docs)
+- **Issues**: [GitHub Issues](https://github.com/wisewand/mcp-wisewand/issues)
+- **Email**: support@wisewand.ai
+
+## Changelog
+
+### v1.2.0 (2025-09-30) - COMPLETE API COVERAGE
+- 🚀 **COMPLETE**: Added 26 missing MCP tools - now 43 total (100% API coverage)!
+- ✨ **NEW CATEGORY**: Connections tools (5) - list, get, create, update, delete
+- ✨ **NEW CATEGORY**: E-commerce tools (8) - Category & Product pages with generation
+- ✨ **NEW CATEGORY**: Content Discovery tools (3) - AI-powered topic discovery
+- ✨ **NEW CATEGORY**: RSS Automation tools (3) - Automated content from feeds
+- ✨ **NEW CATEGORY**: Utility tools (3) - Authors, categories, usage stats
+- 📊 **ENHANCED**: 11 tool handler files (was 5, now 11)
+- 📊 **COVERAGE**: From 40% to 100% API endpoint coverage
+- 📚 **UPDATED**: All documentation reflects complete tool set
+
+### v1.1.0 (2025-09-30)
+- ✨ **NEW**: Social media post generation (`use_social`, `social_networks`)
+- ✨ **NEW**: Inline images ratio control (`inline_images_ratio`)
+- ✨ **NEW**: Source restriction control (`information_search_only_from_subject_sources`)
+- 🔧 **FIXED**: Renamed `use_inlineimages` to `use_inline_images` for API compatibility
+- 🔧 **UPDATED**: Audio voice ID default value to `jSrrwmj13CIlQAXPpk4X`
+- 📚 **IMPROVED**: README with detailed local installation guide
+- 📚 **IMPROVED**: Claude Desktop setup instructions and troubleshooting
+
+### v1.0.0 (2024-12-27)
+- 🎉 Initial release
+- 🚀 Complete Wisewand API coverage (51 endpoints)
+- 🏗️ Production-ready implementation
+- 🐳 Docker support with multi-stage builds
+- 📊 Comprehensive monitoring (Prometheus, health checks)
+- 🔒 Security features (rate limiting, validation)
+- 💾 Multi-tier caching (memory/Redis/hybrid)
+
+---
+
+## FAQ
+
+### How much does it cost to generate articles?
+Use the `estimate_article_cost` tool to calculate costs before generation. Typical costs:
+- Blog post (1000 words): ~10-20 credits
+- With images: +5-10 credits
+- With social media posts: +2-5 credits
+
+### Can I use this without Claude Desktop?
+Yes! The server can run standalone via Docker or Node.js and be accessed through the MCP protocol from any MCP-compatible client.
+
+### Where can I get a Wisewand API key?
+Visit [wisewand.ai](https://wisewand.ai) and sign up for an account. API keys are available in your dashboard.
+
+### How long does article generation take?
+- Article creation: ~1 second
+- Content generation: 30-180 seconds (depending on length and features)
+- Use `wait_for_completion: true` to wait automatically
+
+---
+
+Built with ❤️ by Wisewand Team