Thread MCP

螺纹MCP

thread mcp是用于LLM的Jupyter笔记本，针对自然语言进行了优化。Thread可帮助您在不同的LLM客户端之间共享、复制、更新和恢复LLM对话。

特性

• 统一保存：本地存储会话（Markdown/JSON）或通过REST API远程存储会话
• 智能搜索：通过ID、标题、标签或带有相关性评分的全文搜索查找线程
• 轻松更新：按ID或标题附加消息-无需手动跟踪ID
• 恢复对话：加载具有针对AI延续进行了上下文优化的先前线程
• 元数据：包括时间戳、标签、摘要和源应用程序信息

演示

安装

npm install thread-mcp

或者从源代码安装：

git clone https://github.com/your-username/thread-mcp.git
cd thread-mcp
npm install
npm run build

用法

使用Claude Desktop进行配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thread-mcp": {
      "command": "npx",
      "args": ["thread-mcp"]
    }
  }
}

或者，如果从源代码安装：

{
  "mcpServers": {
    "thread-mcp": {
      "command": "node",
      "args": ["/path/to/thread-mcp/dist/index.js"]
    }
  }
}

使用克劳德代码/VS代码进行配置

添加a .mcp.json 将文件保存到项目根目录：

{
  "mcpServers": {
    "thread-mcp": {
      "command": "npx",
      "args": ["thread-mcp"],
      "env": {
        "THREAD_MCP_STORAGE_DIR": "./thread-mcp"
      }
    }
  }
}

看 .mcp.json.example 和 claude_desktop_config.json.example 对于模板。

配置

环境变量

使用环境变量配置MCP服务器。这些提供了可以在每次工具调用时覆盖的默认值。

优先

配置值按以下顺序解析（优先级从高到低）：

1. 工具调用参数 -如果请求中明确提供
2. 环境变量 -服务器级配置
3. 内置默认值 -硬编码回退

配置示例

{
  "mcpServers": {
    "thread-mcp": {
      "command": "npx",
      "args": ["thread-mcp"],
      "env": {
        "THREAD_MCP_STORAGE_DIR": "./threads",
        "THREAD_MCP_FORMAT": "markdown",
        "THREAD_MCP_DEFAULT_SOURCE": "local",
        "THREAD_MCP_REMOTE_URL": "https://api.example.com",
        "THREAD_MCP_API_KEY": "your-api-key",
        "THREAD_MCP_REMOTE_HEADERS": "{\"X-Custom-Header\": \"value\"}"
      }
    }
  }
}

笔记：

• 相对路径（例如。， ./threads)从启动MCP服务器的工作目录解析
• THREAD_MCP_REMOTE_HEADERS 必须是有效的JSON
• 工具调用参数与环境变量头合并（并覆盖）

使用示例

示例1：保存对话并稍后继续

用户提示： “保存这段关于我们API重新设计的对话，这样我明天就可以开始了。”

线程MCP调用 save_thread 对话内容：

{
  "title": "API Redesign Discussion",
  "messages": [
    {
      "role": "user",
      "content": "Let's redesign the /users endpoint to support pagination."
    },
    {
      "role": "assistant",
      "content": "Good idea. I'd suggest cursor-based pagination with a default page size of 25..."
    }
  ],
  "tags": ["api", "backend"],
  "summary": "Planning cursor-based pagination for the /users endpoint"
}

第二天，用户说：“继续API的重新设计对话。”

线程MCP调用 resume_thread，它返回完整的上下文——标题、摘要、标签、所有消息和延续提示——这样助手就可以准确地从您停止的地方继续。

示例2：搜索过去的对话

用户提示： “查找我之前关于数据库迁移的对话。”

线程MCP调用 find_threads 使用搜索查询：

{
  "query": "database migrations",
  "includeContent": false
}

预期产量：

{
  "totalResults": 2,
  "threads": [
    {
      "title": "Postgres Migration Strategy",
      "tags": ["database", "postgres"],
      "summary": "Discussed zero-downtime migration approach for production DB",
      "relevance": { "score": 85, "matchedFields": ["title", "content"] }
    },
    {
      "title": "MongoDB to SQL Migration",
      "tags": ["database", "migration"],
      "summary": "Planned schema mapping from MongoDB collections to SQL tables",
      "relevance": { "score": 72, "matchedFields": ["title", "tags"] }
    }
  ]
}

然后，用户可以通过标题或ID继续对话。

示例3：继续多会话对话

用户提示： “将今天的后续内容添加到我们的入职流程讨论中。”

线程MCP调用 update_thread 将新消息附加到现有线程：

{
  "title": "Onboarding Flow Redesign",
  "messages": [
    {
      "role": "user",
      "content": "We decided to add a progress bar. How should we implement it?"
    },
    {
      "role": "assistant",
      "content": "I'd recommend a stepper component with 4 stages: account, profile, preferences, confirmation..."
    }
  ]
}

预期产量：

{
  "success": true,
  "title": "Onboarding Flow Redesign",
  "messageCount": 8,
  "messagesAdded": 2,
  "mode": "append"
}

新消息附加了自动重复数据删除功能，因此即使消息已经保存，也不会被复制。

可用工具

save_thread

将新的对话线程保存到本地存储或远程服务器。

参数：

例子：

{
  "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

按ID、标题、搜索查询或列出所有线程查找已保存的线程。支持过滤和相关性评分。

参数：

示例：

列出所有线程：

{
  "source": "local"
}

按ID查找：

{
  "id": "abc123-def456"
}

使用筛选器搜索：

{
  "query": "Python debugging",
  "tags": ["code"],
  "includeMessages": true,
  "limit": 5
}

响应包括相关性元数据：

{
  "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

通过附加新消息来更新现有线程。按ID或标题查找线程。

参数：

示例-按标题附加：

{
  "title": "Code Review Discussion",
  "messages": [
    { "role": "user", "content": "What about error handling?" },
    { "role": "assistant", "content": "Good point! You should..." }
  ]
}

示例-使用新元数据按ID更新：

{
  "id": "abc123-def456",
  "messages": [{ "role": "user", "content": "Follow-up question..." }],
  "tags": ["code-review", "python", "error-handling"],
  "summary": "Extended discussion including error handling"
}

______________________________________________________________________

delete_thread

按ID或标题删除已保存的线程。

参数：

示例：

{
  "id": "abc123-def456"
}

{
  "title": "Old Discussion to Remove"
}

______________________________________________________________________

resume_thread

加载已保存的线程以继续对话。返回针对AI连续性优化的上下文。

参数：

输出格式：

• "structured" -具有元数据、消息和延续提示的有组织上下文
• "narrative" -适合上下文注入的人类可读摘要
• "messages" -仅原始消息数组

示例-按标题简历：

{
  "title": "Code Review Discussion",
  "format": "structured",
  "maxMessages": 10
}

结构化响应：

{
  "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
}

典型工作流程

1. 保存新线程 在一次重要的谈话之后：

   { "title": "Project Planning", "messages": [...], "tags": ["planning"] }

1. 稍后继续 -查找并恢复：

   { "title": "Project Planning" } // resume_thread

1. 添加新消息 随着对话的继续：

   { "title": "Project Planning", "messages": [new messages...] }  // update_thread

1. 跨线程搜索 查找相关上下文：

   { "query": "database schema", "tags": ["planning"] } // find_threads

输出格式

标记语言

使用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

生成结构化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"
    }
  ]
}

远程服务器API

使用远程存储时，您的服务器应实现以下端点：

POST /conversations

创建新对话。

请求正文：

{
  "id": "string",
  "title": "string",
  "content": "string (formatted content)",
  "format": "markdown | json",
  "metadata": { ... }
}

答复：

{
  "url": "https://your-server.com/conversations/id"
}

GET /conversations

列出所有对话。

GET /conversations/:id

进行一次特定的对话。

PUT /conversations/:id

更新对话（用于Update_thread）。

DELETE /conversations/:id

删除对话。

发展

先决条件

• Node.js 22+
• npm

设置

npm install

构建

npm run build

运行测试

npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # With coverage report

开发服务器

npm run dev

装订和格式化

npm run lint            # ESLint
npm run format          # Prettier format
npm run format:check    # Check formatting
npm run typecheck       # TypeScript type checking

项目结构

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

隐私

Thread MCP的设计考虑到了隐私：

• 默认情况下为本地 -所有对话数据都存储在本地文件系统上。除非明确配置远程存储，否则不会向外部服务发送任何数据。
• 远程存储是可选择的 -远程存储要求您提供自己的服务器URL(THREAD_MCP_REMOTE_URL).您可以控制数据的去向。
• 自动汇总/自动标记使用MCP采样 -启用后，这些功能将使用MCP采样功能，这意味着您的客户端自己的LLM将生成摘要和标签。服务器不进行额外的外部API调用。
• 无遥测或分析 -线程MCP不以任何方式收集使用数据、发送遥测数据或给家里打电话。
• 无第三方数据共享 -您的对话数据永远不会与第三方共享。

许可证

GPL-3.0

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试： npm test
5. 提交拉取请求