# 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

```bash
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 

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

Or using a connection string:

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

### Claude Desktop

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

Or using a connection string:

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

### Environment Variables

You can also set environment variables:

```bash
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:**
```json
{
  "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)

```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
```bash
npm run build
```

### Watch Mode
```bash
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