k-linkedin-mcp 0.1.0

package/.dockerignore

@@ -0,0 +1,15 @@
+.git/
+.agent/
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+COPILOT.md
+VIBE.md
+.env
+.env.*
+!.env.example
+deploy/docker-compose.override.yml
+node_modules/
+coverage/
+*.log
+TODO.md

package/.gitlab-ci.yml

@@ -0,0 +1,78 @@
+# linkedin-mcp — GitLab CI/CD Pipeline
+# Stages: test → build image → deploy to homelab
+
+stages:
+  - test
+  - build
+  - deploy
+
+variables:
+  IMAGE_NAME: registry.gitlab.com/kpihx-labs/linkedin-mcp
+  CONTAINER_NAME: linkedin_mcp
+
+# ── Test ──────────────────────────────────────────────────────────────────────
+
+test:
+  stage: test
+  image: oven/bun:1-slim
+  script:
+    - bun install --frozen-lockfile
+    - bun test
+  coverage: '/\d+ pass/'
+  artifacts:
+    reports:
+      junit: test-results.xml
+    when: always
+    expire_in: 7 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+
+# ── Build Docker image ────────────────────────────────────────────────────────
+
+build:
+  stage: build
+  image: docker:27
+  services:
+    - docker:27-dind
+  before_script:
+    - echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
+  script:
+    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHORT_SHA -t $IMAGE_NAME:latest .
+    - docker push $IMAGE_NAME:$CI_COMMIT_SHORT_SHA
+    - docker push $IMAGE_NAME:latest
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ── Deploy to Homelab ─────────────────────────────────────────────────────────
+
+deploy:
+  stage: deploy
+  image: alpine:3.20
+  before_script:
+    - apk add --no-cache openssh-client
+    - mkdir -p ~/.ssh
+    - echo "$HOMELAB_SSH_KEY" > ~/.ssh/id_ed25519
+    - chmod 600 ~/.ssh/id_ed25519
+    - ssh-keyscan -H $HOMELAB_HOST >> ~/.ssh/known_hosts
+  script:
+    - |
+      ssh -i ~/.ssh/id_ed25519 kpihx@$HOMELAB_HOST "
+        echo '$CI_REGISTRY_PASSWORD' | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
+        docker pull $IMAGE_NAME:latest
+        cd ~/stacks/linkedin-mcp && docker compose pull && docker compose up -d --remove-orphans
+        docker image prune -f
+      "
+  environment:
+    name: homelab
+    url: https://linkedin.kpihx-labs.com
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+  needs: [build]
+
+# ── Variables to define in GitLab CI/CD Settings → Variables ─────────────────
+# HOMELAB_SSH_KEY    — private SSH key for homelab deploy user (masked, protected)
+# HOMELAB_HOST       — homelab IP/hostname reachable from CI runner (masked)
+# CI_REGISTRY_USER   — GitLab container registry user (auto)
+# CI_REGISTRY_PASSWORD — GitLab registry password / deploy token (masked)

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog — linkedin-mcp
+
+---
+
+## [0.1.0] — 2026-03-22
+
+### Added
+- [x] Full MCP server — 8 tools: guide, auth_status, get_profile, create_post, create_image_post, delete_post, like_post, create_comment
+- [x] LinkedIn OAuth 2.0 + OIDC flow (`linkedin-admin auth`)
+- [x] Three-level admin: CLI (`linkedin-admin`) · HTTP (`/admin/*`) · Telegram bot
+- [x] Dual transport: stdio + Streamable HTTP (Express, port 8095)
+- [x] Token lifecycle management — 60-day expiry tracking, `tokenSummary` with days_left
+- [x] Test suite — 41 tests, 5 files, 0 live API calls (mocked fetch + temp dirs)
+- [x] Docker image (`oven/bun:1-slim`) + `deploy/docker-compose.yml` with Traefik labels
+- [x] GitLab CI — test → build → deploy pipeline
+- [x] Editable install via `bun link`

package/Dockerfile

@@ -0,0 +1,27 @@
+FROM oven/bun:1-slim
+
+WORKDIR /app
+
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile --production
+
+COPY src ./src
+COPY config.json ./config.json
+COPY README.md ./README.md
+COPY CHANGELOG.md ./CHANGELOG.md
+
+RUN chmod +x /app/src/main.js /app/src/admin.js /app/src/admin/cli.js \
+    && ln -sf /app/src/main.js /usr/local/bin/linkedin-mcp \
+    && ln -sf /app/src/admin.js /usr/local/bin/linkedin-admin
+
+ENV NODE_ENV=production
+ENV LINKEDIN_STATE_DIR=/data/state
+ENV LINKEDIN_MCP_HTTP_HOST=0.0.0.0
+ENV LINKEDIN_MCP_HTTP_PORT=8095
+ENV LINKEDIN_MCP_HTTP_PATH=/mcp
+
+VOLUME ["/data"]
+
+EXPOSE 8095
+
+CMD ["bun", "src/main.js", "serve-http"]

package/README.md

@@ -0,0 +1,235 @@
+# linkedin-mcp
+
+> **0 Trust · 100% Control | 0 Magic · 100% Transparency | 0 Hardcoding · 100% Flexibility**
+
+A **Model Context Protocol (MCP) server** for LinkedIn — official OAuth 2.0, intent-first tool surface, three-level admin (CLI · HTTP · Telegram). Designed for the KpihX homelab stack; deployment-ready with Docker + Traefik.
+
+**Repos:** [GitHub](https://github.com/KpihX/linkedin-mcp) · [GitLab](https://gitlab.com/kpihx-labs/linkedin-mcp)
+
+---
+
+## Why this exists
+
+LinkedIn has no general-purpose developer API for personal accounts. The official OAuth surface (`openid profile email w_member_social`) covers everything an individual power-user needs:
+
+- Post, delete, like, comment on content
+- Read own profile and auth status
+- Guide agents through the flow with `linkedin_guide`
+
+This MCP wraps that surface with **full operational visibility**: a CLI admin, an HTTP admin API, and an optional Telegram bot — the same architecture as `whats-mcp`, `tick-mcp`, `mail-mcp`.
+
+---
+
+## Architecture
+
+```
+linkedin-mcp/
+├── src/
+│   ├── main.js          ← entry: serve (stdio) | serve-http
+│   ├── admin.js         ← entry: CLI admin (linkedin-admin)
+│   ├── config.js        ← loadConfig() — deep merge defaults → config.json → env
+│   ├── token.js         ← save / load / clear / summary  (~/.mcps/linkedin/token.json)
+│   ├── client.js        ← LinkedInClient — official REST API calls
+│   ├── server.js        ← createMcpServer() — MCP SDK wiring
+│   ├── http_app.js      ← Express HTTP app: /health /admin/* /mcp
+│   ├── .env.example     ← required secrets template
+│   └── admin/
+│       ├── cli.js       ← Commander CLI (auth / status / logout / logs / health / urls / guide)
+│       ├── service.js   ← shared text helpers (statusSummaryText, healthSummaryText, …)
+│       ├── oauth.js     ← LinkedIn OAuth 2.0 + OIDC flow
+│       └── telegram.js  ← optional Telegram bot admin
+├── tools/
+│   ├── registry.js      ← listTools() + callTool()
+│   ├── guide.js         ← linkedin_guide
+│   ├── profile.js       ← linkedin_get_profile, linkedin_auth_status
+│   ├── posts.js         ← linkedin_create_post, linkedin_create_image_post, linkedin_delete_post
+│   └── social.js        ← linkedin_like_post, linkedin_create_comment
+├── tests/               ← bun test (41 tests, 0 deps on live API)
+├── deploy/
+│   ├── docker-compose.yml
+│   └── docker-compose.override.example.yml
+├── Dockerfile
+├── .gitlab-ci.yml
+└── config.json          ← non-secret defaults (port 8095, state dir, scopes)
+```
+
+**Transport strategy:**
+
+```
+Agent / Claude / Gemini
+         │
+         ├─── HTTP (homelab) ──→  https://linkedin.kpihx-labs.com/mcp   (primary)
+         └─── stdio (local)  ──→  ~/.bun/bin/linkedin-mcp serve         (fallback)
+```
+
+---
+
+## Tools (8)
+
+| Tool | Description |
+|------|-------------|
+| `linkedin_guide` | Orientation — all tools, auth flow, quick start |
+| `linkedin_auth_status` | Token presence, validity, days remaining, profile |
+| `linkedin_get_profile` | Fetch own LinkedIn profile (name, email, sub) |
+| `linkedin_create_post` | Create a text post (PUBLIC or CONNECTIONS) |
+| `linkedin_create_image_post` | Create a post with an attached image |
+| `linkedin_delete_post` | Delete a post by URN |
+| `linkedin_like_post` | Like a post by URN |
+| `linkedin_create_comment` | Add a comment to a post by URN |
+
+---
+
+## Admin interfaces
+
+### CLI (`linkedin-admin`)
+
+```bash
+linkedin-admin auth          # Run OAuth flow — opens browser, saves token
+linkedin-admin status        # Token status + profile
+linkedin-admin status --json # Machine-readable JSON
+linkedin-admin logout        # Clear saved token
+linkedin-admin logs --lines 50
+linkedin-admin health        # HTTP server reachability
+linkedin-admin urls          # All public/private endpoints
+linkedin-admin guide         # Full help text
+```
+
+### HTTP admin
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Liveness probe |
+| `GET /admin/status` | Token status + Telegram runtime state |
+| `GET /admin/help` | All commands reference |
+| `GET /admin/logs?lines=50` | Recent admin log tail |
+| `POST /mcp` | MCP Streamable HTTP transport |
+
+### Telegram bot (optional)
+
+Set `TELEGRAM_LINKEDIN_TOKEN` + `TELEGRAM_CHAT_IDS` and the server polls every 5 s.
+
+| Command | Action |
+|---------|--------|
+| `/start` `/help` | Full command reference |
+| `/status` | Token + service status |
+| `/health` | HTTP server health |
+| `/urls` | Endpoint map |
+| `/logs [n]` | Last n admin log lines (default 20) |
+
+---
+
+## Quick start
+
+### 1. LinkedIn App setup
+
+1. Go to [LinkedIn Developer Portal](https://developer.linkedin.com)
+2. Create an app → add products: **"Sign In with LinkedIn using OpenID Connect"** + **"Share on LinkedIn"**
+3. Set redirect URI: `http://localhost:3000/callback`
+4. Note `Client ID` and `Client Secret`
+
+### 2. Configure secrets
+
+```bash
+cp src/.env.example .env
+# Fill in LINKEDIN_CLIENT_ID and LINKEDIN_CLIENT_SECRET
+```
+
+### 3. Install & authenticate
+
+```bash
+bun install
+bun link              # editable install: ~/.bun/bin/linkedin-mcp + linkedin-admin
+
+linkedin-admin auth   # opens browser → authorizes → saves token
+linkedin-admin status # verify token is valid
+```
+
+### 4. Start MCP server
+
+```bash
+# stdio (for agent config)
+linkedin-mcp serve
+
+# HTTP (for homelab deployment)
+linkedin-mcp serve-http
+```
+
+---
+
+## Docker / Homelab deployment
+
+```bash
+cp deploy/docker-compose.yml docker-compose.yml
+cp deploy/docker-compose.override.example.yml docker-compose.override.yml
+# Edit docker-compose.override.yml with your secrets
+
+docker compose up -d
+```
+
+Traefik labels in `deploy/docker-compose.yml` expose:
+- `https://linkedin.kpihx-labs.com` (primary private trusted route)
+- `https://linkedin.homelab` (fallback)
+
+---
+
+## Agent registration
+
+### Claude Code (`~/.claude.json`)
+
+```json
+"linkedin-mcp": {
+  "type": "http",
+  "url": "https://linkedin.kpihx-labs.com/mcp"
+},
+"linkedin-mcp--fallback": {
+  "command": "/home/kpihx/.bun/bin/linkedin-mcp",
+  "args": ["serve"]
+}
+```
+
+### Gemini (`~/.gemini/extensions/linkedin_mcp/gemini-extension.json`)
+
+```json
+{
+  "name": "linkedin-mcp",
+  "version": "0.1.0",
+  "mcpServers": {
+    "linkedin-mcp": {
+      "httpUrl": "https://linkedin.kpihx-labs.com/mcp"
+    },
+    "linkedin-mcp--fallback": {
+      "command": "/home/kpihx/.bun/bin/linkedin-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+---
+
+## Tests
+
+```bash
+bun test           # 41 tests, 5 files, 0 live API calls
+bun test --watch   # watch mode
+```
+
+All tests use mocked `fetch` and temp directories — no credentials needed.
+
+---
+
+## Token lifecycle
+
+LinkedIn personal OAuth tokens expire in **60 days**. There is no refresh token for non-Partner apps.
+
+```
+Day 0   →  linkedin-admin auth   (OAuth flow, browser consent)
+Day 55+ →  linkedin-admin status  (shows days_left, warns if < 7)
+Day 60  →  token invalid, re-run auth
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/config.json

@@ -0,0 +1,18 @@
+{
+  "server": {
+    "state_directory": "~/.mcps/linkedin",
+    "http_host": "127.0.0.1",
+    "http_port": 8095,
+    "http_mcp_path": "/mcp",
+    "public_base_url": "https://linkedin.kpihx-labs.com",
+    "fallback_base_url": "https://linkedin.homelab"
+  },
+  "oauth": {
+    "redirect_port": 3000,
+    "redirect_uri": "http://localhost:3000/callback",
+    "scopes": ["openid", "profile", "email", "w_member_social"]
+  },
+  "logging": {
+    "level": "error"
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "k-linkedin-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for LinkedIn — intent-first posting, profile management, and professional networking over stdio and HTTP.",
+  "main": "src/main.js",
+  "bin": {
+    "linkedin-mcp": "src/main.js",
+    "linkedin-admin": "src/admin.js"
+  },
+  "scripts": {
+    "start": "bun src/main.js serve",
+    "serve:http": "bun src/main.js serve-http",
+    "admin": "bun src/admin.js",
+    "auth": "bun src/admin.js auth",
+    "status": "bun src/admin.js status",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "keywords": [
+    "linkedin",
+    "mcp",
+    "model-context-protocol",
+    "oauth",
+    "professional-network",
+    "automation"
+  ],
+  "author": "Ivann KAMDEM <kapoivha@gmail.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "commander": "^13.1.0",
+    "express": "^5.2.1",
+    "pino": "^10.3.1"
+  },
+  "devDependencies": {}
+}

package/src/.env.example

@@ -0,0 +1,17 @@
+# LinkedIn OAuth credentials — register your app at https://developer.linkedin.com
+# Products to add: "Sign In with LinkedIn using OpenID Connect" + "Share on LinkedIn"
+LINKEDIN_CLIENT_ID=your_client_id_here
+LINKEDIN_CLIENT_SECRET=your_client_secret_here
+
+# Optional: pre-set access token (bypasses oauth flow). Populated by: linkedin-admin auth
+# LINKEDIN_ACCESS_TOKEN=your_access_token_here
+
+# Optional: Telegram admin bot
+# TELEGRAM_LINKEDIN_TOKEN=your_bot_token_here   (from @BotFather)
+# TELEGRAM_CHAT_IDS=123456789,987654321         (comma-separated chat IDs)
+
+# Optional server overrides
+# LINKEDIN_MCP_HTTP_HOST=0.0.0.0
+# LINKEDIN_MCP_HTTP_PORT=8095
+# LINKEDIN_MCP_LOG_LEVEL=info
+# LINKEDIN_STATE_DIR=~/.mcps/linkedin

package/src/admin/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * linkedin-mcp — Admin CLI (linkedin-admin).
+ *
+ * Commands:
+ *   auth             Start OAuth 2.0 flow (opens browser, saves token)
+ *   status [--json]  Show token + member info
+ *   logout           Clear stored token
+ *   logs [--lines N] Tail the admin log
+ *   health           Show HTTP endpoint URLs
+ *   urls             Show all public URLs
+ *   guide            Show admin capabilities
+ */
+
+"use strict";
+
+const { Command } = require("commander");
+
+const { loadConfig }       = require("../config");
+const { tokenSummary, clearToken } = require("../token");
+const { runOAuthFlow }     = require("./oauth");
+const {
+  adminHelpText,
+  getLogsText,
+  healthSummaryText,
+  statusSummaryText,
+  urlsSummary,
+  appendAdminLog,
+} = require("./service");
+
+const PKG = require("../../package.json");
+
+const program = new Command();
+program
+  .name("linkedin-admin")
+  .description("linkedin-mcp administration: auth, status, logout, logs")
+  .version(PKG.version);
+
+// ── auth ─────────────────────────────────────────────────────────────────────
+
+program
+  .command("auth")
+  .description("Start LinkedIn OAuth 2.0 flow. Opens a browser for authorization.")
+  .action(async () => {
+    const config = loadConfig();
+    if (!config.oauth.client_id || !config.oauth.client_secret) {
+      console.error(
+        "\nError: LINKEDIN_CLIENT_ID and LINKEDIN_CLIENT_SECRET are not set.\n" +
+        "Steps:\n" +
+        "  1. Create app at https://developer.linkedin.com\n" +
+        "  2. Add products: 'Sign In with LinkedIn using OpenID Connect' + 'Share on LinkedIn'\n" +
+        "  3. Set redirect URI: http://localhost:3000/callback\n" +
+        "  4. Store credentials via bw-env: LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET\n",
+      );
+      process.exit(1);
+    }
+    console.log("\nStarting LinkedIn OAuth flow...");
+    console.log(`Redirect URI : ${config.oauth.redirect_uri}`);
+    console.log(`Scopes       : ${config.oauth.scopes.join(", ")}\n`);
+    try {
+      const tokenData = await runOAuthFlow(config, (url) => {
+        console.log("Open this URL in your browser:\n");
+        console.log(`  ${url}\n`);
+        const { execSync } = require("child_process");
+        try { execSync(`xdg-open "${url}"`, { stdio: "ignore" }); } catch { /* silent */ }
+      });
+      appendAdminLog(`auth success member=${tokenData.member_id} name=${tokenData.name}`);
+      console.log(`\nAuthenticated: ${tokenData.name || "LinkedIn member"}`);
+      console.log(`Email        : ${tokenData.email || "N/A"}`);
+      console.log(`Expires in   : ${Math.floor((tokenData.expires_in || 5184000) / 86400)} days`);
+      console.log("\nToken saved. linkedin-mcp is ready.\n");
+    } catch (err) {
+      appendAdminLog(`auth error ${err.message}`);
+      console.error(`\nAuth failed: ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+// ── status ────────────────────────────────────────────────────────────────────
+
+program
+  .command("status")
+  .description("Show current authentication status and token details.")
+  .option("--json", "Output raw JSON")
+  .action((opts) => {
+    const config  = loadConfig();
+    const summary = tokenSummary(config);
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(`\n${statusSummaryText()}\n`);
+    }
+  });
+
+// ── logout ────────────────────────────────────────────────────────────────────
+
+program
+  .command("logout")
+  .description("Clear the stored LinkedIn access token.")
+  .action(() => {
+    const config = loadConfig();
+    clearToken(config);
+    appendAdminLog("logout: token cleared");
+    console.log("\nToken cleared. Run 'linkedin-admin auth' to re-authenticate.\n");
+  });
+
+// ── logs ──────────────────────────────────────────────────────────────────────
+
+program
+  .command("logs")
+  .description("Show recent admin log lines.")
+  .option("--lines <n>", "Number of lines to show", "50")
+  .action((opts) => {
+    const limit = parseInt(opts.lines, 10) || 50;
+    console.log(getLogsText(limit));
+  });
+
+// ── health ────────────────────────────────────────────────────────────────────
+
+program
+  .command("health")
+  .description("Show HTTP endpoint URLs and health check info.")
+  .action(() => {
+    console.log(`\n${healthSummaryText()}\n`);
+  });
+
+// ── urls ──────────────────────────────────────────────────────────────────────
+
+program
+  .command("urls")
+  .description("Show all public and fallback endpoint URLs.")
+  .action(() => {
+    console.log(`\n${urlsSummary()}\n`);
+  });
+
+// ── guide ─────────────────────────────────────────────────────────────────────
+
+program
+  .command("guide")
+  .description("Show full admin capabilities (CLI + HTTP + Telegram).")
+  .action(() => {
+    console.log(`\n${adminHelpText()}\n`);
+  });
+
+module.exports = { program };