# ✅ PAYLOAD MCP SERVER - PUBLISHED & READY

**Published:** 2025-10-30  
**Package:** `@xeniac/payload-mcp@1.0.0`  
**Registry:** https://mcpreg.xencolabs.com  
**Status:** ✅ LIVE AND AVAILABLE

---

## 📦 Package Information

```bash
npm view @xeniac/payload-mcp --registry=https://mcpreg.xencolabs.com

# Output:
@xeniac/payload-mcp@1.0.0 | MIT | deps: 3 | versions: 1
Payload CMS MCP Server
Published: just now
Tarball: https://mcpreg.xencolabs.com/@xeniac/payload-mcp/-/payload-mcp-1.0.0.tgz
```

---

## 🚀 USER INSTALLATION INSTRUCTIONS

### For Cursor Users

**Step 1: Get Your JWT Token**

```bash
curl -X POST https://cms.xencolabs.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com","password":"your-password"}'
```

**Response will include:**
```json
{
  "token": "eyJhbGci...",
  "user": {...}
}
```

**Step 2: Add to `.cursor/mcp.json`**

```json
{
  "mcpServers": {
    "payload": {
      "command": "npx",
      "args": [
        "-y",
        "--registry=https://mcpreg.xencolabs.com",
        "@xeniac/payload-mcp"
      ],
      "env": {
        "PAYLOAD_API_URL": "https://cms.xencolabs.com",
        "PAYLOAD_API_TOKEN": "paste-your-jwt-token-here"
      }
    }
  }
}
```

**Step 3: Reload Cursor**

- Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
- Type "Reload Window"
- Or restart Cursor

**Step 4: Verify It's Working**

In Cursor's AI chat:
```typescript
mcp_payload_server_info()
```

**Expected Response:**
```json
{
  "server": "payload-mcp",
  "version": "1.0.0",
  "status": "healthy",
  "connection": {
    "status": "connected",
    "baseURL": "https://cms.xencolabs.com",
    "authenticated": "configured",
    "responseTime": "~1500ms"
  },
  "currentUser": {
    "id": 2,
    "email": "your-email@example.com"
  },
  "tools_available": [
    "articles_list",
    "articles_get",
    "articles_create",
    "articles_update",
    "articles_delete",
    "sites_list",
    "sites_get",
    "sites_create",
    "media_list",
    "media_upload",
    "media_get",
    "search",
    "server_info"
  ]
}
```

---

## 🎯 USAGE EXAMPLES

### List Articles

```typescript
const articles = await mcp_payload_articles_list({
  page: 1,
  limit: 10,
  sort: '-createdAt'
});
```

### Create Article

```typescript
const newArticle = await mcp_payload_articles_create({
  title: 'Getting Started with Payload CMS',
  content: 'Payload is a powerful headless CMS that provides...',
  status: 'published'
});
```

### Search Content

```typescript
const results = await mcp_payload_search({
  query: 'typescript tutorial',
  collections: ['articles', 'sites'],
  limit: 20
});
```

### Get Server Status

```typescript
const status = await mcp_payload_server_info();
```

---

## 🔧 TROUBLESHOOTING

### "Authentication failed"

**Cause:** JWT token expired (tokens last ~2 hours)

**Fix:**
1. Get a new token via the login endpoint (see Step 1 above)
2. Update the `PAYLOAD_API_TOKEN` in `.cursor/mcp.json`
3. Reload Cursor

### "Connection timeout"

**Cause:** Network connectivity or firewall

**Fix:**
1. Test connectivity: `curl https://cms.xencolabs.com/api/users/me`
2. Check VPN/firewall settings
3. Verify you can reach cms.xencolabs.com

### "Module not found"

**Cause:** Package not found or wrong registry

**Fix:**
1. Verify registry URL: `https://mcpreg.xencolabs.com`
2. Ensure `--registry` flag is in args
3. Clear npm cache: `npm cache clean --force`
4. Retry: Cursor will re-download on next reload

### "Tool not responding"

**Fix:**
1. Run `mcp_payload_server_info()` first
2. Check the error message - it will be descriptive
3. Verify all required parameters are provided
4. Check Payload CMS is accessible

---

## 📊 AVAILABLE TOOLS REFERENCE

| Tool | Description | Required Params | Example |
|---|---|---|---|
| **server_info** | Get diagnostics | - | `mcp_payload_server_info()` |
| **articles_list** | List articles | - | `mcp_payload_articles_list({ limit: 10 })` |
| **articles_get** | Get article | `id` | `mcp_payload_articles_get({ id: '123' })` |
| **articles_create** | Create article | `title` | `mcp_payload_articles_create({ title: 'New Post' })` |
| **articles_update** | Update article | `id` | `mcp_payload_articles_update({ id: '123', title: 'Updated' })` |
| **articles_delete** | Delete article | `id` | `mcp_payload_articles_delete({ id: '123' })` |
| **sites_list** | List sites | - | `mcp_payload_sites_list()` |
| **sites_get** | Get site | `id` | `mcp_payload_sites_get({ id: '456' })` |
| **sites_create** | Create site | `name` | `mcp_payload_sites_create({ name: 'My Site' })` |
| **media_list** | List media | - | `mcp_payload_media_list()` |
| **media_upload** | Upload media | `file` | `mcp_payload_media_upload({ file: '/path/to/image.jpg' })` |
| **media_get** | Get media | `id` | `mcp_payload_media_get({ id: '789' })` |
| **search** | Search content | `query` | `mcp_payload_search({ query: 'tutorial' })` |

---

## 🔐 SECURITY NOTES

- **JWT tokens are sensitive** - Never commit them to git
- **Tokens expire** - You'll need to refresh them periodically
- **Server runs locally** - No network exposure
- **All communication** - Encrypted via HTTPS to cms.xencolabs.com

---

## 📈 MONITORING

If users report issues:

1. **Ask for server_info output** first
2. **Check common issues** above
3. **Verify JWT hasn't expired** (most common issue)
4. **Test connectivity** to cms.xencolabs.com

---

## 🎉 READY FOR USE!

The Payload MCP server is now **live and available** for all users with access to the XencoLabs registry!

Users can start managing their Payload CMS content directly from Cursor using natural language and MCP tools.

**Questions?** Check the comprehensive README.md in the package or run `mcp_payload_server_info()` for diagnostics.

---

**Published by:** Cluster Maestro Orchestrator  
**Date:** 2025-10-30  
**Version:** 1.0.0  
**Registry:** https://mcpreg.xencolabs.com  
**Payload CMS:** https://cms.xencolabs.com