Remix MCP Server

A Model Context Protocol (MCP) server for transferring conversation context between AI chat sessions. This server maintains a tree structure of conversations with their message history, allowing you to branch conversations and search through them.

Features

• Conversation Branching: Create new conversations that branch from existing ones, forming a tree structure
• Message Storage: Save chat messages with proper ordering (using a linked list with prev/next message IDs)
• Tree Navigation: View the entire conversation tree or subtrees
• Full-Text Search: Search messages across parent or child conversations using PostgreSQL's powerful text search
• Persistent Storage: Uses PostgreSQL for reliable, scalable storage

Installation

npm install
npm run build

Configuration

The server connects to PostgreSQL using connection parameters that can be specified in three ways (in order of precedence):

1. Command-line arguments
2. Environment variables
3. Default values

Connection Parameters

| Parameter | CLI Argument | CLI Short | Environment Variable | Default | |-----------|--------------|-----------|---------------------|---------| | Host | --host | - | PGHOST | localhost | | Port | --port | -p | PGPORT | 5432 | | User | --user | -U | PGUSER | postgres | | Password | --password | -W | PGPASSWORD | (empty) | | Database | --database | -d | PGDATABASE | remix_mcp | | Connection String | --connection-string | - | - | - |

Note: If --connection-string is provided, it takes precedence over individual parameters.

Security Warning: Passing passwords via command-line arguments (--password) or connection strings can expose them in process listings, shell history, and configuration files. For production deployments:

• Use environment variables (PGPASSWORD) instead
• Use PostgreSQL's .pgpass file for secure credential management
• Ensure configuration files with passwords have restricted permissions (chmod 600)

VS Code

"servers": {
  "remix": {
    "command": "npx",
    "args": [
      "remix-mcp",
      "--host", "localhost",
      "--port", "5432",
      "--user", "myuser",
      "--password", "mypassword",
      "--database", "remix_mcp"
    ]
  }
}

Or using a connection string:

"servers": {
  "remix": {
    "command": "npx",
    "args": [
      "remix-mcp",
      "--connection-string", "postgresql://myuser:mypassword@localhost:5432/remix_mcp"
    ]
  }
}

Claude Desktop

{
  "mcpServers": {
    "remix": {
      "command": "npx",
      "args": [
        "remix-mcp",
        "--host", "localhost",
        "--port", "5432",
        "--user", "myuser",
        "--password", "mypassword",
        "--database", "remix_mcp"
      ]
    }
  }
}

Or using a connection string:

{
  "mcpServers": {
    "remix": {
      "command": "npx",
      "args": [
        "remix-mcp",
        "--connection-string", "postgresql://myuser:mypassword@localhost:5432/remix_mcp"
      ]
    }
  }
}

Environment Variables

You can also set environment variables:

export PGHOST=localhost
export PGPORT=5432
export PGUSER=myuser
export PGPASSWORD=mypassword
export PGDATABASE=remix_mcp
npx remix-mcp

Tools

1. remix_conversation

Save chat messages to create a new conversation or branch from an existing one.

Parameters:

• new_conversation_id (required): Unique ID for the new conversation
• title (required): Title for the conversation
• task_description (required): Description of the task or context
• messages (required): Array of message objects with:
  • author: Either "User" or "Copilot"
  • payload: The message content
• old_conversation_id (optional): Parent conversation ID to branch from

Example:

{
  "new_conversation_id": "conv-123",
  "title": "Implementing User Authentication",
  "task_description": "Discussing best practices for OAuth2 implementation",
  "messages": [
    {
      "author": "User",
      "payload": "How do I implement OAuth2 in Node.js?"
    },
    {
      "author": "Copilot",
      "payload": "Here are the steps for implementing OAuth2..."
    }
  ],
  "old_conversation_id": "conv-100"
}

Quick prompt (usage guide):

• Remix this conversation: “remix this conversation, Save all the messages in this chat that you remember. New id: <new-id>, task_description: <description>, title: <title>”

2. continue_conversation

Retrieve all messages from a conversation to continue it in a new AI chat session.

Parameters:

• conversation_id (required): ID of the conversation to retrieve

Returns: Array of messages with IDs, author, payload, and timestamps.

Quick prompt:

• “continue conversation <conversation-id>”

3. read_conversation_tree

View the conversation tree structure as JSON.

Parameters:

• root_conversation (optional): Start from a specific conversation. If omitted, shows all root conversations.

Returns: Nested JSON tree with conversation IDs, titles, task descriptions, and children.

Quick prompt:

• “show conversation tree starting at <root-id>” (or omit for all)

4. search_parents

Search messages from a child conversation up through all parent conversations.

Parameters:

• keywords (required): Array of search keywords
• child_conversation_id (required): Starting conversation ID

Returns: Matching messages with full metadata.

Quick prompt:

• “search parents of <child-id> for keywords: <kw1>, <kw2>”

5. search_children

Search messages from a parent conversation down through all child conversations recursively.

Parameters:

• keywords (required): Array of search keywords
• parent_conversation_id (required): Starting conversation ID

Returns: Matching messages with full metadata.

Quick prompt:

• “search children of <parent-id> for keywords: <kw1>, <kw2>”

Tool flow (Mermaid)

flowchart TD
    A["Client (Claude / VS Code MCP)"] -->|Call tool| B[remix_conversation]
    A -->|Call tool| C[continue_conversation]
    A -->|Call tool| D[read_conversation_tree]
    A -->|Call tool| E[search_parents]
    A -->|Call tool| F[search_children]
    B -->|writes| G[(PostgreSQL DB)]
    C -->|reads| G
    D -->|reads| G
    E -->|reads FTS + tree| G
    F -->|reads FTS + tree| G

Database Schema

Conversations Table

• id: Primary key
• parent_id: Reference to parent conversation (for tree structure)
• title: Conversation title
• task_description: Task context
• created_at: Timestamp

Messages Table

• id: Primary key
• conversation_id: Reference to conversation
• prev_message_id: Previous message in the linked list
• next_message_id: Next message in the linked list
• author: "User" or "Copilot"
• payload: Message content
• created_at: Timestamp

Full-Text Search: PostgreSQL's native full-text search with GIN indexes is used for efficient message searching.

Development

Build

npm run build

Watch Mode

npm run watch

Changelog

• 0.3.0 (Current)

  • BREAKING: Migrated from SQLite to PostgreSQL
  • Added support for connection parameters via command-line arguments: --host, --port, --user, --password, --database
  • Support for PostgreSQL connection strings via --connection-string
  • Replaced SQLite FTS5 with PostgreSQL full-text search
  • All database operations are now async
  • Environment variable support: PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE
  • Added graceful shutdown handling for database connections

• 0.2.0

  • BREAKING: Replaced --db-path parameter with --connection-string parameter
  • This version used SQLite and is no longer compatible with 0.3.0+

• 0.1.1

  • Added quick usage prompt for remixing a conversation
  • Added installation guides for VS Code MCP extension and Claude Desktop
  • Added Mermaid diagram showing tool flows
  • Updated publish workflow trigger and version bump

License

MIT