# MCP (Model Context Protocol) - AI Control
**MCP is the primary and recommended way to work with the project.** Instead of remembering CLI commands, you manage publications through AI assistant using natural language directly in Cursor, Claude, or other AI tools.
## What is MCP?
Model Context Protocol is an open standard that allows AI models to safely access external data and perform actions in the real world.
**In this project, MCP is used for:**
- Managing publications through natural language (primary way of working)
- Integration with AI assistants (Cursor, Claude Desktop, etc.)
- Automating publication planning through AI
- Smart content generation with context
## Quick Start
### 1. Build the Project
```bash
npm install
npm run build
```
### 2. Setup in Cursor (Automatic)
The `.cursor/mcp.json` file is already configured in the project. After building, the MCP server is automatically available in Cursor - **no additional setup needed!**
Simply start using natural language in Cursor chat:
```
"Publish IMG_0802.JPG tomorrow at 18:00"
```
### 3. Restart Cursor
**Important:** After building the project, completely restart Cursor (close the application and open it again) for the MCP server to connect.
## Setup for Other AI Tools
### Claude Desktop
1. Find the configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add configuration:
```json
{
"mcpServers": {
"content-automation": {
"command": "node",
"args": ["dist/mcp/mcp-server.js"],
"cwd": "/"
}
}
}
```
3. Restart Claude Desktop
### Windsurf / VS Code
Add similar MCP server configuration in the tool settings.
## Available MCP Tools
### 1. `generate_content`
Generates content for Pinterest and Instagram from an image.
**Parameters:**
- `imagePathOrUrl` (required) - Path to local file or CDN URL
- `userContext` (optional) - Context (location, mood, etc.)
**Prompt Examples:**
```
"Generate content for image IMG_0802.JPG with context 'Concert hall, evening'"
"Create content for IMG_1460.JPG with context 'City center, morning light'"
"Show what content will be generated for IMG_2228.JPG"
```
### 2. `schedule_post`
Schedules publication to Instagram and Pinterest through Late API.
**Parameters:**
- `imagePathOrUrl` (required) - Path to local file or CDN URL
- `userContext` (optional) - Context for content generation
- `publishDate` (required) - Publication date (ISO, "YYYY-MM-DD HH:MM", "tomorrow 18:00", "1 hour"). Must not be in the past
- `instagramType` (optional) - Content type: 'post' or 'story'
- `platforms` (optional) - Platforms: ['instagram', 'pinterest'] or ['instagram'] or ['pinterest']
- `isDraft` (optional) - Create as draft
- `carouselAdditionalImagePaths` (optional) - Array of 2nd, 3rd, ... image filenames for Instagram carousel (2–10 photos total). First image = `imagePathOrUrl`
**Prompt Examples:**
```
"Publish IMG_0802.JPG tomorrow at 18:00"
"Schedule publication of IMG_1460.JPG for January 25 at 18:00 with context 'City center'"
"Publish Story for IMG_2228.JPG today at 20:00"
"Create draft for Instagram post and Pinterest post from image IMG_6342.JPG, context 'City center'"
"Publish only to Pinterest IMG_5857.JPG tomorrow at 12:00"
```
### 3. `get_cdn_url`
Builds CDN URL from filename.
**Parameters:**
- `filename` (required) - Filename
**Prompt Examples:**
```
"What is the CDN URL for file IMG_0802.JPG?"
"Check CDN configuration"
```
## Usage Examples
### Example 1: Simple Publication
**Prompt:**
```
Publish IMG_0802.JPG tomorrow at 18:00
```
**What will happen:**
1. AI will generate content for Pinterest and Instagram
2. Schedule publication through Late API for tomorrow at 18:00
3. Confirm successful scheduling
### Example 2: Publication with Context
**Prompt:**
```
Publish IMG_1460.JPG on January 25 at 18:00 with context
"Concert hall, evening light, architectural masterpiece,
cultural venue, modern design"
```
**What will happen:**
1. AI will use detailed context for content generation
2. Create unique SEO-optimized content for Pinterest
3. Create emotional content for Instagram
4. Schedule publication for the specified date
### Example 3: Story Publication
**Prompt:**
```
Publish Story for IMG_2228.JPG today at 20:00
```
**What will happen:**
1. AI will determine this is a Story (24-hour limitation)
2. Schedule publication for today
3. Use Instagram Stories format
### Example 4: Draft
**Prompt:**
```
Create draft for Instagram post and Pinterest post
from image IMG_6342.JPG, context "City center"
```
**What will happen:**
1. Create draft with publication date
2. Content will be ready but not published immediately
3. Can be published later through Late API dashboard
### Example 5: Pinterest Only
**Prompt:**
```
Publish only to Pinterest IMG_5857.JPG tomorrow at 12:00
```
**What will happen:**
1. Publication only to Pinterest (without Instagram)
2. SEO-optimized content for Pinterest is used
### Example 6: Instagram Carousel
**Prompt:**
```
Create draft carousel from IMG_1001.HEIC, IMG_1002.HEIC, IMG_1003.HEIC
for Instagram, tomorrow at 18:00
```
**What will happen:**
1. All images will be processed in parallel (HEIC → JPG, crop 4:5)
2. AI will generate content based on the first image
3. Draft carousel post (3 photos) will be created in Late API
### Example 7: Bulk Publication
**Prompt:**
```
Publish all available images, starting tomorrow,
with 2-day intervals between publications
```
**What will happen:**
1. AI will get list of all available images
2. For each image, schedule publication
3. Automatically distribute publications with 2-day intervals
### Example 8: Content Generation Without Publication
**Prompt:**
```
Generate content for IMG_0802.JPG with context
"City center, morning, modern architecture"
```
**What will happen:**
1. AI will generate content for both platforms
2. Show result without publication
3. You can decide whether to publish this content
## Proper Request Formulation
### ✅ Correct Requests (AI uses MCP tools):
```
"Publish IMG_6342.JPG tomorrow at 18:00 with context 'City center'"
"Create draft for Instagram post and Pinterest post from image IMG_6342.JPG"
"Make Story for Instagram from IMG_6342.JPG, context 'City center', draft"
"Show available images for publication"
```
### ❌ Incorrect Requests (AI will search for files):
```
"Find file IMG_6342.JPG and run publish command"
"Run script to publish IMG_6342.JPG"
"Use npm run publish for IMG_6342.JPG"
```
## Troubleshooting
### Problem: AI Searches for Files Instead of Using MCP
**Solution:**
1. **Make sure the project is built:**
```bash
npm run build
```
2. **Completely restart Cursor:**
- Close Cursor completely (not just the window)
- Wait 5-10 seconds
- Open Cursor again
3. **Check MCP settings in Cursor:**
- Open settings (Cmd+, or Ctrl+,)
- Find "MCP Servers" section
- Make sure `content-automation` is active
4. **Formulate requests correctly:**
- Use natural language
- Don't mention commands or files directly
- Simply describe what needs to be done
### Problem: MCP Server Doesn't Start
**Solution:**
1. Check that file `dist/mcp/mcp-server.js` exists
2. Make sure Node.js is installed and available
3. Check path in `.cursor/mcp.json` - should point to project root
### Problem: Code Changes Don't Apply
**Solution:**
1. Run watch mode for automatic recompilation:
```bash
npm run watch
```
2. Cursor will automatically restart MCP server when `dist/mcp/mcp-server.js` changes
## Dev Mode (Testing)
When using `npm run watch`, `DEV_MODE=true` is automatically enabled:
- ✅ Requests to Late API are **NOT sent**
- ✅ JSON ready to send is output to terminal
- ✅ Allows testing logic without real publications
- ✅ Saves free plan limits of Late API
**Example output in dev mode:**
```
🔧 DEV MODE: Dry-run (no actual API call)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📤 POST https://getlate.dev/api/v1/posts
📋 Request Body (JSON ready to send):
{
"profile_id": "...",
"platforms": [...],
"media_urls": [...],
"scheduled_at": "...",
...
}
```
## MCP Benefits
✅ **Natural language** - No need to remember commands
✅ **Automation** - AI can plan publications itself
✅ **Integration** - Works directly in your AI tool
✅ **Contextual understanding** - AI understands your intentions
✅ **Security** - MCP provides secure access to APIs
✅ **Flexibility** - Can be combined with other MCP servers
## Compatibility
MCP server is compatible with:
- Cursor ⭐ (recommended)
- Claude Desktop
- Windsurf
- VS Code (with MCP extension)
- Any other clients supporting MCP
