ThreadShare MCP Server

This is the Model Context Protocol (MCP) server that enables integration with ThreadShare from ChatGPT and VS Code. It allows users to create ThreadShare links, manage their links, and save ChatGPT conversations as beautifully formatted summaries.

Overview

The ThreadShare MCP server provides tools for:

ChatGPT Integration

• Say "save this conversation" in ChatGPT
• Have ChatGPT automatically format the conversation into a structured summary
• Get a shareable link to their formatted summary

VS Code Integration

• Create ThreadShare links from any URL (ChatGPT conversations, GitHub issues, etc.)
• List and manage your ThreadShare links
• Get detailed information about specific links
• Delete links you no longer need

Features

• Track views and analytics on shared conversations
• Beautifully formatted summaries with code blocks, headings, and more
• Shareable links that work anywhere

Architecture

ChatGPT User Interface
        ↓
[Model Context Protocol]
        ↓
ThreadShare MCP Server (this directory)
        ↓
[HTTP REST API]
        ↓
ThreadShare Backend (/src/)
        ↓
PostgreSQL Database

Prerequisites

• Node.js 20+ (LTS)
• npm or pnpm
• ThreadShare backend running (see parent directory)

For ChatGPT Integration

• ChatGPT Developer Mode enabled
• OpenAI Apps SDK preview access

For VS Code Integration

• VS Code with MCP support (VS Code 1.90+)
• A ThreadShare account (sign up at https://threadshare.ai)

Installation

1. Install dependencies:

   npm install

2. Get your authentication token (REQUIRED for VS Code):

   Important: The token is REQUIRED for VS Code tools (list_my_links, get_link_details, delete_link). Only create_threadshare_link can work without a token (using email fallback).

   See the "Getting Your Authentication Token" section below for detailed instructions.

3. Build the TypeScript code:

   npm run build

VS Code Setup

Getting Your Authentication Token

⚠️ REQUIRED for VS Code Integration

The authentication token is required for most VS Code tools. Here's how to get it:

Method 1: Browser Local Storage (Easiest)

1. Sign up or log in to ThreadShare at https://threadshare.ai
2. Open your browser's developer tools:
   • Chrome/Edge: Press F12 or Ctrl+Shift+I (Windows) / Cmd+Option+I (Mac)
   • Firefox: Press F12 or Ctrl+Shift+I (Windows) / Cmd+Option+I (Mac)
   • Safari: Enable Developer menu first, then Cmd+Option+I
3. Navigate to Application/Storage:
   • Click the Application tab (Chrome) or Storage tab (Firefox)
   • In the left sidebar, expand Local Storage
   • Click on https://threadshare.ai
4. Find and copy the token:
   • Look for a key named userData
   • Click on it to see its value (a JSON object)
   • Find the token field inside - it's a long string starting with eyJ...
   • Copy the entire token value (it's a JWT, typically 200+ characters)

Method 2: Network Tab (Alternative)

1. Log in to ThreadShare at https://threadshare.ai
2. Open Developer Tools → Network tab
3. Make any action on the site (click a link, refresh, etc.)
4. Find any API request in the Network tab
5. Click on the request → Headers tab
6. Look for Authorization header - it will show: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
7. Copy everything after Bearer (the token part)

Token Format

Your token will look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI3ODkwMTIzNDU2IiwidXNlckVtYWlsIjoiamRvZUBleGFtcGxlLmNvbSIsImlhdCI6MTczMzQ1Njc4OSwiZXhwIjoxNzM5MDY0Nzg5fQ.xK9mP2qR7sT4vW8yZ3nB6cD1fG5hJ0kL2mN4pQ6rS8t

Important Notes:

• Tokens expire after 7 days - you'll need to get a new one periodically
• Keep your token secure - don't share it or commit it to version control
• If you get authentication errors, your token may have expired - get a new one

Configuring VS Code

1. Open VS Code Settings:

   • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
   • Type "Preferences: Open User Settings (JSON)"
   • Or go to Settings → Extensions → Model Context Protocol

2. Add MCP Server Configuration:

   Add the following to your VS Code settings (.vscode/settings.json in your workspace or global settings):

   {
     "mcp.servers": {
       "threadshare": {
         "command": "node",
         "args": ["/absolute/path/to/threadshare/backend/mcp-server/dist/index.js"],
         "env": {
           "THREADSHARE_AUTH_TOKEN": "PASTE_YOUR_TOKEN_HERE"
         }
       }
     }
   }

   Important: Replace:

   • /absolute/path/to/threadshare/backend/mcp-server/dist/index.js with the actual absolute path to the compiled server
   • PASTE_YOUR_TOKEN_HERE with the actual JWT token you copied from ThreadShare (see "Getting Your Authentication Token" above)
   • The API URL defaults to production automatically - no need to configure it unless using a custom backend

   Example with real values:

   {
     "mcp.servers": {
       "threadshare": {
         "command": "node",
         "args": ["/Users/john/projects/threadshare/backend/mcp-server/dist/index.js"],
         "env": {
           "THREADSHARE_AUTH_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI3ODkwMTIzNDU2IiwidXNlckVtYWlsIjoiamRvZUBleGFtcGxlLmNvbSIsImlhdCI6MTczMzQ1Njc4OSwiZXhwIjoxNzM5MDY0Nzg5fQ.xK9mP2qR7sT4vW8yZ3nB6cD1fG5hJ0kL2mN4pQ6rS8t"
         }
       }
     }
   }

3. Build the MCP Server (if not already built):

   cd backend/mcp-server
   npm run build

4. Restart VS Code to load the MCP server configuration

Using ThreadShare in VS Code Chat

Once configured, you can use natural language commands in VS Code's chat interface:

Example Prompts

Create a ThreadShare link:

Can you create a ThreadShare link for this ChatGPT conversation: https://chat.openai.com/share/abc123

Can you create a ThreadShare link for this conversation covering the bug fix we just went over?

List my links:

Show me all my ThreadShare links

Get link details:

Get details for link with slug xyz789

Delete a link:

Delete the ThreadShare link with ID abc123def456

Available Tools

The MCP server exposes these tools to the LLM:

1. create_threadshare_link - Create a shareable link from any URL

   • Input: originalUrl (required), email (optional)
   • Returns: Short URL, slug, title, and description

2. list_my_links - List all your ThreadShare links

   • Input: None (uses auth token)
   • Returns: Array of links with details

3. get_link_details - Get details about a specific link

   • Input: linkId or slug
   • Returns: Full link information

4. delete_link - Delete a link permanently

   • Input: linkId (required)
   • Returns: Confirmation message

5. save_conversation_summary - Save ChatGPT conversation (ChatGPT integration)

   • Input: email, title, contentBlocks, metadata
   • Returns: Shareable link

Troubleshooting VS Code Integration

MCP Server Not Found:

• Verify the path in args is correct and absolute
• Ensure the server is built: npm run build in backend/mcp-server
• Check that dist/index.js exists

Authentication Errors:

• Token Missing: Make sure THREADSHARE_AUTH_TOKEN is set in VS Code settings
• Token Invalid: Verify your token is correct (check for typos, ensure you copied the entire token)
• Token Expired: Tokens expire after 7 days - get a new one from ThreadShare (see "Getting Your Authentication Token" above)
• Common Issues:
  • Make sure you copied the entire token (it's long, 200+ characters)
  • Don't include Bearer prefix - just the token itself
  • Check for extra spaces or newlines when pasting
  • Try getting a fresh token if errors persist

Connection Errors:

• The server connects to the production backend by default - no configuration needed
• If using a custom backend, verify THREADSHARE_API_URL is correct and the backend is accessible
• Check your network connection and firewall settings

Tools Not Available:

• Restart VS Code after configuration changes
• Check VS Code chat is in "Agent" mode (allows tool usage)
• Verify MCP server is running (check VS Code output panel)

How It Works

1. User Request

User says something like:

• "Save this conversation to ThreadShare"
• "Create a ThreadShare summary"
• "Share this chat"

2. ChatGPT Processing

ChatGPT:

• Analyzes the conversation
• Formats it into structured content blocks
• Extracts key insights and topics
• Creates a compelling title

3. MCP Tool Call

The MCP server receives:

{
  "email": "[email protected]",
  "title": "Understanding REST APIs",
  "contentBlocks": [
    { "type": "heading", "level": 1, "text": "Understanding REST APIs" },
    { "type": "paragraph", "text": "This conversation covers..." },
    { "type": "heading", "level": 2, "text": "Key Concepts" },
    { "type": "list", "ordered": false, "items": ["...", "..."] },
    { "type": "code", "language": "javascript", "code": "...", "caption": "..." }
  ],
  "metadata": {
    "messageCount": 8,
    "hasCode": true,
    "topics": ["REST", "APIs", "HTTP"]
  }
}

4. Backend Storage

The MCP server POSTs to /chatgpt/summary which:

• Finds or creates the user
• Generates a unique slug
• Stores the formatted summary
• Returns a shareable link

5. User Response

ChatGPT displays the shareable link and summary details

Content Block Types

The MCP server instructs ChatGPT to use these content block types:

heading

{
  "type": "heading",
  "level": 1,  // 1, 2, or 3
  "text": "Section Title"
}

paragraph

{
  "type": "paragraph",
  "text": "Regular paragraph text content..."
}

list

{
  "type": "list",
  "ordered": false,  // true for numbered, false for bullets
  "items": ["Item 1", "Item 2", "Item 3"]
}

code

{
  "type": "code",
  "language": "javascript",
  "code": "const example = 'code here';",
  "caption": "Optional description"
}

quote

{
  "type": "quote",
  "text": "Important statement or insight",
  "author": "user",  // or "assistant"
  "context": "Optional context about when this was said"
}

callout

{
  "type": "callout",
  "variant": "tip",  // "info", "tip", "warning", or "success"
  "text": "Helpful information or important note"
}

API Endpoints Used

VS Code Tools (Require Authentication)

• POST /api/links - Create a new link from URL
• GET /api/links - List all user's links
• GET /api/links/:id - Get link details by ID or slug
• DELETE /api/links/:id - Delete a link

ChatGPT Tool

POST /api/chatgpt/summary

Creates a new summary from ChatGPT-formatted data.

Request:

{
  "email": "[email protected]",
  "title": "Conversation Title",
  "contentBlocks": [...],
  "metadata": {
    "messageCount": 10,
    "hasCode": true,
    "topics": ["topic1", "topic2"]
  }
}

Response:

{
  "success": true,
  "summaryId": "abc123",
  "slug": "xyz789",
  "url": "https://threadshare.link/summary/xyz789",
  "message": "Summary created successfully"
}

Troubleshooting

MCP Server Won't Start

• Check that Node.js 20+ is installed: node --version
• Ensure dependencies are installed: npm install
• Check for TypeScript errors: npm run build

Backend Connection Fails

• The server connects to the production backend by default - verify your network connection
• If using a custom backend, check THREADSHARE_API_URL environment variable is set correctly
• Ensure no firewall is blocking HTTPS connections

ChatGPT Can't Find the App

• Verify you're in Developer Mode
• Check the manifest.json is valid
• Ensure the MCP server is running
• Try restarting ChatGPT

Summary Not Saving

• Check backend logs for errors
• Verify the email format is valid
• Ensure contentBlocks array is not empty
• Check database connectivity

Environment Variables

For Local Development

Create a .env file in this directory with:

# Optional: Override backend API URL (defaults to production automatically)
# Only set this if you need to use a custom backend
# THREADSHARE_API_URL=http://localhost:3000

# Optional: JWT token for authenticated operations (VS Code)
# Get your token by logging into https://threadshare.ai
# THREADSHARE_AUTH_TOKEN=your-jwt-token-here

For VS Code Configuration

Set these in VS Code settings (not .env file):

• THREADSHARE_AUTH_TOKEN - REQUIRED: Your JWT authentication token
• THREADSHARE_API_URL - Backend API URL (optional, defaults to production automatically - only set if using a custom backend)

Getting Your Token

See the detailed "Getting Your Authentication Token" section above for step-by-step instructions with screenshots guidance.

Quick version:

1. Log in to ThreadShare at https://threadshare.ai
2. Open browser DevTools (F12) → Application → Local Storage → https://threadshare.ai
3. Find userData → copy the token value (long string starting with eyJ...)
4. Paste it into VS Code settings as THREADSHARE_AUTH_TOKEN

Support

• Documentation: See parent directory README
• Issues: Open an issue on GitHub
• Email: [email protected]

License

MIT