npm package: @simplystack-org/mcp
Description: Model Context Protocol server for SimplyStack
Author: SimplyStack
Latest version: 1.3.1

# SimplyStack MCP Server

> ✅ **PRODUCTION READY** (v1.1.1)
> 
> **Current Status:**
> - ✅ Dual transport system (local + hosted) working
> - ✅ Real API integration complete
> - ✅ Authentication system implemented
> - ✅ Cloudflare Workers deployed at `mcp.simplystack.dev`
> - ✅ NPM package published and stable
> 
> **Known Issues:** Some quality improvements pending (see [`PROJECT-STATUS.md`](PROJECT-STATUS.md) for details)

**Model Context Protocol server for SimplyStack** - Bring SimplyStack's powerful backend services directly to your AI assistants like Cursor, Claude, and Windsurf.

[![npm version](https://img.shields.io/npm/v/@simplystack-org/mcp.svg)](https://www.npmjs.com/package/@simplystack-org/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What is This?

This MCP server allows AI assistants to interact with your SimplyStack projects, enabling:

- 🚀 **Project Management** - Create and manage SimplyStack projects
- 📝 **Content Management** - Create and manage blog posts
- 🔍 **Logging** - Create and search application logs  
- 📁 **File Storage** - Manage and retrieve files
- 📧 **Email Management** - Send emails and manage configurations
- 👥 **Lead Management** - Capture and manage leads
- 📊 **Analytics** - Get insights and statistics

## Quick Start

### Step 1: Create Account & Get Personal Token

1. **Create a SimplyStack account** (if you don't have one):
   - Go to [SimplyStack](https://www.simplystack.dev)
   - Sign up for an account

2. **Generate your Personal Access Token**:
   - Go to [Account Settings](https://www.simplystack.dev/accounts/settings)
   - Click "Generate New Token"
   - Copy the token (you'll need it for configuration)

> 💡 **Personal Access Token**: This allows you to create and list projects from your AI assistant.

### Step 2: Configure Your AI Tool

Choose your preferred AI tool and add the MCP server configuration:

#### **Cursor**

Go to Settings → Features → MCP Servers and add:

```json
{
  "name": "simplystack",
  "command": "npx",
  "args": [
    "-y",
    "@simplystack-org/mcp@latest",
    "--personal-token",
    "your_personal_token_here"
  ]
}
```

#### **Windsurf**

Go to Cascade → Configure and add:

```json
{
  "mcpServers": {
    "simplystack": {
      "command": "npx",
      "args": [
        "-y",
        "@simplystack-org/mcp@latest",
        "--personal-token",
        "your_personal_token_here"
      ]
    }
  }
}
```

#### **Claude Desktop**

Edit your MCP configuration file:

```json
{
  "mcpServers": {
    "simplystack": {
      "command": "npx",
      "args": [
        "-y",
        "@simplystack-org/mcp@latest",
        "--personal-token",
        "your_personal_token_here"
      ]
    }
  }
}
```

### Step 3: Restart Your AI Tool

Restart your AI assistant to load the SimplyStack MCP server.

### Step 4: Test the Connection

First, verify the MCP server is working:

```
You: "Call the test_connection tool"
AI: Should return "hello world of cli" (confirming the connection works)
```

### Step 5: Start Using!

Try asking your AI assistant:
- "Create a new SimplyStack project called 'My Blog'"
- "List all my SimplyStack projects"

> 📝 **Note**: Advanced features (blog posts, emails, storage) are currently being refactored and may not work reliably in this development version.

## Authentication & Project Setup

SimplyStack uses a two-level authentication system:

### 1. **Personal Access Token** (Project Management)
- **Purpose**: Create and list projects
- **Where to get**: [Account Settings](https://www.simplystack.dev/accounts/settings)
- **Used for**: Project creation, listing all projects

### 2. **Project Token** (Project Operations)
- **Purpose**: Manage content within a specific project (blogs, emails, storage, etc.)
- **Where to get**: SimplyStack Dashboard → Your Project → Settings → API Keys
- **Used for**: Blog posts, email sending, file storage, lead management

### Setting Up Project Tokens

After creating or selecting a project, you'll need to configure its token:

1. **Get the Project Token**:
   - Go to [SimplyStack Dashboard](https://www.simplystack.dev/dashboard)
   - Navigate to your project
   - Go to Settings → API Keys
   - Create a new API key

2. **Configure in Your AI Assistant**:
   - Tell your assistant: *"Set the project secret for project [project-id] to [your-project-token]"*

## Usage Examples

### Project Setup
```
You: "Create a new project called 'AI Newsletter' for my newsletter service"
AI: ✅ Creates project and sets it as active

You: "What's my current active project?"
AI: Shows current project details and available actions
```

### Content Management
```
You: "Create a blog post titled 'Getting Started with AI' with content about AI basics"
AI: ✅ Creates blog post in active project

You: "List all my blog posts"
AI: Shows all blog posts with titles, status, and dates
```

### Email & Lead Management
```
You: "Set up email configuration with sender name 'AI Newsletter'"
AI: ✅ Configures email system

You: "Send a welcome email to new.subscriber@example.com"
AI: ✅ Sends email and tracks in system

You: "Add john@example.com as a new lead from our landing page"
AI: ✅ Creates lead and optionally sends welcome email
```

## Development Roadmap

### Phase 1: Transport Foundation ✅ COMPLETE
- [x] Transport abstraction layer
- [x] HTTP and stdio transport support
- [x] JSON-RPC 2.0 compliance
- [x] Basic tool functionality
- [x] Test connection tool

### Phase 2: Authentication & Project Resolution ✅ COMPLETE
- [x] Enhanced authentication flows
- [x] Project name resolution
- [x] Public/private tool access
- [x] Cloudflare Workers integration

### Phase 3: Production Deployment ✅ COMPLETE
- [x] Cloudflare Workers hosting
- [x] Production API endpoints
- [x] Performance optimization
- [x] Comprehensive testing

### Phase 4: Advanced Features ✅ MOSTLY COMPLETE
- [x] Full blog management
- [x] Email system integration
- [x] File storage operations
- [x] Lead management
- [x] Logging and monitoring
- [ ] Shopping tools (planned)

### Phase 5: Quality Improvements 🚧 IN PROGRESS
- [ ] Enhanced error messaging consistency
- [ ] Blog SEO validation and optimization
- [ ] Email configuration data persistence fixes
- [ ] Content analysis features

> 📊 **Current Status**: Production ready with known quality improvement areas.  
> See [`PROJECT-STATUS.md`](PROJECT-STATUS.md) for detailed implementation status and known issues.

## Available Tools

### Core Tools (Working)
- `test_connection` - Test transport connectivity
- `create_simplystack_project` - Create new projects  
- `list_user_projects` - List accessible projects

### Project Management
- `create_simplystack_project` - Create new projects
- `list_user_projects` - List all accessible projects  
- `set_active_project` - Switch active project
- `get_active_project` - Get current project details
- `set_project_secret` - Configure project API keys
- `get_project_context` - View all projects and status

### Content Management
- `create_blog_post` - Create blog posts
- `list_blog_posts` - List blog posts with filters
- `get_blog_post` - Get specific blog post
- `update_blog_post` - Update blog post content
- `delete_blog_post` - Delete blog posts

### Storage Management  
- `get_storage_assets` - List uploaded files
- `get_storage_asset` - Get file details and URLs
- `get_file_url` - Generate file URLs with transformations
- `delete_storage_asset` - Delete files

### Logging
- `create_log_entry` - Create application logs
- `search_logs` - Search and filter logs
- `get_log_entry` - Get specific log entry

### Email System
- `setup_email_configuration` - Configure email settings
- `get_email_configuration` - Get current email config
- `update_email_configuration` - Update email settings
- `send_email` - Send emails with templates
- `get_emails` - List sent emails
- `get_email` - Get specific email details

### Lead Management
- `create_lead` - Add new leads with welcome emails
- `get_leads` - List leads with filters
- `get_lead` - Get specific lead details  
- `update_lead` - Update lead information

### Analytics
- `get_email_stats` - Get email and lead statistics

## CLI Options

```bash
npx @simplystack-org/mcp [options]

Options:
  -t, --personal-token <token>  SimplyStack personal access token (required)
  -u, --base-url <url>          API base URL (default: production)
  --test                        Run in test mode (validates and exits)
  --debug                       Enable debug logging
  -h, --help                    Display help
```

## Configuration Storage

Your projects and settings are automatically stored in:
- **Location**: `~/.simplystack/projects.json`
- **Auto-created**: Yes, on first run
- **Contains**: Project contexts, active project, and project tokens

## Error Handling

The MCP server provides helpful error messages and solutions:

```
❌ Cannot perform create_blog_post: No active project set.

🔧 SOLUTION:
1. Create a new project: use create_simplystack_project
2. Or select existing project: use set_active_project with project ID

Use get_project_context to see available projects.
```

## Troubleshooting

### "Personal token required"
- **Solution**: Get your token from [Account Settings](https://www.simplystack.dev/accounts/settings)
- Make sure it's properly configured in your AI tool's MCP configuration

### "No active project set"
- **Solution**: Create a new project or select an existing one
- Try: *"Create a SimplyStack project called 'My Project'"*
- Or: *"Set active project to [project-id]"*

### "Project has no secret configured" 
- **Solution**: Get your project token and configure it
- Get project token from: Dashboard → Your Project → Settings → API Keys
- Configure: *"Set the project secret for [project-id] to [your-project-token]"*

### "API connectivity issues"
- **Check**: Verify your tokens are valid and not expired
- **Check**: Ensure you're connected to the internet
- **Test**: Try the test command: `npx @simplystack-org/mcp --personal-token "your-token" --test`

### AI Tool Not Detecting MCP Server
- **Restart** your AI tool after adding the configuration
- **Check** that the configuration syntax is correct for your specific tool
- **Verify** the green indicator shows the server is connected

## Support

- 📧 **Email**: support@simplystack.dev
- 🐛 **Issues**: [GitHub Issues](https://github.com/simplystack-org/mcp/issues)
- 📖 **Documentation**: [SimplyStack Docs](https://docs.simplystack.dev)
- 💬 **Community**: [SimplyStack Discord](https://discord.gg/simplystack)

---

Built with ❤️ by the [SimplyStack](https://www.simplystack.dev) team