# LinkedIn Automation MCP Server

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version 1.0.0" />
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" />
  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node >= 18.0.0" />
  <img src="https://img.shields.io/badge/MCP-Protocol-purple.svg" alt="MCP Protocol" />
  <img src="https://img.shields.io/badge/TypeScript-5.3.3-blueviolet.svg" alt="TypeScript 5.3.3" />
  <img src="https://img.shields.io/badge/PRs-welcome-orange.svg" alt="PRs Welcome" />
</p>

## Overview

Enterprise-grade **MCP (Model Context Protocol)** server that enables AI assistants to manage LinkedIn workflows through secure, composable tools. Combines AI-powered content generation, lead management, profile optimization, message outreach, analytics, scheduling, and industry research into a single extensible platform.

## Features

| Category | Tools |
|---|---|
| **Content Generation** | Generate posts, rewrite content, hooks, CTAs, carousels, articles, polls, translations, hashtags, repurpose content across 10 content types and 10 tones |
| **Profile Optimization** | Full profile analysis, headline/About generation, SEO scoring, skill recommendations, banner suggestions |
| **Lead Management** | Find prospects by industry/company/location/title, score leads, save/export (CSV/JSON), paginated retrieval |
| **Message Outreach** | Connection requests, follow-ups, thank-you, meeting requests, sales outreach, recruitment, networking messages |
| **Engagement Strategy** | Post recommendations, comment generation, engagement strategies, conversation starters, industry trend analysis |
| **Analytics & Insights** | Performance metrics, post analysis, top content, growth trends, AI recommendations, best posting times |
| **Content Calendar** | Create calendars, schedule posts, publish, save drafts, recurring posts, timezone-aware scheduling |
| **Industry Research** | Trend research, content ideas, competitor analysis, trending hashtags |
| **Multi-AI Provider** | OpenAI GPT-4, Anthropic Claude 3, Google Gemini — switchable per request |
| **Vector Memory** | Qdrant-based semantic storage for writing style, brand voice, company knowledge, successful posts, RAG |

## Quick Start

```bash
git clone <repo>
cd linkedin-automation-mcp
npm install
cp .env.example .env
# Edit .env with your API keys
npm run dev
```

## Architecture

The server follows **Clean Architecture** with strict separation of concerns across six layers:

```
┌─────────────────────────────────────────────────────────────────────┐
│                        AI Client (Claude, Cursor, etc.)              │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ MCP Protocol (stdio)
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         MCP Server Layer                             │
│              @modelcontextprotocol/sdk  StdioServerTransport          │
│              Tool registry, request routing, schema validation        │
├──────────────────────────────────────────────────────────────────────┤
│                            Tools Layer                                │
│   Content   Profile   Lead   Message   Engagement   Analytics        │
│   Calendar  Research                                                  │
├──────────────────────────────────────────────────────────────────────┤
│                           Services Layer                              │
│   Business logic, orchestration, validation, AI prompt building       │
├──────────────────────────────────────────────────────────────────────┤
│                         Provider Layer                                │
│   OpenAIProvider   AnthropicProvider   GeminiProvider   LinkedIn      │
├──────────────────────────────────────────────────────────────────────┤
│                           Data Layer                                  │
│   PostgreSQL (Drizzle ORM)    Redis    Qdrant Vector DB              │
└──────────────────────────────────────────────────────────────────────┘
```

## Tech Stack

| Category | Technology |
|---|---|
| **Runtime** | Node.js 18+, TypeScript 5.3 |
| **MCP** | `@modelcontextprotocol/sdk` v0.5 |
| **HTTP** | Express 4.18, Helmet, CORS, Compression |
| **Validation** | Zod 3.22 |
| **Database** | PostgreSQL 16 (Drizzle ORM 0.29) |
| **Vector DB** | Qdrant 1.8 |
| **Cache** | Redis 7 (ioredis) |
| **AI** | OpenAI, Anthropic, Google Gemini |
| **Auth** | JWT, bcryptjs, LinkedIn OAuth |
| **Logging** | Winston 3.11 |
| **Scheduling** | node-cron 3.0 |
| **Testing** | Jest 29, Supertest, Nock |
| **Linting** | ESLint 8, Prettier 3 |
| **CI** | Husky 8, lint-staged |

## Project Structure

```
linkedin-automation-mcp/
├── src/
│   ├── index.ts                 # Server entry point
│   ├── config/
│   │   └── index.ts             # Environment configuration
│   ├── types/
│   │   └── index.ts             # TypeScript enums, interfaces, types
│   ├── database/
│   │   ├── schema.ts            # Drizzle ORM schema (14 tables)
│   │   ├── connection.ts        # PostgreSQL connection pool
│   │   ├── migrations/          # Database migrations
│   │   ├── index.ts             # Database exports
│   │   └── seed.ts              # Seed data
│   ├── providers/
│   │   ├── ai-provider.ts       # AI provider interface
│   │   ├── openai-provider.ts   # OpenAI GPT-4 implementation
│   │   ├── anthropic-provider.ts # Anthropic Claude 3 implementation
│   │   ├── gemini-provider.ts   # Google Gemini implementation
│   │   └── linkedin-provider.ts # LinkedIn API client
│   ├── services/
│   │   ├── content-service.ts   # Content generation business logic
│   │   ├── profile-service.ts   # Profile optimization logic
│   │   ├── lead-service.ts      # Lead management logic
│   │   ├── message-service.ts   # Message generation logic
│   │   ├── engagement-service.ts # Engagement strategy logic
│   │   ├── analytics-service.ts # Analytics business logic
│   │   ├── research-service.ts  # Research & trends logic
│   │   └── scheduler-service.ts # Cron-based scheduling
│   ├── tools/
│   │   ├── content-tools.ts     # 10 content MCP tools
│   │   ├── profile-tools.ts     # 6 profile MCP tools
│   │   ├── lead-tools.ts        # 5 lead MCP tools
│   │   ├── message-tools.ts     # 7 message MCP tools
│   │   ├── engagement-tools.ts  # 5 engagement MCP tools
│   │   ├── analytics-tools.ts   # 6 analytics MCP tools
│   │   ├── calendar-tools.ts    # 7 calendar MCP tools
│   │   ├── research-tools.ts    # 4 research MCP tools
│   │   ├── utils.ts             # Tool utility functions
│   │   └── index.ts             # Tool registry
│   ├── agents/
│   │   └── index.ts             # AI agent orchestrator
│   ├── memory/
│   │   └── index.ts             # Qdrant vector memory
│   ├── prompts/
│   │   └── index.ts             # AI prompt templates
│   ├── middleware/
│   │   ├── auth.ts              # JWT authentication
│   │   ├── error-handler.ts     # Centralized error handling
│   │   ├── rate-limit.ts        # Rate limiting
│   │   ├── validation.ts        # Zod validation middleware
│   │   ├── async-handler.ts     # Async route handler
│   │   └── log-request.ts       # Request logging
│   ├── routes/
│   │   ├── auth-routes.ts       # Authentication endpoints
│   │   ├── post-routes.ts       # Post management endpoints
│   │   ├── profile-routes.ts    # Profile optimization endpoints
│   │   ├── lead-routes.ts       # Lead management endpoints
│   │   ├── message-routes.ts    # Message endpoints
│   │   ├── analytics-routes.ts  # Analytics endpoints
│   │   ├── calendar-routes.ts   # Calendar endpoints
│   │   └── index.ts             # Route aggregator
│   └── utils/
│       ├── logger.ts            # Winston logger
│       ├── cache.ts             # In-memory cache
│       ├── encryption.ts        # AES-256-GCM encryption
│       ├── helpers.ts           # Utility helpers
│       ├── rate-limiter.ts      # Rate limiter helpers
│       ├── retry.ts             # Retry logic
│       └── validators.ts        # Zod validation schemas
├── dashboard/                   # Admin dashboard (Vite + React)
├── scripts/                     # Utility scripts
├── __tests__/                   # Test files
├── docker-compose.yml           # Docker Compose (app, postgres, qdrant, redis)
├── Dockerfile                   # Multi-stage build
├── .env.example                 # Environment variables template
├── tsconfig.json                # TypeScript configuration
├── jest.config.js               # Unit test configuration
├── jest.e2e.config.js           # E2E test configuration
└── package.json
```

## MCP Tools

The server exposes **50 MCP tools** across 8 categories:

### Content Tools (10)

| Tool | Description | Key Inputs |
|---|---|---|
| `generate_post` | Generate a LinkedIn post with full customization | type, tone, audience, industry, topic |
| `rewrite_post` | Rewrite/improve existing content | content, tone, readabilityLevel |
| `generate_hashtags` | Generate relevant LinkedIn hashtags | topic, industry, count, trending |
| `generate_hook` | Generate an engaging post hook | topic, tone |
| `generate_cta` | Generate a compelling call-to-action | topic, goal |
| `translate_post` | Translate post preserving tone/hashtags | content, targetLanguage |
| `generate_carousel` | Generate carousel outline with slides | topic, slides |
| `generate_article` | Generate long-form LinkedIn article | title, topic, wordCount |
| `generate_poll` | Generate poll with question and options | topic, options |
| `repurpose_content` | Repurpose blog/video/podcast to LinkedIn post | sourceContent, sourceType |

### Profile Tools (6)

| Tool | Description | Key Inputs |
|---|---|---|
| `optimize_profile` | Full profile optimization analysis | headline, about, skills, industry, targetRole |
| `generate_headline` | Generate optimized headline (<220 chars) | current, targetRole, industry, keywords |
| `generate_about` | Generate/optimize About section | current, targetRole, industry, keyPoints |
| `analyze_profile_seo` | SEO effectiveness analysis | headline, about, skills, experience |
| `recommend_skills` | Skill recommendations for target role | currentSkills, targetRole, industry |
| `suggest_banner` | LinkedIn banner design suggestions | industry, branding |

### Lead Tools (5)

| Tool | Description | Key Inputs |
|---|---|---|
| `find_leads` | Search for prospects by criteria | industry, company, location, jobTitle, keywords |
| `score_leads` | Score/qualify leads by fit and intent | prospectIds |
| `save_leads` | Save leads to database | leads array |
| `get_leads` | Retrieve saved leads with filters | userId, status, industry, page, limit |
| `export_leads` | Export leads as CSV or JSON | userId, format |

### Message Tools (7)

| Tool | Description | Key Inputs |
|---|---|---|
| `generate_connection_request` | Personalized connection request (<300 chars) | prospectName, senderName, context |
| `generate_followup` | Follow-up referencing previous conversation | previousMessage, context |
| `generate_thank_you` | Thank-you message for relationships | context |
| `generate_meeting_request` | Meeting invitation | meetingPurpose |
| `generate_sales_outreach` | Value-first sales outreach | product, valueProposition |
| `generate_recruitment_message` | Recruitment/InMail for talent | role, company |
| `generate_networking_message` | Networking message based on shared interests | commonInterest |

### Engagement Tools (5)

| Tool | Description | Key Inputs |
|---|---|---|
| `recommend_posts` | Recommend posts to engage with | userId, industry, interests |
| `generate_comment` | Generate value-adding comment | postContent, tone |
| `get_engagement_strategy` | Like/follow engagement strategy | industry, goals |
| `get_conversation_starters` | Generate conversation starters | topic, industry |
| `analyze_industry_trends` | Analyze trends and content opportunities | industry |

### Analytics Tools (6)

| Tool | Description | Key Inputs |
|---|---|---|
| `get_analytics` | Get analytics for account/date range | accountId, startDate, endDate, metrics |
| `analyze_post` | Analyze individual post performance | postId |
| `get_top_content` | Get top-performing content | accountId, limit |
| `get_growth_trends` | Follower/engagement growth trends | accountId, period |
| `get_recommendations` | AI-powered actionable recommendations | analyticsId |
| `recommend_post_time` | Best times to post for engagement | accountId |

### Calendar Tools (7)

| Tool | Description | Key Inputs |
|---|---|---|
| `create_content_calendar` | Create content calendar with slots | name, frequency, slots, startDate, endDate |
| `schedule_post` | Schedule post for future publishing | postId, scheduledAt, timezone |
| `publish_post` | Publish post immediately | postId, accountId |
| `save_draft` | Save post as draft | content, type, tone |
| `get_calendar` | Get content calendar with scheduled posts | userId, startDate, endDate |
| `get_drafts` | Get saved drafts with pagination | userId, page, limit |
| `cancel_scheduled_post` | Cancel scheduled post | postId |

### Research Tools (4)

| Tool | Description | Key Inputs |
|---|---|---|
| `research_trends` | Research industry trends and content strategy | industry, topics, contentTypes |
| `get_content_ideas` | Generate content ideas for industry | industry, topics, contentTypes |
| `analyze_competitors` | Analyze competitor LinkedIn strategies | industry, topics |
| `get_trending_hashtags` | Get trending hashtags for industry | industry, topics |

## Docker Setup

```bash
# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f app

# Stop all services
docker-compose down

# Rebuild after changes
docker-compose build app
```

The Docker Compose setup includes:
- **app** — Node.js MCP server on port 3001
- **dashboard** — Admin dashboard on port 5173
- **postgres** — PostgreSQL 16 on port 5432
- **qdrant** — Vector database on port 6333
- **redis** — Cache on port 6379

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `PORT` | HTTP server port | `3001` |
| `NODE_ENV` | Environment (development/production) | `development` |
| `API_PREFIX` | REST API base path | `/api/v1` |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://...` |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `QDRANT_URL` | Qdrant vector DB URL | `http://localhost:6333` |
| `OPENAI_API_KEY` | OpenAI API key | — |
| `ANTHROPIC_API_KEY` | Anthropic API key | — |
| `GEMINI_API_KEY` | Google Gemini API key | — |
| `DEFAULT_AI_PROVIDER` | Default AI provider | `openai` |
| `LINKEDIN_CLIENT_ID` | LinkedIn OAuth client ID | — |
| `LINKEDIN_CLIENT_SECRET` | LinkedIn OAuth client secret | — |
| `JWT_SECRET` | JWT signing secret | — |
| `JWT_EXPIRES_IN` | JWT token expiry | `7d` |
| `JWT_REFRESH_SECRET` | Refresh token secret | — |
| `ENCRYPTION_KEY` | AES-256 encryption key (32 chars) | — |
| `RATE_LIMIT_WINDOW_MS` | Rate limit window | `900000` (15 min) |
| `RATE_LIMIT_MAX_REQUESTS` | Max requests per window | `100` |
| `CORS_ORIGIN` | Allowed CORS origins | `http://localhost:5173` |
| `LOG_LEVEL` | Logging level | `info` |
| `SCHEDULER_CRON` | Scheduler cron expression | `0 */6 * * *` |
| `MAX_SCHEDULED_POSTS_PER_DAY` | Max daily scheduled posts | `5` |
| `CACHE_TTL_SECONDS` | Cache TTL | `300` |
| `FEATURE_AI_WRITER` | Enable AI writer feature | `true` |
| `FEATURE_CALENDAR` | Enable calendar feature | `true` |
| `FEATURE_LEAD_GEN` | Enable lead generation | `true` |
| `FEATURE_ANALYTICS` | Enable analytics | `true` |
| `FEATURE_OUTREACH` | Enable outreach | `true` |

## API Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/api/v1/auth/register` | Register new user |
| `POST` | `/api/v1/auth/login` | Login |
| `POST` | `/api/v1/auth/refresh` | Refresh access token |
| `POST` | `/api/v1/auth/logout` | Logout |
| `GET` | `/api/v1/auth/me` | Get current user |
| `GET` | `/api/v1/auth/linkedin/authorize` | LinkedIn OAuth authorize |
| `GET` | `/api/v1/auth/linkedin/callback` | LinkedIn OAuth callback |
| `POST` | `/api/v1/posts/generate` | Generate post |
| `POST` | `/api/v1/posts/rewrite` | Rewrite post |
| `POST` | `/api/v1/posts/schedule` | Schedule post |
| `POST` | `/api/v1/posts/publish` | Publish post |
| `POST` | `/api/v1/posts/draft` | Save draft |
| `GET` | `/api/v1/posts` | List posts |
| `GET` | `/api/v1/posts/drafts` | List drafts |
| `GET` | `/api/v1/posts/:id` | Get post |
| `DELETE` | `/api/v1/posts/:id` | Delete post |
| `POST` | `/api/v1/profile/optimize` | Optimize profile |
| `POST` | `/api/v1/profile/headline` | Generate headline |
| `POST` | `/api/v1/profile/about` | Generate About section |
| `POST` | `/api/v1/profile/seo` | SEO analysis |
| `POST` | `/api/v1/profile/skills` | Recommend skills |
| `POST` | `/api/v1/leads/search` | Search leads |
| `POST` | `/api/v1/leads/score` | Score leads |
| `POST` | `/api/v1/leads/save` | Save leads |
| `GET` | `/api/v1/leads` | List leads |
| `GET` | `/api/v1/leads/export` | Export leads |
| `DELETE` | `/api/v1/leads/:id` | Delete lead |
| `POST` | `/api/v1/messages/generate` | Generate message |
| `POST` | `/api/v1/messages/connection-request` | Generate connection request |
| `POST` | `/api/v1/messages/followup` | Generate follow-up |
| `POST` | `/api/v1/messages/send` | Send message |
| `GET` | `/api/v1/messages` | List messages |
| `GET` | `/api/v1/analytics` | Get analytics |
| `GET` | `/api/v1/analytics/posts/:id` | Analyze post |
| `GET` | `/api/v1/analytics/top` | Top content |
| `GET` | `/api/v1/analytics/trends` | Growth trends |
| `POST` | `/api/v1/analytics/recommendations` | Get recommendations |
| `POST` | `/api/v1/analytics/best-time` | Best posting time |
| `POST` | `/api/v1/calendar` | Create calendar |
| `GET` | `/api/v1/calendar` | List calendars |
| `POST` | `/api/v1/calendar/schedule` | Schedule post |
| `POST` | `/api/v1/calendar/publish` | Publish post |
| `POST` | `/api/v1/calendar/draft` | Save draft |
| `GET` | `/api/v1/calendar/drafts` | List drafts |
| `DELETE` | `/api/v1/calendar/scheduled/:id` | Cancel scheduled post |
| `GET` | `/health` | Health check |

## Dashboard

The admin dashboard is a Vite + React application in the `dashboard/` directory.

```bash
# Start dashboard in development mode
npm run dashboard:dev

# Build dashboard for production
npm run dashboard:build
```

## Testing

```bash
# Run unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run end-to-end tests
npm run test:e2e
```

## Deployment

### Production Build

```bash
npm run build
npm start
```

### Docker Production

```bash
docker-compose -f docker-compose.yml up -d
```

### Environment Configuration

1. Copy `.env.example` to `.env`
2. Set `NODE_ENV=production`
3. Configure strong `JWT_SECRET` and `ENCRYPTION_KEY`
4. Set database credentials
5. Configure AI provider API keys
6. Set LinkedIn OAuth credentials

### CI/CD Pipeline

```yaml
# Suggested pipeline stages
- lint:     npm run lint
- typecheck: npm run typecheck
- test:     npm run test:coverage
- build:    npm run build
- docker:   docker-compose build
- deploy:   docker-compose up -d
```

## License

MIT License — see [LICENSE](LICENSE)