使用说明

项目简介

TweetSave MCP 服务端是一个遵循 MCP (Model Context Protocol) 的后端服务，专注于将 Twitter/X 内容分析与博客生成能力以统一的工具集暴露给 LLM 客户端。它通过 MCP 提供的工具接口，支持读取单条 tweet、获取 tweet 线程、将 tweet 转换成博客格式、批量获取、以及提取媒体等多种操作，并通过标准化的传输通道与客户端通信，方便在 LLM 场景中进行上下文管理与功能调用。

主要功能点

工具集注册与暴露
- tweetsave_get_tweet：获取单条 tweet 的文本、作者、媒体、互动等信息，并可输出为 Markdown 或 JSON。
- tweetsave_get_thread：获取 tweet 线程（若支持）并输出为 Markdown 或 JSON。
- tweetsave_to_blog：将 tweet 转换为格式化的博客文章，包含媒体、标签、阅读时间、参与度等信息。
- tweetsave_batch：批量获取多条 tweet 的内容，输出为 Markdown 或 JSON。
- tweetsave_extract_media：提取 tweet 中的媒体（图片、视频等）的直接下载 URL。
传输模式
- 标准输入输出（stdio）传输，适合本地开发与嵌入式脚本场景。
- HTTP + SSE 传输，适合部署为远程服务供 MCP 客户端连接。
会话与服务能力
- 自动注册工具、建立 MCP 服务端、基于传输通道进行 JSON-RPC 请求/响应处理。
- 提供健康检查端点、SSE 会话管理、以及对 MCP 客户端的消息转发。

安装步骤

1. 克隆或下载代码到本地
1. 安装依赖
- 使用 npm 或 yarn 安装项目所需依赖（例如：axios、zod、模型上下文协议 SDK 等）。
1. 构建与运行
- 根据项目的构建脚本，将 TypeScript 源代码编译为 JavaScript（通常输出到 dist 目录）。
- 运行入口有两种：
  - stdio 传输入口：dist/index.js
  - HTTP SSE 传输入口：dist/http-server.js
- 启动后服务器将监听默认端口（HTTP 服务器示例为 3000，stdio 模式默认通过标准输入输出进行交互）。

服务器配置（MCP 客户端所需）

MCP 客户端需要通过 JSON 配置来连接 MCP 服务器。本仓库提供两种可能的启动方式，客户端配置时可任意选择其一：

标准输入/输出模式（stdio） { "server_name": "tweetsave-mcp-server-stdio", "command": "node", "args": ["dist/index.js"], "description": "通过标准输入输出与 MCP 客户端通信的本地运行模式" } 注释说明：
server_name: 唯一标识服务器的名称，便于客户端区分与管理。
command: 启动命令，使用 Node.js 运行编译输出的入口文件。
args: 入口参数，指向编译输出的 stdio 入口。
description: 该模式下，无需网络传输，只通过父进程的标准输入输出进行消息往返。
HTTP SSE 模块模式（remote HTTP） { "server_name": "tweetsave-mcp-server-http", "command": "node", "args": ["dist/http-server.js"], "description": "通过 HTTP+SSE 传输与 MCP 客户端通信的服务端模式（对外提供 /sse 与 /messages 接口）" } 注释说明：
server_name、command、args 的含义同上。
description 描述该模式下的对外端点与传输方式，MCP 客户端通过 SSE 连接服务器实现 JSON-RPC 通信，后续通过 /messages 进行请求与响应。

说明：MCP 客户端实际使用时只需要以上任一配置中的 server_name、command、args 即可，无需额外的客户端代码。本仓库还实现了健康端点、SSE 会话管理及对外 API 的直连接口。

基本使用方法

启动方式
- 选择 stdio 模式或 HTTP SSE 模式启动相应入口文件（编译后 dist 目录下的入口）。
- 启动后，客户端可以通过 MCP 协议向工具集发起请求，请求格式遵循 MCP 标准的 JSON-RPC 风格。
客户端连接与交互
- 使用 SSE 的 MCP 客户端：通过 /sse 建立会话，然后使用 /messages 发送 JSON-RPC 请求，接收服务器响应。
- 使用 stdio 的 MCP 客户端：通过标准输入输出进行请求和响应的文本交换。
功能使用示例（对接 MCP 客户端时的操作要点）
- 获取单条 tweet 的信息并输出 Markdown：调用 tweetsave_get_tweet 工具，传入 tweet 的 URL/ID 及输出格式。
- 将 tweet 转换为博客文章：调用 tweetsave_to_blog，传入 tweet 的 URL/ID、是否包含互动数据等标志，以及输出格式。
- 批量获取：调用 tweetsave_batch，传入要分析的 tweet URL/ID 列表及输出格式。
- 提取媒体：调用 tweetsave_extract_media，传入 tweet 的 URL/ID 与需要的媒体类型。

TweetSave MCP 服务端