@ldraney/mcp-linkedin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lucas Draney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# MCP LinkedIn
+
+**Post to LinkedIn from Claude Desktop.**
+
+Install in 30 seconds. Authenticate once. Post forever.
+
+## Quick Start
+
+### Option A: One-Click Install (Recommended)
+1. **Download** [mcp-linkedin.mcpb](https://github.com/ldraney/mcp-linkedin/releases/latest)
+2. **Install** in Claude Desktop: Settings → Extensions → Install Extension
+3. **Authorize** when prompted (one-time LinkedIn OAuth)
+
+### Option B: Command Line
+```bash
+npx @ldraney/mcp-linkedin
+```
+Then add to your Claude Desktop config and authorize.
+
+That's it! Ask Claude to post to LinkedIn.
+
+## What You Can Do
+
+Ask Claude to:
+
+- *"Post about my new GitHub project with a link"*
+- *"Create a poll asking my network about AI trends"*
+- *"Schedule a post for tomorrow at 9am"*
+- *"Upload this PDF and share it with my network"*
+
+### 20 Tools Available
+
+| Category | Tools |
+|----------|-------|
+| **Posting** | Text, links, images, videos, documents, polls |
+| **Multi-media** | Up to 20 images per post |
+| **Scheduling** | Schedule posts for future publication |
+| **Engagement** | Comment and react to posts |
+| **Management** | Edit, delete, list your posts |
+
+## How It Works
+
+```
+npm registry (@ldraney/mcp-linkedin)
+    │
+    ├─► Developers: npx @ldraney/mcp-linkedin
+    │
+    └─► Everyone: Download .mcpb → Install via Extensions
+            │
+            └─► Both run the same npm package
+                    │
+                    └─► First use triggers OAuth
+                            │
+                            └─► Tokens stored locally
+                                    │
+                                    └─► Post to LinkedIn!
+```
+
+Your credentials stay on your machine. Our backend only handles the OAuth handshake.
+
+## Requirements
+
+- [Claude Desktop](https://claude.ai/download) installed
+- LinkedIn account
+
+## Documentation
+
+- [User Story](./docs/user-story.html) - Why this exists, user journey
+- [Architecture](./docs/architecture.html) - Technical diagrams
+- [Roadmap](./docs/roadmap.html) - What's coming next
+
+## Features
+
+### Core Posting
+- **Text posts** with hashtags and mentions
+- **Link posts** with article previews (great for GitHub links!)
+- **Image posts** (PNG, JPG, GIF)
+- **Multi-image posts** (2-20 images)
+- **Video posts** (MP4, MOV, up to 200MB)
+- **Document posts** (PDF, PPT, DOC)
+- **Poll posts** (2-4 options, 1-14 day duration)
+
+### Post Management
+- Edit existing posts
+- Delete posts
+- List your recent posts with pagination
+
+### Scheduling
+LinkedIn's API doesn't support native scheduling, so we built it:
+- Schedule posts for any future time
+- List scheduled posts by status
+- Cancel pending posts
+
+### Social Interactions
+- Add comments to posts
+- React to posts (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT)
+
+## For Developers
+
+Want to contribute or run locally?
+
+```bash
+git clone https://github.com/ldraney/mcp-linkedin.git
+cd mcp-linkedin
+npm install
+npm test  # 118 tests
+```
+
+See [CLAUDE.md](./CLAUDE.md) for development guidelines.
+
+## Privacy
+
+- Your LinkedIn access token is stored locally on your machine
+- Our OAuth backend only facilitates the initial authentication
+- We never store or have access to your LinkedIn credentials
+- All API calls go directly from your machine to LinkedIn
+
+## License
+
+MIT - See [LICENSE](./LICENSE)
+
+## Author
+
+Lucas Draney ([@ldraney](https://github.com/ldraney))
+
+---
+
+**Questions?** Open an issue or reach out on LinkedIn!

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ldraney/mcp-linkedin",
+  "version": "0.1.0",
+  "description": "MCP server for LinkedIn automation - post, schedule, and engage from Claude Desktop",
+  "main": "src/index.js",
+  "bin": {
+    "mcp-linkedin": "./src/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ldraney/mcp-linkedin.git"
+  },
+  "homepage": "https://github.com/ldraney/mcp-linkedin",
+  "scripts": {
+    "start": "node src/index.js",
+    "auth": "node src/auth-server.js",
+    "scheduler": "node src/scheduler.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:manual": "node test_post.js"
+  },
+  "keywords": [
+    "mcp",
+    "linkedin",
+    "api",
+    "automation"
+  ],
+  "author": "Lucas Draney",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.6.0",
+    "dotenv": "^16.3.1",
+    "node-cron": "^3.0.3",
+    "uuid": "^11.0.3",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/auth-server.js

@@ -0,0 +1,223 @@
+/**
+ * Spike: Localhost OAuth Callback Server
+ *
+ * Validates that MCP can spin up a temporary HTTP server to receive
+ * OAuth callback from Fly.io backend.
+ *
+ * Usage:
+ *   node src/auth-server.js
+ *
+ * Then complete OAuth flow at:
+ *   https://mcp-linkedin-oauth.fly.dev/auth/linkedin
+ */
+
+const http = require('http');
+const url = require('url');
+
+const PREFERRED_PORT = 3000;
+const MAX_PORT_ATTEMPTS = 10;
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Start the OAuth callback server
+ * @returns {Promise<{code: string, port: number}>} Resolves with auth code when received
+ */
+function startAuthServer() {
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    let server;
+
+    const handleCallback = (req, res) => {
+      const parsedUrl = url.parse(req.url, true);
+
+      // Only handle the callback path
+      if (parsedUrl.pathname !== '/oauth-callback') {
+        res.writeHead(404);
+        res.end('Not Found');
+        return;
+      }
+
+      const { code, error, error_description } = parsedUrl.query;
+
+      if (error) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(`
+          <html>
+            <head><title>Authentication Failed</title></head>
+            <body style="font-family: sans-serif; text-align: center; padding: 2rem;">
+              <h1 style="color: #dc2626;">Authentication Failed</h1>
+              <p>${error}: ${error_description || 'Unknown error'}</p>
+              <p>You can close this tab.</p>
+            </body>
+          </html>
+        `);
+        cleanup();
+        reject(new Error(`OAuth error: ${error} - ${error_description}`));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(`
+          <html>
+            <head><title>Missing Code</title></head>
+            <body style="font-family: sans-serif; text-align: center; padding: 2rem;">
+              <h1 style="color: #dc2626;">Missing Authorization Code</h1>
+              <p>No code received from LinkedIn.</p>
+              <p>You can close this tab.</p>
+            </body>
+          </html>
+        `);
+        cleanup();
+        reject(new Error('No authorization code received'));
+        return;
+      }
+
+      // Success!
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <html>
+          <head><title>Authentication Successful</title></head>
+          <body style="font-family: sans-serif; text-align: center; padding: 2rem;">
+            <h1 style="color: #10b981;">✓ Authentication Successful!</h1>
+            <p>You can close this tab and return to Claude.</p>
+            <script>setTimeout(() => window.close(), 3000);</script>
+          </body>
+        </html>
+      `);
+
+      console.log(`[auth-server] Received authorization code: ${code.substring(0, 20)}...`);
+
+      cleanup();
+      resolve({ code, port: server.address().port });
+    };
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (server) {
+        server.close(() => {
+          console.log('[auth-server] Server shut down');
+        });
+      }
+    };
+
+    server = http.createServer(handleCallback);
+
+    // Try to find an available port
+    const tryPort = (port, attempts = 0) => {
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE' && attempts < MAX_PORT_ATTEMPTS) {
+          console.log(`[auth-server] Port ${port} in use, trying ${port + 1}...`);
+          tryPort(port + 1, attempts + 1);
+        } else {
+          reject(err);
+        }
+      });
+
+      server.listen(port, '127.0.0.1', () => {
+        const actualPort = server.address().port;
+        console.log(`[auth-server] Listening on http://localhost:${actualPort}/oauth-callback`);
+        console.log(`[auth-server] Waiting for OAuth callback (timeout: ${CALLBACK_TIMEOUT_MS / 1000}s)...`);
+
+        // Set timeout
+        timeoutId = setTimeout(() => {
+          console.log('[auth-server] Timeout waiting for callback');
+          cleanup();
+          reject(new Error('Timeout waiting for OAuth callback'));
+        }, CALLBACK_TIMEOUT_MS);
+      });
+    };
+
+    tryPort(PREFERRED_PORT);
+  });
+}
+
+/**
+ * Exchange authorization code for access token
+ * This would normally call linkedin-api.js exchangeCode()
+ */
+async function exchangeCodeForToken(code) {
+  // For spike, just log that we would exchange
+  console.log(`[auth-server] Would exchange code for token: ${code.substring(0, 20)}...`);
+
+  // In real implementation:
+  // const { exchangeCode } = require('./linkedin-api');
+  // return exchangeCode(code);
+
+  return {
+    access_token: 'mock_token',
+    expires_in: 5184000,
+    refresh_token: 'mock_refresh'
+  };
+}
+
+/**
+ * Store token to config directory
+ * This would normally save to ~/.config/mcp-linkedin/credentials.json
+ */
+async function storeToken(tokenData) {
+  const fs = require('fs').promises;
+  const path = require('path');
+  const os = require('os');
+
+  const configDir = path.join(os.homedir(), '.config', 'mcp-linkedin');
+  const credentialsPath = path.join(configDir, 'credentials.json');
+
+  // Create config directory if needed
+  await fs.mkdir(configDir, { recursive: true });
+
+  // Store token with metadata
+  const credentials = {
+    ...tokenData,
+    obtained_at: new Date().toISOString(),
+    expires_at: new Date(Date.now() + (tokenData.expires_in * 1000)).toISOString()
+  };
+
+  await fs.writeFile(credentialsPath, JSON.stringify(credentials, null, 2));
+  console.log(`[auth-server] Token stored at ${credentialsPath}`);
+
+  return credentialsPath;
+}
+
+// Main execution
+async function main() {
+  console.log('='.repeat(60));
+  console.log('MCP LinkedIn OAuth Callback Server (Spike)');
+  console.log('='.repeat(60));
+  console.log('');
+  console.log('1. Open this URL in your browser:');
+  console.log('   https://mcp-linkedin-oauth.fly.dev/auth/linkedin');
+  console.log('');
+  console.log('2. Authorize with LinkedIn');
+  console.log('');
+  console.log('3. You will be redirected back here');
+  console.log('');
+  console.log('='.repeat(60));
+
+  try {
+    const { code, port } = await startAuthServer();
+    console.log(`\n[auth-server] Success! Received code on port ${port}`);
+
+    // Exchange code for token
+    const tokenData = await exchangeCodeForToken(code);
+    console.log('[auth-server] Token exchanged successfully');
+
+    // Store token
+    const credPath = await storeToken(tokenData);
+    console.log(`[auth-server] Credentials saved to ${credPath}`);
+
+    console.log('\n✓ OAuth flow complete!');
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n✗ OAuth flow failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// Export for use as module
+module.exports = { startAuthServer, exchangeCodeForToken, storeToken };
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}

package/src/database.js

@@ -0,0 +1,288 @@
+/**
+ * @fileoverview SQLite database wrapper for scheduled LinkedIn posts
+ * @module database
+ */
+
+const Database = require('better-sqlite3');
+const path = require('path');
+const { v4: uuidv4 } = require('uuid');
+
+/**
+ * @typedef {import('./types').ScheduledPost} ScheduledPost
+ * @typedef {import('./types').ScheduledPostStatus} ScheduledPostStatus
+ */
+
+const DEFAULT_DB_PATH = path.join(__dirname, '..', 'scheduled_posts.db');
+
+/**
+ * Database wrapper for scheduled posts
+ */
+class ScheduledPostsDB {
+  /**
+   * @param {string} [dbPath] - Path to the SQLite database file
+   */
+  constructor(dbPath = DEFAULT_DB_PATH) {
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this._initializeSchema();
+  }
+
+  /**
+   * Initialize the database schema
+   * @private
+   */
+  _initializeSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS scheduled_posts (
+        id TEXT PRIMARY KEY,
+        commentary TEXT NOT NULL,
+        url TEXT,
+        visibility TEXT DEFAULT 'PUBLIC',
+        scheduled_time TEXT NOT NULL,
+        status TEXT DEFAULT 'pending',
+        created_at TEXT NOT NULL,
+        published_at TEXT,
+        post_urn TEXT,
+        error_message TEXT,
+        retry_count INTEGER DEFAULT 0
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_status ON scheduled_posts(status);
+      CREATE INDEX IF NOT EXISTS idx_scheduled_time ON scheduled_posts(scheduled_time);
+    `);
+  }
+
+  /**
+   * Add a new scheduled post
+   * @param {Object} data - Post data
+   * @param {string} data.commentary - Post text
+   * @param {string} data.scheduledTime - ISO 8601 datetime string
+   * @param {string} [data.url] - Optional URL for link posts
+   * @param {string} [data.visibility='PUBLIC'] - Post visibility
+   * @returns {ScheduledPost} The created scheduled post
+   */
+  addScheduledPost({ commentary, scheduledTime, url = null, visibility = 'PUBLIC' }) {
+    const id = uuidv4();
+    const createdAt = new Date().toISOString();
+
+    const stmt = this.db.prepare(`
+      INSERT INTO scheduled_posts (id, commentary, url, visibility, scheduled_time, status, created_at)
+      VALUES (?, ?, ?, ?, ?, 'pending', ?)
+    `);
+
+    stmt.run(id, commentary, url, visibility, scheduledTime, createdAt);
+
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Get a single scheduled post by ID
+   * @param {string} id - Post ID
+   * @returns {ScheduledPost|null} The scheduled post or null if not found
+   */
+  getScheduledPost(id) {
+    const stmt = this.db.prepare('SELECT * FROM scheduled_posts WHERE id = ?');
+    const row = stmt.get(id);
+    return row ? this._rowToPost(row) : null;
+  }
+
+  /**
+   * Get all scheduled posts, optionally filtered by status
+   * @param {ScheduledPostStatus} [status] - Filter by status
+   * @param {number} [limit=50] - Maximum number of posts to return
+   * @returns {ScheduledPost[]} Array of scheduled posts
+   */
+  getScheduledPosts(status = null, limit = 50) {
+    let stmt;
+    if (status) {
+      stmt = this.db.prepare(`
+        SELECT * FROM scheduled_posts
+        WHERE status = ?
+        ORDER BY scheduled_time ASC
+        LIMIT ?
+      `);
+      return stmt.all(status, limit).map(row => this._rowToPost(row));
+    } else {
+      stmt = this.db.prepare(`
+        SELECT * FROM scheduled_posts
+        ORDER BY scheduled_time ASC
+        LIMIT ?
+      `);
+      return stmt.all(limit).map(row => this._rowToPost(row));
+    }
+  }
+
+  /**
+   * Get posts that are due to be published (scheduled time has passed and status is pending)
+   * @returns {ScheduledPost[]} Array of posts ready to publish
+   */
+  getDuePosts() {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      SELECT * FROM scheduled_posts
+      WHERE status = 'pending' AND scheduled_time <= ?
+      ORDER BY scheduled_time ASC
+    `);
+    return stmt.all(now).map(row => this._rowToPost(row));
+  }
+
+  /**
+   * Update post status after successful publish
+   * @param {string} id - Post ID
+   * @param {string} postUrn - The URN of the published post
+   * @returns {ScheduledPost|null} Updated post or null if not found
+   */
+  markAsPublished(id, postUrn) {
+    const publishedAt = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      UPDATE scheduled_posts
+      SET status = 'published', published_at = ?, post_urn = ?
+      WHERE id = ?
+    `);
+    stmt.run(publishedAt, postUrn, id);
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Mark post as failed with error message
+   * @param {string} id - Post ID
+   * @param {string} errorMessage - Error description
+   * @returns {ScheduledPost|null} Updated post or null if not found
+   */
+  markAsFailed(id, errorMessage) {
+    const stmt = this.db.prepare(`
+      UPDATE scheduled_posts
+      SET status = 'failed', error_message = ?, retry_count = retry_count + 1
+      WHERE id = ?
+    `);
+    stmt.run(errorMessage, id);
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Cancel a scheduled post
+   * @param {string} id - Post ID
+   * @returns {ScheduledPost|null} Updated post or null if not found
+   */
+  cancelPost(id) {
+    const stmt = this.db.prepare(`
+      UPDATE scheduled_posts
+      SET status = 'cancelled'
+      WHERE id = ? AND status = 'pending'
+    `);
+    const result = stmt.run(id);
+    if (result.changes === 0) {
+      return null; // Post not found or not in pending status
+    }
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Delete a scheduled post
+   * @param {string} id - Post ID
+   * @returns {boolean} True if deleted, false if not found
+   */
+  deleteScheduledPost(id) {
+    const stmt = this.db.prepare('DELETE FROM scheduled_posts WHERE id = ?');
+    const result = stmt.run(id);
+    return result.changes > 0;
+  }
+
+  /**
+   * Reset a failed post to pending for retry
+   * @param {string} id - Post ID
+   * @returns {ScheduledPost|null} Updated post or null if not found
+   */
+  resetForRetry(id) {
+    const stmt = this.db.prepare(`
+      UPDATE scheduled_posts
+      SET status = 'pending', error_message = NULL
+      WHERE id = ? AND status = 'failed'
+    `);
+    const result = stmt.run(id);
+    if (result.changes === 0) {
+      return null;
+    }
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Update scheduled time for a pending post
+   * @param {string} id - Post ID
+   * @param {string} newScheduledTime - New ISO 8601 datetime string
+   * @returns {ScheduledPost|null} Updated post or null if not found/not pending
+   */
+  reschedulePost(id, newScheduledTime) {
+    const stmt = this.db.prepare(`
+      UPDATE scheduled_posts
+      SET scheduled_time = ?
+      WHERE id = ? AND status = 'pending'
+    `);
+    const result = stmt.run(newScheduledTime, id);
+    if (result.changes === 0) {
+      return null;
+    }
+    return this.getScheduledPost(id);
+  }
+
+  /**
+   * Convert database row to ScheduledPost object
+   * @private
+   * @param {Object} row - Database row
+   * @returns {ScheduledPost}
+   */
+  _rowToPost(row) {
+    return {
+      id: row.id,
+      commentary: row.commentary,
+      url: row.url,
+      visibility: row.visibility,
+      scheduledTime: row.scheduled_time,
+      status: row.status,
+      createdAt: row.created_at,
+      publishedAt: row.published_at,
+      postUrn: row.post_urn,
+      errorMessage: row.error_message,
+      retryCount: row.retry_count
+    };
+  }
+
+  /**
+   * Close the database connection
+   */
+  close() {
+    this.db.close();
+  }
+}
+
+// Singleton instance for the application
+let dbInstance = null;
+
+/**
+ * Get the database instance (creates one if needed)
+ * @param {string} [dbPath] - Optional path for testing
+ * @returns {ScheduledPostsDB}
+ */
+function getDatabase(dbPath) {
+  if (!dbInstance || dbPath) {
+    dbInstance = new ScheduledPostsDB(dbPath);
+  }
+  return dbInstance;
+}
+
+/**
+ * Reset the database instance (for testing)
+ */
+function resetDatabase() {
+  if (dbInstance) {
+    dbInstance.close();
+    dbInstance = null;
+  }
+}
+
+module.exports = {
+  ScheduledPostsDB,
+  getDatabase,
+  resetDatabase,
+  DEFAULT_DB_PATH
+};