thread-mcp 1.0.0

package/README.md

@@ -0,0 +1,497 @@
+# Thread MCP
+
+An MCP (Model Context Protocol) server for saving AI conversation threads to local files or remote servers. This tool enables you to preserve, update, search, and resume your conversations with AI applications like Claude, ChatGPT, and others.
+
+## Features
+
+- **Unified Saving**: Store conversations locally (Markdown/JSON) or remotely via REST API
+- **Smart Search**: Find threads by ID, title, tags, or full-text search with relevance scoring
+- **Easy Updates**: Append messages by ID or title - no need to track IDs manually
+- **Resume Conversations**: Load previous threads with context optimized for AI continuation
+- **Rich Metadata**: Include timestamps, tags, summaries, and source application info
+
+## Installation
+
+```bash
+npm install thread-mcp
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/your-username/thread-mcp.git
+cd thread-mcp
+npm install
+npm run build
+```
+
+## Usage
+
+### Configure with Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "thread-mcp": {
+      "command": "npx",
+      "args": ["thread-mcp"]
+    }
+  }
+}
+```
+
+Or if installed from source:
+
+```json
+{
+  "mcpServers": {
+    "thread-mcp": {
+      "command": "node",
+      "args": ["/path/to/thread-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `save_thread`
+
+Save a new conversation thread to local storage or a remote server.
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `title` | string | Yes | - | Title for the thread |
+| `messages` | array | Yes | - | Array of messages with `role` and `content` |
+| `destination` | string | No | `"local"` | Where to save: `"local"` or `"remote"` |
+| `format` | string | No | `"markdown"` | Output format: `"markdown"` or `"json"` |
+| `sourceApp` | string | No | - | Name of the AI application |
+| `tags` | string[] | No | - | Tags for categorization |
+| `summary` | string | No | - | Summary of the conversation |
+| `outputDir` | string | No | `~/.thread-mcp` | Custom directory for local storage |
+| `remoteUrl` | string | Conditional | - | Required when destination is `"remote"` |
+| `apiKey` | string | No | - | API key for remote authentication |
+| `headers` | object | No | - | Additional HTTP headers for remote |
+
+**Example:**
+
+```json
+{
+  "title": "Code Review Discussion",
+  "messages": [
+    { "role": "user", "content": "Can you review this Python function?" },
+    { "role": "assistant", "content": "Sure! Here are my suggestions..." }
+  ],
+  "sourceApp": "Claude",
+  "tags": ["code-review", "python"],
+  "format": "markdown"
+}
+```
+
+---
+
+### `find_threads`
+
+Find saved threads by ID, title, search query, or list all threads. Supports filtering and relevance scoring.
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `id` | string | No | - | Get a specific thread by ID (returns full details) |
+| `title` | string | No | - | Find thread by exact title match |
+| `query` | string | No | - | Search in titles, summaries, and content |
+| `tags` | string[] | No | - | Filter by tags (must have ALL specified) |
+| `sourceApp` | string | No | - | Filter by source application |
+| `dateFrom` | string | No | - | Filter by creation date (ISO format) |
+| `dateTo` | string | No | - | Filter by creation date (ISO format) |
+| `includeMessages` | boolean | No | `false` | Include full message content |
+| `limit` | number | No | `50` | Maximum results to return |
+| `source` | string | No | `"local"` | Source: `"local"` or `"remote"` |
+| `outputDir` | string | No | `~/.thread-mcp` | Directory for local storage |
+| `remoteUrl` | string | Conditional | - | Required when source is `"remote"` |
+
+**Examples:**
+
+List all threads:
+```json
+{
+  "source": "local"
+}
+```
+
+Find by ID:
+```json
+{
+  "id": "abc123-def456"
+}
+```
+
+Search with filters:
+```json
+{
+  "query": "Python debugging",
+  "tags": ["code"],
+  "includeMessages": true,
+  "limit": 5
+}
+```
+
+**Response includes relevance metadata:**
+
+```json
+{
+  "totalResults": 3,
+  "threads": [
+    {
+      "id": "abc123",
+      "title": "Python Debugging Session",
+      "summary": "Discussion about debugging techniques",
+      "tags": ["python", "debugging"],
+      "messageCount": 12,
+      "createdAt": "2024-01-15T10:00:00.000Z",
+      "relevance": {
+        "score": 85,
+        "matchedFields": ["title", "content"],
+        "topicHints": ["python", "debugging", "error handling"]
+      }
+    }
+  ]
+}
+```
+
+---
+
+### `update_thread`
+
+Update an existing thread by appending new messages. Find thread by ID or title.
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `id` | string | Conditional | - | Thread ID (use this OR title) |
+| `title` | string | Conditional | - | Find thread by exact title (use this OR id) |
+| `messages` | array | Yes | - | New messages to add |
+| `mode` | string | No | `"append"` | `"append"` to add messages, `"replace"` to overwrite |
+| `deduplicateMessages` | boolean | No | `true` | Skip duplicate messages |
+| `newTitle` | string | No | - | Update the thread title |
+| `tags` | string[] | No | - | Update tags |
+| `summary` | string | No | - | Update summary |
+| `source` | string | No | `"local"` | Source: `"local"` or `"remote"` |
+| `outputDir` | string | No | `~/.thread-mcp` | Directory for local storage |
+| `remoteUrl` | string | Conditional | - | Required when source is `"remote"` |
+
+**Example - Append by title:**
+
+```json
+{
+  "title": "Code Review Discussion",
+  "messages": [
+    { "role": "user", "content": "What about error handling?" },
+    { "role": "assistant", "content": "Good point! You should..." }
+  ]
+}
+```
+
+**Example - Update by ID with new metadata:**
+
+```json
+{
+  "id": "abc123-def456",
+  "messages": [
+    { "role": "user", "content": "Follow-up question..." }
+  ],
+  "tags": ["code-review", "python", "error-handling"],
+  "summary": "Extended discussion including error handling"
+}
+```
+
+---
+
+### `delete_thread`
+
+Delete a saved thread by ID or title.
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `id` | string | Conditional | - | Thread ID (use this OR title) |
+| `title` | string | Conditional | - | Find thread by exact title (use this OR id) |
+| `source` | string | No | `"local"` | Source: `"local"` or `"remote"` |
+| `outputDir` | string | No | `~/.thread-mcp` | Directory for local storage |
+| `remoteUrl` | string | Conditional | - | Required when source is `"remote"` |
+
+**Examples:**
+
+```json
+{
+  "id": "abc123-def456"
+}
+```
+
+```json
+{
+  "title": "Old Discussion to Remove"
+}
+```
+
+---
+
+### `resume_thread`
+
+Load a saved thread to continue the conversation. Returns context optimized for AI continuation.
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `id` | string | Conditional | - | Thread ID |
+| `title` | string | Conditional | - | Find by exact title match |
+| `titleContains` | string | Conditional | - | Find most recent thread with title containing this |
+| `format` | string | No | `"structured"` | Output format (see below) |
+| `maxMessages` | number | No | all | Limit to last N messages |
+| `includeSummary` | boolean | No | `true` | Include thread summary |
+| `source` | string | No | `"local"` | Source: `"local"` or `"remote"` |
+| `outputDir` | string | No | `~/.thread-mcp` | Directory for local storage |
+| `remoteUrl` | string | Conditional | - | Required when source is `"remote"` |
+
+**Output Formats:**
+
+- `"structured"` - Organized context with metadata, messages, and continuation hints
+- `"narrative"` - Human-readable summary suitable for context injection
+- `"messages"` - Raw message array only
+
+**Example - Resume by title:**
+
+```json
+{
+  "title": "Code Review Discussion",
+  "format": "structured",
+  "maxMessages": 10
+}
+```
+
+**Structured Response:**
+
+```json
+{
+  "found": true,
+  "id": "abc123",
+  "format": "structured",
+  "context": {
+    "title": "Code Review Discussion",
+    "summary": "Discussion about Python best practices",
+    "tags": ["code-review", "python"],
+    "messageCount": 15,
+    "startedAt": "2024-01-15T10:00:00.000Z"
+  },
+  "messages": [...],
+  "continuationHint": "The assistant last responded. The user may have follow-up questions.",
+  "totalMessages": 15
+}
+```
+
+## Typical Workflow
+
+1. **Save a new thread** after an important conversation:
+   ```json
+   { "title": "Project Planning", "messages": [...], "tags": ["planning"] }
+   ```
+
+2. **Continue later** - find and resume:
+   ```json
+   { "title": "Project Planning" }  // resume_thread
+   ```
+
+3. **Add new messages** as the conversation continues:
+   ```json
+   { "title": "Project Planning", "messages": [new messages...] }  // update_thread
+   ```
+
+4. **Search across threads** to find relevant context:
+   ```json
+   { "query": "database schema", "tags": ["planning"] }  // find_threads
+   ```
+
+## Output Formats
+
+### Markdown
+
+Produces a human-readable Markdown file with YAML frontmatter:
+
+```markdown
+---
+id: abc123-def456
+title: "Code Review Discussion"
+created_at: 2024-01-15T10:00:00.000Z
+source_app: Claude
+tags: ["code-review", "python"]
+---
+
+# Code Review Discussion
+
+> A discussion about Python best practices
+
+## Conversation
+
+### User _(1/15/2024, 10:00:00 AM)_
+
+Can you review this Python function?
+
+### Assistant _(1/15/2024, 10:00:05 AM)_
+
+Sure! Here are my suggestions...
+```
+
+### JSON
+
+Produces a structured JSON file:
+
+```json
+{
+  "id": "abc123-def456",
+  "metadata": {
+    "title": "Code Review Discussion",
+    "sourceApp": "Claude",
+    "createdAt": "2024-01-15T10:00:00.000Z",
+    "tags": ["code-review", "python"]
+  },
+  "messages": [
+    {
+      "role": "user",
+      "content": "Can you review this Python function?",
+      "timestamp": "2024-01-15T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+## Remote Server API
+
+When using remote storage, your server should implement these endpoints:
+
+### `POST /conversations`
+
+Create a new conversation.
+
+**Request Body:**
+
+```json
+{
+  "id": "string",
+  "title": "string",
+  "content": "string (formatted content)",
+  "format": "markdown | json",
+  "metadata": { ... }
+}
+```
+
+**Response:**
+
+```json
+{
+  "url": "https://your-server.com/conversations/id"
+}
+```
+
+### `GET /conversations`
+
+List all conversations.
+
+### `GET /conversations/:id`
+
+Get a specific conversation.
+
+### `PUT /conversations/:id`
+
+Update a conversation (for update_thread).
+
+### `DELETE /conversations/:id`
+
+Delete a conversation.
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- npm
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run Tests
+
+```bash
+npm test                 # Run all tests
+npm run test:watch       # Watch mode
+npm run test:coverage    # With coverage report
+```
+
+### Development Server
+
+```bash
+npm run dev
+```
+
+### Linting & Formatting
+
+```bash
+npm run lint            # ESLint
+npm run format          # Prettier format
+npm run format:check    # Check formatting
+npm run typecheck       # TypeScript type checking
+```
+
+## Project Structure
+
+```
+thread-mcp/
+├── src/
+│   ├── index.ts           # Entry point
+│   ├── server.ts          # MCP server setup
+│   ├── types.ts           # TypeScript types & Zod schemas
+│   ├── tools/             # MCP tool implementations
+│   │   ├── save-thread.ts    # Save new threads
+│   │   ├── find-threads.ts   # Search/list/get threads
+│   │   ├── update-thread.ts  # Update existing threads
+│   │   ├── delete-thread.ts  # Delete threads
+│   │   └── resume-thread.ts  # Load threads for continuation
+│   ├── formatters/        # Output formatters
+│   │   ├── markdown.ts
+│   │   └── json.ts
+│   └── storage/           # Storage providers
+│       ├── local.ts
+│       └── remote.ts
+├── tests/
+│   ├── unit/              # Unit tests
+│   └── e2e/               # End-to-end tests
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## License
+
+MIT
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npm test`
+5. Submit a pull request

package/dist/formatters/index.d.ts

@@ -0,0 +1,5 @@
+import type { Formatter, OutputFormat } from "../types.js";
+export { markdownFormatter } from "./markdown.js";
+export { jsonFormatter } from "./json.js";
+export declare function getFormatter(format: OutputFormat): Formatter;
+//# sourceMappingURL=index.d.ts.map

package/dist/formatters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAO1C,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAE5D"}

package/dist/formatters/index.js

@@ -0,0 +1,12 @@
+import { markdownFormatter } from "./markdown.js";
+import { jsonFormatter } from "./json.js";
+export { markdownFormatter } from "./markdown.js";
+export { jsonFormatter } from "./json.js";
+const formatters = {
+    markdown: markdownFormatter,
+    json: jsonFormatter,
+};
+export function getFormatter(format) {
+    return formatters[format];
+}
+//# sourceMappingURL=index.js.map

package/dist/formatters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,UAAU,GAAoC;IAClD,QAAQ,EAAE,iBAAiB;IAC3B,IAAI,EAAE,aAAa;CACpB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/formatters/json.d.ts

@@ -0,0 +1,3 @@
+import { type Formatter } from "../types.js";
+export declare const jsonFormatter: Formatter;
+//# sourceMappingURL=json.d.ts.map

package/dist/formatters/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/formatters/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,aAAa,EAAE,SA2B3B,CAAC"}

package/dist/formatters/json.js

@@ -0,0 +1,25 @@
+import { ConversationSchema, } from "../types.js";
+export const jsonFormatter = {
+    extension: ".json",
+    format(conversation, options) {
+        const output = {
+            id: conversation.id,
+        };
+        if (options.includeMetadata) {
+            output.metadata = conversation.metadata;
+        }
+        output.messages = conversation.messages.map((msg) => {
+            if (!options.includeTimestamps) {
+                const { timestamp, ...rest } = msg;
+                return rest;
+            }
+            return msg;
+        });
+        return JSON.stringify(output, null, 2);
+    },
+    parse(content) {
+        const data = JSON.parse(content);
+        return ConversationSchema.parse(data);
+    },
+};
+//# sourceMappingURL=json.js.map

package/dist/formatters/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/formatters/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,SAAS,EAAE,OAAO;IAElB,MAAM,CAAC,YAA0B,EAAE,OAAoB;QACrD,MAAM,MAAM,GAA4B;YACtC,EAAE,EAAE,YAAY,CAAC,EAAE;SACpB,CAAC;QAEF,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5B,MAAM,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;QAC1C,CAAC;QAED,MAAM,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YAClD,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;gBAC/B,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;gBACnC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;CACF,CAAC"}

package/dist/formatters/markdown.d.ts

@@ -0,0 +1,3 @@
+import type { Formatter } from "../types.js";
+export declare const markdownFormatter: Formatter;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/formatters/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/formatters/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,SAAS,EAAwB,MAAM,aAAa,CAAC;AAmHjF,eAAO,MAAM,iBAAiB,EAAE,SAwD/B,CAAC"}

package/dist/formatters/markdown.js

@@ -0,0 +1,134 @@
+function formatMessage(message, includeTimestamps) {
+    const roleLabel = message.role.charAt(0).toUpperCase() + message.role.slice(1);
+    const timestamp = includeTimestamps && message.timestamp
+        ? ` _(${new Date(message.timestamp).toLocaleString()})_`
+        : "";
+    return `### ${roleLabel}${timestamp}\n\n${message.content}\n`;
+}
+function formatMetadata(conversation) {
+    const { metadata } = conversation;
+    const lines = [
+        "---",
+        `id: ${conversation.id}`,
+        `title: "${metadata.title}"`,
+        `created_at: ${metadata.createdAt}`,
+    ];
+    if (metadata.updatedAt) {
+        lines.push(`updated_at: ${metadata.updatedAt}`);
+    }
+    if (metadata.sourceApp) {
+        lines.push(`source_app: ${metadata.sourceApp}`);
+    }
+    if (metadata.tags && metadata.tags.length > 0) {
+        lines.push(`tags: [${metadata.tags.map((t) => `"${t}"`).join(", ")}]`);
+    }
+    lines.push("---\n");
+    return lines.join("\n");
+}
+function parseMetadata(frontmatter) {
+    const lines = frontmatter.split("\n").filter((l) => l.trim());
+    const data = {};
+    for (const line of lines) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim();
+        let value = line.slice(colonIndex + 1).trim();
+        if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1);
+        }
+        data[key] = value;
+    }
+    if (!data.id || !data.title || !data.created_at) {
+        return null;
+    }
+    let tags;
+    if (data.tags) {
+        const tagsMatch = data.tags.match(/\[(.+)\]/);
+        if (tagsMatch) {
+            tags = tagsMatch[1].split(",").map((t) => t.trim().replace(/^"|"$/g, ""));
+        }
+    }
+    return {
+        id: data.id,
+        metadata: {
+            title: data.title,
+            createdAt: data.created_at,
+            updatedAt: data.updated_at,
+            sourceApp: data.source_app,
+            tags,
+        },
+    };
+}
+function parseMessages(content) {
+    const messages = [];
+    const messageRegex = /### (User|Assistant|System)(?:\s+_\((.+?)\)_)?\s*\n\n([\s\S]*?)(?=\n### |$)/gi;
+    let match;
+    while ((match = messageRegex.exec(content)) !== null) {
+        const role = match[1].toLowerCase();
+        const timestampStr = match[2];
+        const messageContent = match[3].trim();
+        const message = {
+            role,
+            content: messageContent,
+        };
+        if (timestampStr) {
+            try {
+                const date = new Date(timestampStr);
+                if (!isNaN(date.getTime())) {
+                    message.timestamp = date.toISOString();
+                }
+            }
+            catch {
+                // Ignore invalid timestamps
+            }
+        }
+        messages.push(message);
+    }
+    return messages;
+}
+export const markdownFormatter = {
+    extension: ".md",
+    format(conversation, options) {
+        const parts = [];
+        if (options.includeMetadata) {
+            parts.push(formatMetadata(conversation));
+        }
+        parts.push(`# ${conversation.metadata.title}\n`);
+        if (conversation.metadata.summary) {
+            parts.push(`> ${conversation.metadata.summary}\n`);
+        }
+        parts.push("## Conversation\n");
+        for (const message of conversation.messages) {
+            parts.push(formatMessage(message, options.includeTimestamps));
+        }
+        return parts.join("\n");
+    },
+    parse(content) {
+        let id = crypto.randomUUID();
+        let metadata = {
+            title: "Untitled Conversation",
+            createdAt: new Date().toISOString(),
+        };
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (frontmatterMatch) {
+            const parsed = parseMetadata(frontmatterMatch[1]);
+            if (parsed) {
+                id = parsed.id;
+                metadata = parsed.metadata;
+            }
+            content = content.slice(frontmatterMatch[0].length);
+        }
+        const titleMatch = content.match(/^#\s+(.+)$/m);
+        if (titleMatch && metadata.title === "Untitled Conversation") {
+            metadata.title = titleMatch[1].trim();
+        }
+        const summaryMatch = content.match(/^>\s+(.+)$/m);
+        if (summaryMatch) {
+            metadata.summary = summaryMatch[1].trim();
+        }
+        const messages = parseMessages(content);
+        return { id, metadata, messages };
+    },
+};
+//# sourceMappingURL=markdown.js.map