@ldraney/mcp-linkedin 0.2.3 → 0.3.1

package/CLAUDE.md

@@ -7,13 +7,13 @@ MCP server for LinkedIn post management via Claude Desktop.
 ```
 src/
   index.js       # MCP server entry point (stdio transport)
-  tools.js       # 18 tool implementations
+  tools.js       # 21 tool implementations
   linkedin-api.js # LinkedIn REST API client
   schemas.js     # Zod validation schemas
   types.js       # JSDoc type definitions
   database.js    # SQLite wrapper for scheduled posts
   scheduler.js   # Background scheduler daemon
-__tests__/       # Jest test suite (118 tests)
+__tests__/       # Jest test suite (135 tests)
 ```
 
 ## Current Tools (Phase 4 Complete)
@@ -33,6 +33,7 @@ __tests__/       # Jest test suite (118 tests)
 | `linkedin_add_comment` | Add comment to a post |
 | `linkedin_add_reaction` | React to a post (LIKE, PRAISE, EMPATHY, etc.) |
 | `linkedin_get_auth_url` | Start OAuth flow |
+| `linkedin_save_credentials` | Save credentials from OAuth callback |
 | `linkedin_exchange_code` | Complete OAuth |
 | `linkedin_refresh_token` | Refresh expired access token |
 | `linkedin_get_user_info` | Get profile info |
@@ -73,7 +74,7 @@ Required in `.env`:
 ```bash
 npm start        # Start MCP server
 npm scheduler    # Start scheduler daemon (runs every minute)
-npm test         # Run tests (97 passing)
+npm test         # Run tests (135 passing)
 ```
 
 ## Roadmap
@@ -220,5 +221,5 @@ npm run test:manual   # Manual API test (test_post.js)
 
 - [LinkedIn Posts API](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api)
 - [LinkedIn Authentication](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authentication)
-- [USER_STORY.md](./USER_STORY.md) - Full user stories
+- [User Story](https://ldraney.github.io/mcp-linkedin/user-story.html) - Full user stories
 - [LINKEDIN_API_REFERENCE.md](./LINKEDIN_API_REFERENCE.md) - API details

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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/MCP_SETUP.md

@@ -236,7 +236,7 @@ Access tokens expire after 60 days. To refresh:
 
 For issues or questions:
 - Check the [main README](./README.md)
-- Review [USER_STORY.md](./USER_STORY.md) for feature details
+- Review [User Story](https://ldraney.github.io/mcp-linkedin/user-story.html) for feature details
 - Open an issue on GitHub
 
 ---

package/README.md

@@ -1,115 +1,82 @@
 # mcp-linkedin
 
-MCP server for managing LinkedIn posts - create text, image, video, document, poll, and multi-image posts. Schedule posts, add comments and reactions.
+**Post to LinkedIn from Claude Desktop.**
 
-## Installation
+Install in 30 seconds. Authenticate once. Post forever.
 
-### MCPB Bundle (One-Click)
-Download from [latest release](https://github.com/intelligent-staffing-systems/mcp-linkedin/releases/latest) and open `mcp-linkedin.mcpb` with Claude Desktop.
+## Quick Start
 
-### npm / npx
+### Option A: One-Click Install (Recommended)
+1. **Download** [mcp-linkedin.mcpb](https://github.com/ldraney/mcp-linkedin/releases/latest/download/mcp-linkedin.mcpb)
+2. **Open** with Claude Desktop
+3. **Authorize** when prompted (one-time LinkedIn OAuth)
+
+### Option B: Command Line
 ```bash
 npx @ldraney/mcp-linkedin
 ```
 
-### Manual MCP Config
-```json
-{
-  "mcpServers": {
-    "linkedin": {
-      "command": "npx",
-      "args": ["@ldraney/mcp-linkedin"],
-      "env": {
-        "LINKEDIN_CLIENT_ID": "your-client-id",
-        "LINKEDIN_CLIENT_SECRET": "your-client-secret",
-        "LINKEDIN_REDIRECT_URI": "https://localhost:8888/callback",
-        "LINKEDIN_PERSON_ID": "your-person-id",
-        "LINKEDIN_ACCESS_TOKEN": "your-access-token"
-      }
-    }
-  }
-}
-```
+## What You Can Do
 
-## Tools (20 Total)
-
-### Content Creation
-| Tool | Description |
-|------|-------------|
-| `linkedin_create_post` | Create text posts |
-| `linkedin_create_post_with_link` | Posts with article/link preview |
-| `linkedin_create_post_with_image` | Upload image + create post |
-| `linkedin_create_post_with_video` | Upload video + create post |
-| `linkedin_create_post_with_document` | Upload PDF/PPT/DOC + create post |
-| `linkedin_create_post_with_multi_images` | Upload 2-20 images + create post |
-| `linkedin_create_poll` | Create poll posts (2-4 options) |
-
-### Content Management
-| Tool | Description |
-|------|-------------|
-| `linkedin_get_my_posts` | Retrieve recent posts (paginated) |
-| `linkedin_update_post` | Edit existing posts |
-| `linkedin_delete_post` | Delete by URN |
-
-### Social Interactions
-| Tool | Description |
-|------|-------------|
-| `linkedin_add_comment` | Add comment to a post |
-| `linkedin_add_reaction` | React to a post (LIKE, PRAISE, etc.) |
-
-### Scheduling
-| Tool | Description |
-|------|-------------|
-| `linkedin_schedule_post` | Schedule for future publication |
-| `linkedin_list_scheduled_posts` | List by status |
-| `linkedin_cancel_scheduled_post` | Cancel pending post |
-| `linkedin_get_scheduled_post` | Get scheduled post details |
-
-### Authentication
-| Tool | Description |
-|------|-------------|
-| `linkedin_get_auth_url` | Start OAuth flow |
-| `linkedin_exchange_code` | Complete OAuth |
-| `linkedin_refresh_token` | Refresh expired token |
-| `linkedin_get_user_info` | Get profile info |
-
-## Setup
-
-### Option 1: Quick Setup (Recommended)
-1. Install the extension
-2. Ask Claude: "Help me set up LinkedIn authentication"
-3. Follow the guided OAuth flow
-
-### Option 2: Manual Setup
-1. Create a LinkedIn Developer App at https://www.linkedin.com/developers/apps
-2. Add products: "Sign In with LinkedIn using OpenID Connect" + "Share on LinkedIn"
-3. Configure redirect URI: `https://localhost:8888/callback`
-4. Set environment variables (see Installation above)
-
-## Running the Scheduler
-
-For scheduled posts to publish automatically:
-```bash
-npm run scheduler
+Ask Claude things like:
+- *"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"*
+- *"Add a comment to my latest post"*
+
+## 21 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
+
+```
+You install mcp-linkedin (npm or .mcpb)
+         │
+         └─► First use triggers OAuth
+                   │
+                   └─► Tokens stored locally on your machine
+                             │
+                             └─► Claude posts to LinkedIn for you
 ```
 
-This runs a daemon that checks every minute for posts due to publish.
+Your credentials stay on your machine. The OAuth relay only handles the initial handshake.
 
-## Development
+## Privacy
+
+- Your LinkedIn access token is stored locally on your machine
+- We never store or access your LinkedIn credentials
+- All API calls go directly from your machine to LinkedIn
+
+## Requirements
+
+- [Claude Desktop](https://claude.ai/download)
+- LinkedIn account
+
+## Feedback
+
+Found a bug? Have a feature request?
+[Open an issue](https://github.com/ldraney/mcp-linkedin/issues/new)
+
+For security vulnerabilities, see [SECURITY.md](./SECURITY.md).
+
+## For Developers
 
 ```bash
+git clone https://github.com/ldraney/mcp-linkedin.git
+cd mcp-linkedin
 npm install
-npm test              # 118 tests
-npm run test:coverage # Coverage report
-npm start             # Start MCP server
-npm run scheduler     # Start scheduler daemon
+npm test  # 135 tests
 ```
 
-## Documentation
-
-- [CLAUDE.md](./CLAUDE.md) - Project structure and API details
-- [MCP_SETUP.md](./MCP_SETUP.md) - Claude Desktop configuration
-- [LINKEDIN_API_REFERENCE.md](./LINKEDIN_API_REFERENCE.md) - API documentation
+See [CLAUDE.md](./CLAUDE.md) for architecture and API details.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,68 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in mcp-linkedin, please report it responsibly:
+
+1. **Do NOT open a public issue** for security vulnerabilities
+2. **Email:** Open a [private security advisory](https://github.com/ldraney/mcp-linkedin/security/advisories/new) on GitHub
+3. **Include:** Description of the vulnerability, steps to reproduce, and potential impact
+
+You should receive a response within 48 hours. We'll work with you to understand the issue and coordinate a fix before any public disclosure.
+
+## Security Model
+
+### Credential Storage
+
+- OAuth tokens are stored in your **operating system's secure keychain** (macOS Keychain, Windows Credential Manager, Linux Secret Service) via [@napi-rs/keyring](https://github.com/nicedoc/keyring)
+- Environment variables (`.env`) are supported as a fallback for development setups
+- Legacy plaintext credential file support (`~/.mcp-linkedin-credentials.json`) was removed in v0.3.x
+- Token values are masked in all tool outputs to prevent accidental exposure in logs or chat history
+- The OAuth relay server (`fly.io`) only handles the initial handshake redirect -- it never sees or stores your access token
+
+### Data Flow
+
+```
+Your Machine                    External
+┌─────────────────┐            ┌──────────────┐
+│ Claude Desktop  │            │              │
+│   ├─ mcp-linkedin│──────────►│ LinkedIn API │
+│   └─ OS Keychain│            │              │
+└─────────────────┘            └──────────────┘
+        │
+        │ (OAuth only)
+        ▼
+┌─────────────────┐
+│ OAuth Relay     │
+│ (fly.io)        │
+│ Redirect only   │
+└─────────────────┘
+```
+
+- All LinkedIn API calls go **directly** from your machine to LinkedIn
+- No telemetry, analytics, or data collection
+- Scheduled posts are stored in a **local** SQLite database on your machine
+
+### OAuth Security
+
+- CSRF protection via cryptographic nonces on every OAuth flow
+- Tokens are captured by a local callback server and stored directly in your keychain
+- The `w_member_social` scope is the only permission requested (post and interact on your behalf)
+
+### What We Don't Do
+
+- We never store your credentials on any remote server
+- We never log or transmit your LinkedIn data
+- We never access your LinkedIn connections, messages, or profile data beyond what you explicitly post
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.3.x   | Yes       |
+| 0.2.x   | Yes       |
+| < 0.2   | No        |
+
+## Dependencies
+
+We keep dependencies minimal to reduce attack surface. Run `npm audit` to check for known vulnerabilities in dependencies.

package/__tests__/auth/local-server.test.js

@@ -0,0 +1,177 @@
+/**
+ * @file Tests for local callback server
+ * Tests the OAuth callback server functionality
+ */
+
+const http = require('http');
+const { URL } = require('url');
+
+// We need to test the actual module, not mock it
+const {
+  startCallbackServer,
+  generateNonce,
+  findAvailablePort
+} = require('../../src/auth/local-server');
+
+describe('Local Callback Server', () => {
+  describe('generateNonce', () => {
+    it('should generate a base64url-encoded string', () => {
+      const nonce = generateNonce();
+
+      expect(typeof nonce).toBe('string');
+      expect(nonce.length).toBeGreaterThan(20);
+      // Base64url should not contain + or /
+      expect(nonce).not.toMatch(/[+\/]/);
+    });
+
+    it('should generate unique nonces', () => {
+      const nonces = new Set();
+      for (let i = 0; i < 100; i++) {
+        nonces.add(generateNonce());
+      }
+      expect(nonces.size).toBe(100);
+    });
+  });
+
+  describe('findAvailablePort', () => {
+    it('should find a port in the expected range', async () => {
+      const port = await findAvailablePort();
+
+      expect(port).toBeGreaterThanOrEqual(8880);
+      expect(port).toBeLessThanOrEqual(8899);
+    });
+  });
+
+  describe('startCallbackServer', () => {
+    it('should return port, nonce, and waitForCallback function', async () => {
+      const serverInfo = await startCallbackServer();
+
+      expect(serverInfo).toHaveProperty('port');
+      expect(serverInfo).toHaveProperty('nonce');
+      expect(serverInfo).toHaveProperty('waitForCallback');
+
+      expect(typeof serverInfo.port).toBe('number');
+      expect(typeof serverInfo.nonce).toBe('string');
+      expect(typeof serverInfo.waitForCallback).toBe('function');
+
+      expect(serverInfo.port).toBeGreaterThanOrEqual(8880);
+      expect(serverInfo.port).toBeLessThanOrEqual(8899);
+
+      // Don't call waitForCallback - that would start the server listening
+      // Just verify the shape is correct
+    });
+
+    it('should receive credentials on successful callback', async () => {
+      const { port, nonce, waitForCallback } = await startCallbackServer();
+
+      // Start waiting for callback
+      const callbackPromise = waitForCallback();
+
+      // Simulate OAuth relay callback
+      const callbackUrl = `http://127.0.0.1:${port}/callback?` +
+        `nonce=${nonce}&` +
+        `access_token=test-access-token&` +
+        `person_id=test-person-id&` +
+        `expires_in=5184000`;
+
+      // Make HTTP request to callback endpoint
+      await new Promise((resolve, reject) => {
+        const url = new URL(callbackUrl);
+        const req = http.request({
+          hostname: '127.0.0.1',
+          port: port,
+          path: url.pathname + url.search,
+          method: 'GET'
+        }, (res) => {
+          expect(res.statusCode).toBe(200);
+          resolve();
+        });
+        req.on('error', reject);
+        req.end();
+      });
+
+      // Wait for credentials
+      const credentials = await callbackPromise;
+
+      expect(credentials).toEqual({
+        accessToken: 'test-access-token',
+        personId: 'test-person-id',
+        refreshToken: null,
+        expiresAt: expect.any(Number)
+      });
+    });
+
+    it('should reject on nonce mismatch', async () => {
+      const { port, waitForCallback } = await startCallbackServer();
+
+      // Start waiting FIRST and attach catch handler immediately
+      const callbackPromise = waitForCallback();
+      let rejection = null;
+      callbackPromise.catch(err => { rejection = err; });
+
+      // Callback with wrong nonce
+      const callbackUrl = `http://127.0.0.1:${port}/callback?` +
+        `nonce=wrong-nonce&` +
+        `access_token=test-token&` +
+        `person_id=test-person`;
+
+      // Make the request
+      await new Promise((resolve) => {
+        const url = new URL(callbackUrl);
+        const req = http.request({
+          hostname: '127.0.0.1',
+          port: port,
+          path: url.pathname + url.search,
+          method: 'GET'
+        }, (res) => {
+          expect(res.statusCode).toBe(400);
+          resolve();
+        });
+        req.on('error', resolve);
+        req.end();
+      });
+
+      // Wait a tick for the rejection to be captured
+      await new Promise(r => setTimeout(r, 10));
+
+      expect(rejection).not.toBeNull();
+      expect(rejection.message).toContain('Nonce mismatch');
+    });
+
+    it('should reject on OAuth error', async () => {
+      const { port, nonce, waitForCallback } = await startCallbackServer();
+
+      // Start waiting FIRST and attach catch handler immediately
+      const callbackPromise = waitForCallback();
+      let rejection = null;
+      callbackPromise.catch(err => { rejection = err; });
+
+      // Callback with error
+      const callbackUrl = `http://127.0.0.1:${port}/callback?` +
+        `nonce=${nonce}&` +
+        `error=access_denied&` +
+        `error_description=User+denied+access`;
+
+      await new Promise((resolve) => {
+        const url = new URL(callbackUrl);
+        const req = http.request({
+          hostname: '127.0.0.1',
+          port: port,
+          path: url.pathname + url.search,
+          method: 'GET'
+        }, (res) => {
+          expect(res.statusCode).toBe(400);
+          resolve();
+        });
+        req.on('error', resolve);
+        req.end();
+      });
+
+      // Wait a tick for the rejection to be captured
+      await new Promise(r => setTimeout(r, 10));
+
+      expect(rejection).not.toBeNull();
+      expect(rejection.message).toContain('OAuth error');
+    });
+  });
+});

package/__tests__/auth/token-storage.test.js

@@ -0,0 +1,141 @@
+/**
+ * @file Tests for token storage module
+ * Tests the OS keychain credential storage functionality
+ */
+
+// Mock @napi-rs/keyring before requiring the module
+const mockSetPassword = jest.fn();
+const mockGetPassword = jest.fn();
+const mockDeletePassword = jest.fn();
+
+jest.mock('@napi-rs/keyring', () => ({
+  Entry: jest.fn().mockImplementation(() => ({
+    setPassword: mockSetPassword,
+    getPassword: mockGetPassword,
+    deletePassword: mockDeletePassword
+  }))
+}));
+
+const { Entry } = require('@napi-rs/keyring');
+const {
+  storeCredentials,
+  getCredentials,
+  deleteCredentials,
+  hasCredentials
+} = require('../../src/auth/token-storage');
+
+describe('Token Storage Module', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('storeCredentials', () => {
+    it('should store credentials as JSON in keychain', () => {
+      const credentials = {
+        accessToken: 'test-token-123',
+        personId: 'test-person-456',
+        refreshToken: 'refresh-789',
+        expiresAt: Date.now() + 3600000
+      };
+
+      storeCredentials(credentials);
+
+      expect(Entry).toHaveBeenCalledWith('mcp-linkedin', 'oauth-credentials');
+      expect(mockSetPassword).toHaveBeenCalledWith(JSON.stringify(credentials));
+    });
+
+    it('should store minimal credentials', () => {
+      const credentials = {
+        accessToken: 'test-token',
+        personId: 'test-person'
+      };
+
+      storeCredentials(credentials);
+
+      expect(mockSetPassword).toHaveBeenCalledWith(JSON.stringify(credentials));
+    });
+  });
+
+  describe('getCredentials', () => {
+    it('should retrieve and parse credentials from keychain', () => {
+      const storedData = {
+        accessToken: 'stored-token',
+        personId: 'stored-person',
+        refreshToken: null,
+        expiresAt: null
+      };
+      mockGetPassword.mockReturnValue(JSON.stringify(storedData));
+
+      const result = getCredentials();
+
+      expect(Entry).toHaveBeenCalledWith('mcp-linkedin', 'oauth-credentials');
+      expect(result).toEqual(storedData);
+    });
+
+    it('should return null when no credentials stored', () => {
+      mockGetPassword.mockReturnValue(null);
+
+      const result = getCredentials();
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null on keychain access error', () => {
+      mockGetPassword.mockImplementation(() => {
+        throw new Error('Access denied');
+      });
+
+      const result = getCredentials();
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null for empty string', () => {
+      mockGetPassword.mockReturnValue('');
+
+      const result = getCredentials();
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('deleteCredentials', () => {
+    it('should delete credentials from keychain', () => {
+      mockDeletePassword.mockReturnValue(undefined);
+
+      const result = deleteCredentials();
+
+      expect(Entry).toHaveBeenCalledWith('mcp-linkedin', 'oauth-credentials');
+      expect(mockDeletePassword).toHaveBeenCalled();
+      expect(result).toBe(true);
+    });
+
+    it('should return false when credentials not found', () => {
+      mockDeletePassword.mockImplementation(() => {
+        throw new Error('Item not found');
+      });
+
+      const result = deleteCredentials();
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('hasCredentials', () => {
+    it('should return true when credentials exist', () => {
+      mockGetPassword.mockReturnValue(JSON.stringify({ accessToken: 'test' }));
+
+      const result = hasCredentials();
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false when no credentials', () => {
+      mockGetPassword.mockReturnValue(null);
+
+      const result = hasCredentials();
+
+      expect(result).toBe(false);
+    });
+  });
+});