使用说明

项目简介

imessage-mcp 是一个基于 Model Context Protocol (MCP) 构建的服务器，它作为一个应用后端，主要功能是让 LLM 客户端能够访问和检索用户的 iMessage 消息记录。该服务器通过语义搜索技术，帮助 LLM 理解用户 iMessage 中的内容，从而为 LLM 应用提供更丰富的个人上下文信息。

主要功能点

iMessage 消息检索: 通过自然语言查询，在用户的 iMessage 历史记录中进行语义搜索，找到相关的消息片段。
指定会话搜索: 允许在特定的 iMessage 会话中进行搜索，缩小搜索范围，提高检索精度。
语义相似性: 使用语义向量数据库 (ChromaDB) 存储和检索消息，能够理解查询的含义，而不仅仅是关键词匹配。
MCP 工具集成: 以 MCP 工具的形式向 LLM 客户端暴露 iMessage 搜索功能，方便 LLM 应用调用。

安装步骤

克隆仓库

git clone https://github.com/willccbb/imessage-mcp.git
cd imessage-mcp

安装 Python 依赖 确保你的 Python 环境中安装了必要的库。建议创建一个虚拟环境：

python -m venv venv
source venv/bin/activate  # 或 venv\Scripts\activate for Windows
pip install fastapi uvicorn chromadb pydantic python-dotenv polars requests sentence-transformers mcp-server

准备 iMessage 数据
- 'chat.db': 从你的 Mac 电脑中复制 'chat.db' 文件。该文件通常位于 '~/Library/Messages/chat.db'。将其复制到 'imessage-mcp' 仓库的根目录下。
- 'contacts.abbu': 导出你的 Mac 联系人应用为 'Address Book Archive' 文件 ('.abbu')。在“联系人”应用中，选择 “文件” -> “导出” -> “通讯录归档...”，保存为 'contacts.abbu' 到 'imessage-mcp' 仓库的根目录下。
启动 ChromaDB 向量数据库服务器 在 'chroma-imessage' 目录下，启动 ChromaDB 服务器：
```
cd chroma-imessage
python app.py
```
保持此终端窗口运行，ChromaDB 服务器默认监听 'http://localhost:8000'。
处理 iMessage 数据并生成向量嵌入 回到仓库根目录 'imessage-mcp'，运行数据处理脚本，提取 iMessage 消息并生成向量嵌入，存储到 ChromaDB 服务器中：
```
cd .. # 返回仓库根目录
python main.py
```
或者，如果你已经有 CSV 格式的聊天记录，可以使用以下命令加载：
```
python load_chats_to_db.py
```
这个过程可能需要一些时间，取决于你的 iMessage 数据量。
启动 MCP 服务器 进入 'imessage_service/src/imessage_service' 目录，启动 MCP 服务器：
```
cd imessage_service/src/imessage_service
python server.py
```
保持此终端窗口运行，MCP 服务器将通过标准输入/输出 (stdio) 与 MCP 客户端通信。

服务器配置

以下 JSON 配置信息可用于 MCP 客户端连接到 imessage-mcp 服务器。

{
  "servers": [
    {
      "name": "imessage-mcp",
      "command": "python",
      "args": [
        "-u",
        "imessage_service/src/imessage_service/server.py"
      ],
      "description": "iMessage 消息检索 MCP 服务器"
    }
  ]
}

配置参数说明:

'name': 服务器的名称，可以自定义，例如 "imessage-mcp"。
'command': 启动服务器的命令，这里使用 'python' 解释器。
'args': 传递给 'python' 命令的参数列表。
- '"-u"': Python 的 '-u' 参数，用于强制 stdout 和 stderr 流不缓冲，确保 MCP 客户端能及时接收服务器输出。
- '"imessage_service/src/imessage_service/server.py"': MCP 服务器脚本的路径。
'description': 服务器的描述信息，方便用户理解服务器的功能。

MCP 客户端需要配置以上 JSON 信息，才能正确启动和连接到 imessage-mcp 服务器。 具体的配置方法请参考你使用的 MCP 客户端的文档。

基本使用方法

成功启动 MCP 服务器并配置到 MCP 客户端后，你可以在 LLM 应用中通过以下工具来搜索 iMessage 消息：

'search_messages' 工具: 用于在所有 iMessage 历史记录中进行搜索。

输入参数:
- 'query' (必填): 要搜索的自然语言查询语句，例如 "最近和张三聊了什么机器学习的内容"。
- 'n_results' (可选): 返回的消息片段数量，默认为 10。
- 'category' (可选): 消息类别过滤器 (目前可能未实现或未有效使用)。

工具调用示例 (JSON 格式):

{
  "tool_calls": [
    {
      "id": "tool_call_id_1",
      "type": "function",
      "function": {
        "name": "search_messages",
        "arguments": "{\"query\": \"下周开会时间\", \"n_results\": 5}"
      }
    }
  ]
}

'search_chat' 工具: 用于在指定的 iMessage 会话中进行搜索。

输入参数:
- 'query' (必填): 要搜索的自然语言查询语句。
- 'chat_id' (必填): 要搜索的会话 ID。会话 ID 的获取方式可能需要根据具体客户端或工具而定。
- 'n_results' (可选): 返回的消息片段数量，默认为 10。