pipeline-mcp 1.0.0

package/README.md

@@ -0,0 +1,278 @@
+# Pipeline MCP Server
+
+MCP (Model Context Protocol) server for [Pipeline](https://pipeline.help) - AI-powered LinkedIn outreach automation.
+
+Control your LinkedIn campaigns, manage prospects, track buying signals, monitor workflow performance, and view conversations directly from Claude, ChatGPT, Cursor, or any MCP-compatible AI assistant.
+
+## Features
+
+- **40 Tools** across 7 categories
+- **Campaign Management** - Create, start, pause, resume, clone campaigns
+- **Prospect Management** - Add, remove, filter prospects by ICP score
+- **Analytics** - Campaign metrics, reply rates, ICP distribution, top performers
+- **LinkedIn Accounts** - Monitor daily usage, check InMail balance
+- **Workflow Monitoring** - Track execution progress, pending and failed actions
+- **Conversations** - View replies, search conversations, get message threads
+- **Signal Tracking** - Monitor buying signals, create trackers, act on signals
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g pipeline-mcp
+```
+
+Or use with npx:
+
+```bash
+npx pipeline-mcp --api-key YOUR_API_KEY
+```
+
+### Claude Code Configuration
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "pipeline": {
+      "command": "npx",
+      "args": ["-y", "pipeline-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pipeline": {
+      "command": "npx",
+      "args": ["-y", "pipeline-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+
+### Cursor IDE Configuration
+
+Add to your Cursor settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "pipeline": {
+        "command": "npx",
+        "args": ["-y", "pipeline-mcp", "--api-key", "YOUR_API_KEY"]
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once connected, you can ask your AI assistant:
+
+- "How are my campaigns doing?"
+- "Show me prospects with ICP score above 80"
+- "Who replied to my campaigns this week?"
+- "Add linkedin.com/in/johndoe to my VP Sales campaign"
+- "Which campaign has the best reply rate?"
+- "How many InMails do I have left?"
+- "Show me failed actions in my campaign"
+- "What buying signals have been detected?"
+- "Compare my active campaigns side by side"
+- "Clone my best campaign and rename it"
+
+## Available Tools
+
+### Campaign Management (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list-campaigns` | List all campaigns with optional status filter |
+| `get-campaign` | Get detailed campaign information |
+| `create-campaign` | Create a new campaign |
+| `start-campaign` | Start campaign execution |
+| `pause-campaign` | Pause a running campaign |
+| `resume-campaign` | Resume a paused campaign |
+| `clone-campaign` | Clone an existing campaign |
+
+### Prospect Management (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list-prospects` | List prospects with ICP score filtering |
+| `get-prospect` | Get prospect details |
+| `add-prospect` | Add a single prospect |
+| `add-prospects-bulk` | Add up to 1000 prospects at once |
+| `remove-prospect` | Remove a prospect |
+| `get-prospect-stats` | Get pipeline breakdown by status |
+| `list-prospect-lists` | List all prospect lists |
+
+### Analytics (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get-campaign-analytics` | Get campaign performance metrics |
+| `get-account-analytics` | Get account-wide analytics |
+| `get-reply-analytics` | Get reply rates and sentiment breakdown |
+| `get-icp-distribution` | Get ICP score distribution across prospects |
+| `compare-campaigns` | Compare multiple campaigns side by side |
+| `get-top-performers` | Get best performing campaigns by metric |
+
+### LinkedIn Accounts (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list-linkedin-accounts` | List connected LinkedIn accounts |
+| `get-linkedin-account` | Get account details and limits |
+| `get-daily-usage` | Get today's usage vs daily limits |
+| `get-inmail-balance` | Check InMail credits remaining |
+
+### Workflow Monitoring (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get-workflow-status` | Get execution status and progress for a campaign |
+| `get-pending-actions` | List pending workflow actions |
+| `get-failed-actions` | List failed actions with error details |
+| `get-execution-progress` | Get progress percentage and ETA |
+
+### Conversations (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list-conversations` | List conversations, filter by campaign or reply status |
+| `get-conversation` | Get full message thread for a conversation |
+| `get-recent-replies` | Get most recent replies across all campaigns |
+| `search-conversations` | Search conversations by keyword |
+
+### Signal Tracking (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list-signals` | List detected buying signals |
+| `list-signal-trackers` | List configured signal trackers |
+| `create-signal-tracker` | Create a new keyword tracker |
+| `pause-signal-tracker` | Pause a tracker |
+| `resume-signal-tracker` | Resume a tracker |
+| `add-signal-to-campaign` | Add signal prospect to a campaign |
+| `create-prospect-from-signal` | Create a prospect from a detected signal |
+| `trigger-signal-poll` | Manually trigger signal polling |
+
+## HTTP Server Mode
+
+For integrations with n8n, Clay, or custom applications:
+
+```bash
+pipeline-mcp --http --port 3000
+```
+
+Authentication via headers:
+- `X-API-KEY: your_api_key`
+- `Authorization: Bearer your_api_key`
+
+### JSON-RPC Examples
+
+```bash
+# List available tools
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -H "X-API-KEY: your_api_key" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
+
+# Call a tool
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -H "X-API-KEY: your_api_key" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "list-campaigns",
+      "arguments": { "status": "active" }
+    }
+  }'
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PIPELINE_API_KEY` | Your Pipeline API key |
+| `PIPELINE_BASE_URL` | Custom API URL (default: `https://pipeline.help/api`) |
+
+## CLI Options
+
+```
+Options:
+  --api-key <key>     Your Pipeline API key
+  --base-url <url>    Custom API base URL
+  --port <number>     Port for HTTP server (default: 3000)
+  --http              Run in HTTP server mode
+  --stdio             Run in stdio mode (default)
+  --version, -v       Show version
+  --help, -h          Show help
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/mattvinall/pipeline-mcp.git
+cd pipeline-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run in development (watch mode)
+npm run dev
+```
+
+## Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+EXPOSE 3000
+CMD ["node", "dist/index.js", "--http"]
+```
+
+```bash
+docker build -t pipeline-mcp .
+docker run -p 3000:3000 -e PIPELINE_API_KEY=your_key pipeline-mcp
+```
+
+## Getting Your API Key
+
+1. Log in to [Pipeline](https://pipeline.help)
+2. Go to **Settings > API Keys**
+3. Create a new API key
+4. Copy the key and use it with this MCP server
+
+## Support
+
+- [GitHub Issues](https://github.com/mattvinall/pipeline-mcp/issues)
+
+## License
+
+MIT

package/TEST_PLAN.md

@@ -0,0 +1,323 @@
+# Pipeline MCP Server - End-to-End Test Plan
+
+**Test Date:** 2026-02-18  
+**Tester:** Hydra (Automated + Manual)  
+**Status:** In Progress
+
+---
+
+## Pre-Flight Checks
+
+### Build Verification
+- [x] TypeScript compilation successful
+- [x] No type errors
+- [x] All imports resolve correctly
+- [x] Dist output generated
+
+### Architecture Validation
+- [x] 10 tool categories registered
+- [x] 65 total tools defined
+- [x] Both stdio and HTTP transports implemented
+- [x] Error handling in place
+- [x] Auth flow implemented (Bearer token + X-API-KEY header)
+
+---
+
+## Test Categories
+
+### 1. Transport Modes
+
+#### Stdio Mode
+```bash
+# Test with API key
+npm run build
+node dist/index.js --api-key TEST_KEY
+
+# Expected: Server starts without error, waits for stdin
+```
+
+#### HTTP Mode
+```bash
+# Start HTTP server
+node dist/index.js --http --port 3000
+
+# Expected: Server listens on port 3000
+```
+
+### 2. Authentication Flow
+
+#### Valid API Key
+- [ ] Stdio mode with valid key connects
+- [ ] HTTP mode with X-API-KEY header works
+- [ ] HTTP mode with Authorization: Bearer works
+
+#### Invalid API Key
+- [ ] Stdio mode shows error and exits
+- [ ] HTTP mode returns 401
+- [ ] Error message is descriptive
+
+#### Missing API Key
+- [ ] Stdio mode requires key (exits with error)
+- [ ] HTTP mode returns 401
+
+### 3. Tool Categories (65 Tools Total)
+
+#### Campaign Management (7 tools)
+- [ ] `list-campaigns` - Returns paginated campaigns
+- [ ] `get-campaign` - Returns campaign details
+- [ ] `create-campaign` - Creates new campaign
+- [ ] `start-campaign` - Starts campaign
+- [ ] `pause-campaign` - Pauses campaign
+- [ ] `resume-campaign` - Resumes campaign
+- [ ] `clone-campaign` - Clones campaign
+
+#### Prospect Management (7 tools)
+- [ ] `list-prospects` - Returns prospects with filtering
+- [ ] `get-prospect` - Returns prospect details
+- [ ] `add-prospect` - Adds single prospect
+- [ ] `add-prospects-bulk` - Adds up to 1000 prospects
+- [ ] `remove-prospect` - Removes prospect from campaign
+- [ ] `get-prospect-stats` - Returns pipeline breakdown
+- [ ] `list-prospect-lists` - Returns all lists
+
+#### Analytics (6 tools)
+- [ ] `get-campaign-analytics` - Returns metrics
+- [ ] `get-account-analytics` - Returns workspace analytics
+- [ ] `get-reply-analytics` - Returns reply rates
+- [ ] `get-icp-distribution` - Returns score distribution
+- [ ] `compare-campaigns` - Compares multiple campaigns
+- [ ] `get-top-performers` - Returns best campaigns
+
+#### LinkedIn Accounts (4 tools)
+- [ ] `list-linkedin-accounts` - Returns connected accounts
+- [ ] `get-linkedin-account` - Returns account details
+- [ ] `get-daily-usage` - Returns today's usage
+- [ ] `get-inmail-balance` - Returns InMail credits
+
+#### Workflow Monitoring (4 tools)
+- [ ] `get-workflow-status` - Returns execution status
+- [ ] `get-pending-actions` - Returns pending actions
+- [ ] `get-failed-actions` - Returns failed actions
+- [ ] `get-execution-progress` - Returns progress %
+
+#### Conversations (7 tools)
+- [ ] `list-conversations` - Returns conversations
+- [ ] `get-conversation` - Returns message thread
+- [ ] `get-recent-replies` - Returns recent replies
+- [ ] `search-conversations` - Searches by keyword
+- [ ] `generate-reply` - AI-generates reply
+- [ ] `list-draft-replies` - Returns queued drafts
+- [ ] `analyze-sentiment` - Analyzes sentiment
+
+#### Enrichment Tables (11 tools)
+- [ ] `list-tables` - Returns all tables
+- [ ] `get-table` - Returns table details
+- [ ] `create-table` - Creates new table
+- [ ] `add-table-rows` - Adds rows to table
+- [ ] `run-enrichment` - Triggers enrichment
+- [ ] `get-enrichment-job-status` - Checks job progress
+- [ ] `export-table-csv` - Exports CSV
+- [ ] `send-table-to-campaign` - Sends rows to campaign
+- [ ] `list-enrichment-providers` - Returns providers
+- [ ] `deduplicate-table` - Removes duplicates
+- [ ] `create-table-from-search` - Search + create
+
+#### Signal Tracking (8 tools)
+- [ ] `list-signals` - Returns detected signals
+- [ ] `list-signal-trackers` - Returns trackers
+- [ ] `create-signal-tracker` - Creates tracker
+- [ ] `pause-signal-tracker` - Pauses tracker
+- [ ] `resume-signal-tracker` - Resumes tracker
+- [ ] `add-signal-to-campaign` - Adds to campaign
+- [ ] `create-prospect-from-signal` - Creates prospect
+- [ ] `trigger-signal-poll` - Triggers manual poll
+
+#### Content & Comments (9 tools)
+- [ ] `generate-content` - Generates LinkedIn post
+- [ ] `list-posts` - Returns all posts
+- [ ] `get-post` - Returns post details
+- [ ] `publish-post` - Publishes to LinkedIn
+- [ ] `get-content-strategy` - Returns strategy
+- [ ] `generate-content-strategy` - AI-generates strategy
+- [ ] `list-comment-drafts` - Returns drafts
+- [ ] `approve-comment-draft` - Approves/rejects draft
+- [ ] `list-tracked-profiles` - Returns tracked profiles
+
+#### People & Company Search (2 tools)
+- [ ] `search-people-database` - Searches people
+- [ ] `search-companies-database` - Searches companies
+
+---
+
+## Error Handling Tests
+
+### API Errors
+- [ ] 400 Bad Request - Returns meaningful error
+- [ ] 401 Unauthorized - Returns auth error
+- [ ] 403 Forbidden - Returns permission error
+- [ ] 404 Not Found - Returns not found error
+- [ ] 422 Validation Error - Returns validation details
+- [ ] 500 Server Error - Returns generic error
+- [ ] Network timeout - Handles gracefully
+- [ ] DNS failure - Handles gracefully
+
+### Input Validation
+- [ ] Missing required fields - Returns validation error
+- [ ] Invalid types (string instead of number) - Returns error
+- [ ] Empty strings where required - Returns error
+- [ ] Invalid enum values - Returns error
+- [ ] Extra unknown fields - Ignores or errors appropriately
+
+### Edge Cases
+- [ ] Empty response from API - Handles gracefully
+- [ ] Null values in response - Handles gracefully
+- [ ] Very large payloads - Handles without crash
+- [ ] Special characters in inputs - Encodes properly
+- [ ] Unicode characters - Handles properly
+
+---
+
+## Performance Tests
+
+- [ ] 100 concurrent requests - No crashes
+- [ ] Large response (10MB+) - Streams properly
+- [ ] Connection pooling - Reuses connections
+- [ ] Memory usage stable - No leaks over 1000 requests
+
+---
+
+## Integration Test Commands
+
+### Stdio Mode Test
+```bash
+# Build first
+npm run build
+
+# Test stdio mode (in one terminal)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js --api-key $PIPELINE_API_KEY
+
+# Expected: JSON response with tools array
+```
+
+### HTTP Mode Test
+```bash
+# Start server
+node dist/index.js --http --port 3000 &
+SERVER_PID=$!
+
+# Test tools/list
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -H "X-API-KEY: $PIPELINE_API_KEY" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+
+# Test a real tool
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $PIPELINE_API_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "list-campaigns",
+      "arguments": {}
+    }
+  }'
+
+# Stop server
+kill $SERVER_PID
+```
+
+---
+
+## Manual Test Checklist for Matt
+
+Using your actual Pipeline API key:
+
+1. **Get API Key**
+   - Go to Pipeline Settings > API Keys
+   - Create a new key
+   - Copy the key
+
+2. **Test Stdio Mode**
+   ```bash
+   cd C:\Users\Matt\Desktop\pipeline-mcp
+   npm run build
+   node dist/index.js --api-key YOUR_API_KEY
+   ```
+   - Should start without errors
+
+3. **Configure Claude Desktop**
+   Add to `claude_desktop_config.json`:
+   ```json
+   {
+     "mcpServers": {
+       "pipeline": {
+         "command": "node",
+         "args": [
+           "C:\\Users\\Matt\\Desktop\\pipeline-mcp\\dist\\index.js",
+           "--api-key",
+           "YOUR_API_KEY"
+         ]
+       }
+     }
+   }
+   ```
+
+4. **Test in Claude**
+   - Restart Claude Desktop
+   - Ask: "What campaigns do I have in Pipeline?"
+   - Ask: "Show me my LinkedIn accounts"
+   - Ask: "What are my top performing campaigns?"
+
+5. **Test HTTP Mode**
+   ```bash
+   node dist/index.js --http --port 3000
+   ```
+   Then test with curl (see commands above)
+
+---
+
+## Test Results Summary
+
+| Category | Passed | Failed | Skipped |
+|----------|--------|--------|---------|
+| Build Verification | 4 | 0 | 0 |
+| Architecture | 5 | 0 | 0 |
+| Unit Tests | TBD | TBD | TBD |
+| Integration Tests | TBD | TBD | TBD |
+| Manual Tests | TBD | TBD | TBD |
+
+**Overall Status:** Build passing, awaiting manual integration tests
+
+---
+
+## Issues Found
+
+### Critical
+- None
+
+### High
+- None
+
+### Medium
+- None
+
+### Low
+- None
+
+---
+
+## Recommendations
+
+1. **Add rate limiting** to HTTP mode to prevent abuse
+2. **Add request logging** for debugging
+3. **Add health check endpoint** (`/health`)
+4. **Add metrics endpoint** for monitoring
+5. **Consider adding retry logic** for transient API failures
+6. **Add request timeout configuration**
+
+---
+
+*Test completed: TBD*

package/dist/http-server.d.ts

@@ -0,0 +1,2 @@
+export declare function startHttpServer(port: number, defaultApiKey?: string, defaultBaseUrl?: string): Promise<void>;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsOA,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,MAAM,EACtB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAsBf"}