npm package: @greenwoodapps/social-mcp
Description: Model Context Protocol server for Greenwood Apps social media management platform
Author: Greenwood Apps
Latest version: 1.1.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# MCP Server for Social Media Management

Model Context Protocol (MCP) server for the Greenwood Apps social media management platform. This server enables AI assistants like Claude to interact with your Greenwood Apps account to create and manage social media posts.

## Quick Start

### Prerequisites

- Node.js >= 18.0.0
- pnpm
- A Greenwood Apps account with an API key

### Get Your API Key

1. Log in to your [Greenwood Apps account](https://app.greenwoodapps.com)
2. Navigate to the Connected Accounts page
3. Generate an API key if you don't have one
4. Copy the API key - you'll need it when configuring your MCP client

### Using with Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "servers": {
    "social": {
      "command": "npx",
      "args": ["@greenwoodapps/social-mcp"],
      "env": {
        "MCP_GREENWOOD_API_KEY": "your_personal_api_key_here"
      }
    }
  }
}
```

**Important:** Replace `your_personal_api_key_here` with the API key from your Greenwood Apps dashboard.

## Available MCP Tools

The MCP server provides the following tools for AI assistants:

### Core Tools

#### `get_user`

Get information about the authenticated user.

- **No parameters required**
- Returns user email and auth ID

#### `create_post`

Create a new social media post across multiple platforms.

- **Parameters:**
  - `content` (required): The text content of the post
  - `accounts` (required): Array of account nicknames to post to
  - `scheduledDateTime` (optional): ISO 8601 datetime string for scheduling
  - `mediaUrls` (optional): Array of media URLs to include
  - `tags` (optional): Array of hashtags and mentions
  - `privacy` (optional): Privacy level (public, unlisted, private)
  - `type` (optional): Post type (image, video, story, text)

#### `get_posts`

Retrieve archived social media posts.

- **Parameters:**
  - `postId` (optional): Specific post ID to retrieve (if not provided, returns all posts)

### Bulk Posting Tools

#### `bulk_post`

Create multiple social media posts in a bulk session for efficient batch posting.

- **Parameters:**
  - `sessionId` (optional): Existing session ID to add posts to
  - `posts` (required): Array of posts to create

#### `get_bulk_sessions`

Retrieve bulk posting sessions and their details.

- **Parameters:**
  - `sessionId` (optional): Specific session ID to retrieve (if not provided, returns all sessions)

## Development

### Local Development Setup

1. **Clone the repository and install dependencies:**

   ```bash
   git clone https://github.com/greenwoodapps/greenwoodapps.git
   cd greenwoodapps
   pnpm install
   ```

2. **Set up local environment:**

   For local development against localhost:

   ```bash
   # Start the local Greenwood Apps server
   pnpm dev --filter=@greenwoodapps/social
   ```

   Add your dev API key to the root `.env` file:

   ```env
   MCP_GREENWOOD_API_KEY=your_dev_api_key_here
   ```

3. **Start development server:**
   ```bash
   pnpm dev --filter=@greenwoodapps/social-mcp
   ```

### Testing with MCP Inspector

```bash
# Install MCP Inspector
npx @modelcontextprotocol/inspector

# Build the MCP server
pnpm build --filter=@greenwoodapps/social-mcp

# Test with inspector
npx @modelcontextprotocol/inspector node apps/social-mcp/dist/index.js
```

Set these environment variables in the inspector:

- `MCP_GREENWOOD_API_KEY=your_api_key_here`
- `NODE_ENV=development` (for localhost) or `production` (for app.greenwoodapps.com)

### Available Scripts

- `pnpm dev` - Start development server with hot reload
- `pnpm build` - Build for production
- `pnpm build:dev` - Build for development (localhost)
- `pnpm build:prod` - Build for production
- `pnpm start` - Start production server
- `pnpm typecheck` - Run TypeScript type checking
- `pnpm lint` - Run ESLint
- `pnpm format` - Check code formatting
- `pnpm clean` - Clean build artifacts

### Project Structure

```
src/
├── index.ts              # Main MCP server entry point
├── services/             # Service layer
│   └── api-client.ts     # Authenticated API client
├── tools/                # MCP tool definitions and handlers
│   ├── index.ts          # Tool registry
│   ├── create-post.ts    # Post creation
│   ├── get-posts.ts      # Post retrieval
│   ├── get-user.ts       # User information
│   ├── bulk-post.ts      # Bulk posting
│   └── get-bulk-sessions.ts # Bulk session retrieval
└── utils/                # Utility functions
    └── logger.ts         # Logging utility
```

## Building and Publishing

### Build for Different Environments

```bash
# Development (localhost:4000)
pnpm build:dev

# Production (app.greenwoodapps.com)
pnpm build:prod
```

### Publishing to NPM

```bash
# Update version
npm version patch  # or minor/major

# Publish to NPM
npm publish
```

The package includes:

- Compiled JavaScript in `dist/`
- README documentation
- Type definitions

### Installation by End Users

Once published:

```bash
# Global installation
npm install -g @greenwoodapps/social-mcp

# Or use with npx (recommended)
npx @greenwoodapps/social-mcp
```

### Claude Desktop Configuration Examples

**Using global installation:**

```json
{
  "servers": {
    "social": {
      "command": "greenwood-social-mcp",
      "env": {
        "MCP_GREENWOOD_API_KEY": "your_personal_api_key_here"
      }
    }
  }
}
```

**Using npx (recommended):**

```json
{
  "servers": {
    "social": {
      "command": "npx",
      "args": ["@greenwoodapps/social-mcp"],
      "env": {
        "MCP_GREENWOOD_API_KEY": "your_personal_api_key_here"
      }
    }
  }
}
```

## Environment Configuration

The MCP server's target API environment is determined at deployment time:

| NODE_ENV               | API URL                             |
| ---------------------- | ----------------------------------- |
| `development`          | `http://localhost:4000/api`         |
| `production` (default) | `https://app.greenwoodapps.com/api` |

For custom deployments, set `DEPLOYMENT_API_URL`:

```bash
DEPLOYMENT_API_URL=https://custom.api.url/api
```

**Note:** Users only configure their API key - they cannot control which environment the MCP server connects to.

## Architecture

### Schema Consolidation Strategy

This MCP server implements a **dual-schema approach** to avoid TypeScript compilation issues while maintaining validation consistency:

#### Problem Context

- **Zod v3 Complex Schemas**: The existing schemas use complex Zod features like `.superRefine()` that can cause "Type instantiation is excessively deep" errors
- **Schema Duplication Risk**: Without careful design, we'd need to redefine validation logic

#### Solution Architecture

1. **MCP Tool Definitions**: Use simplified JSON Schema definitions for the MCP protocol interface
2. **Runtime Validation**: Inline Zod schemas for actual validation
3. **Best of Both Worlds**: Clear MCP interface + robust validation without TypeScript compilation issues

#### Benefits

- ✅ **No TypeScript compilation errors**: Simplified tool definitions avoid deep type instantiation
- ✅ **Consistent validation**: Runtime validation matches the main API
- ✅ **Clear interface**: MCP tool definitions are easy to understand
- ✅ **Future-proof**: Less susceptible to Zod version upgrade issues

## Troubleshooting

### API Key Issues

- Ensure your API key is correctly set in your MCP client configuration
- Verify the API key is valid in the Greenwood Apps dashboard
- Check that you're using your personal API key, not someone else's

### Connection Issues

- Check the MCP server logs for any errors
- Ensure you're running the server with correct environment variables
- Verify network connectivity to the Greenwood Apps API

### Build Issues

```bash
# Check TypeScript errors
pnpm typecheck

# Check for lint issues
pnpm lint

# Clean and rebuild
pnpm clean && pnpm build
```

### Runtime Issues

```bash
# Check if binary is executable
chmod +x dist/index.js

# Verify Node.js version
node --version  # Should be >= 18.0.0

# Test with minimal environment
MCP_GREENWOOD_API_KEY=test_key node dist/index.js
```

### Tool Errors

- Most tool errors will include descriptive messages
- Check that you're providing required parameters for each tool
- Ensure your account has necessary permissions for requested operations

### Common Development Issues

1. **"Missing required environment variable: MCP_GREENWOOD_API_KEY"**
   - Add your dev API key to the root `.env` file
   - Make sure you're using a key from your localhost instance

2. **API Connection Errors**
   - Ensure local server is running at `http://localhost:4000`
   - Verify the API key is valid in your local instance
   - Check network connectivity

3. **MCP Client Connection Issues**
   - Verify the path to `dist/index.js` is absolute and correct
   - Check that the server builds successfully
   - Ensure environment variables are set in the MCP client config

## License

MIT