项目简介 Letta-Matrix MCP 服务器作为连接 Matrix 聊天平台和 Letta 智能体（AI Agent）系统的核心组件。它实现了 Model Context Protocol (MCP)，允许外部的 LLM 客户端以标准化的方式访问 Letta 智能体提供的功能、资源和Prompt模板。通过此服务器，LLM 客户端可以：

管理和访问与智能体相关的资源数据。
调用智能体定义的外部工具（如在 Matrix 房间发送消息、与其他智能体通信）。
利用 Prompt 模板来定制与智能体的交互模式。所有通信通过 JSON-RPC 协议进行，确保了 LLM 应用的安全、可扩展和上下文感知服务。

主要功能点

智能体管理与路由： 根据 Matrix 房间 ID 将消息准确路由到对应的 Letta 智能体，并管理智能体用户的 Matrix 账户。
Matrix 平台集成： 充当 Matrix 与 Letta 智能体之间的桥梁，处理 Matrix 消息的收发，并支持智能体在 Matrix 空间中创建和管理聊天房间。
MCP 协议支持： 实现 Model Context Protocol 的核心规范，允许 LLM 客户端通过 JSON-RPC 调用服务器提供的功能，包括资源访问、工具执行和 Prompt 渲染。
工具调用能力： 暴露如 'matrix_send_message' (向 Matrix 房间发送消息) 和 'matrix_agent_message' (向其他 Letta 智能体发送消息) 等工具，供 LLM 客户端通过 MCP 调用。
会话与认证管理： 负责维护客户端会话、处理认证，并支持持久化会话数据以实现无缝交互。
可扩展性： 支持多种传输协议（如 Stdio, SSE, WebSocket），为 LLM 应用提供灵活的部署选项。

安装步骤 由于仓库信息中只提供了测试和诊断脚本，并未包含完整的部署说明或 Dockerfile，以下为基于常见 Python 项目结构和 Matrix/Letta 生态推测的安装步骤。实际安装可能需要参考完整的项目文档。

克隆仓库：

git clone https://github.com/oculairmedia/Letta-Matrix.git
cd Letta-Matrix

设置Python环境： 建议使用 'venv' 或 'conda' 创建隔离的 Python 环境。

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt # 假设存在 requirements.txt 文件

安装数据库： 项目使用 PostgreSQL 存储智能体映射信息。请确保已安装并运行 PostgreSQL 数据库。

# 例如，使用 Docker 运行 PostgreSQL
docker run --name letta-postgres -e POSTGRES_USER=letta -e POSTGRES_PASSWORD=letta -e POSTGRES_DB=matrix_letta -p 5432:5432 -d postgres:latest

您需要根据实际情况创建 'matrix_letta' 数据库和 'letta' 用户（密码为 'letta'），或修改配置以匹配您的数据库凭据。

配置环境变量： 服务器需要多个环境变量来连接 Matrix Homeserver、Letta API 和数据库。创建一个 '.env' 文件或直接在环境中设置。

# .env 示例
MATRIX_HOMESERVER_URL=http://your_matrix_homeserver:8008 # Matrix homeserver URL
MATRIX_ADMIN_USER=admin # Matrix 管理员用户名
MATRIX_ADMIN_PASSWORD=your_admin_password # Matrix 管理员密码
MATRIX_USERNAME=@letta:your_matrix_domain.com # Letta Bot 的 Matrix 用户 ID
MATRIX_PASSWORD=letta_bot_password # Letta Bot 的 Matrix 密码
LETTA_API_URL=http://your_letta_api_server:8283 # Letta API 服务器 URL
LETTA_TOKEN=your_letta_api_token # 访问 Letta API 的认证令牌
DATABASE_URL=postgresql://letta:letta@localhost:5432/matrix_letta # 数据库连接字符串
MATRIX_DATA_DIR=/app/data # 用于存储会话和映射数据的目录
# 其他可能的配置，例如日志级别、调试模式等
LOG_LEVEL=INFO
DEV_MODE=false

运行迁移（如果需要）： 如果项目包含数据库迁移脚本（如 Alembic），请运行它们以设置数据库 schema。
```
# 假设有迁移工具
alembic upgrade head
```

服务器配置 (MCP 客户端所需)

MCP 客户端通常通过 JSON-RPC 协议与 MCP 服务器通信。以下是一个示例 JSON 配置，展示了 MCP 客户端如何连接到 Letta-Matrix 服务器：

{
  "server_name": "Letta-Matrix MCP Server",
  "command": "python",
  "args": [
    "src/main.py",          // 假设这是 MCP 服务器的启动文件，根据实际情况修改
    "--mcp-port", "8284",   // MCP 服务器监听的端口，可选
    "--log-level", "INFO"
  ],
  "env": {
    "MATRIX_HOMESERVER_URL": "http://your_matrix_homeserver:8008", // 您的 Matrix Homeserver URL
    "MATRIX_ADMIN_USER": "admin", // Matrix 管理员用户名
    "MATRIX_ADMIN_PASSWORD": "your_admin_password", // Matrix 管理员密码
    "MATRIX_USERNAME": "@letta:your_matrix_domain.com", // Letta Bot 的完整 Matrix 用户 ID
    "MATRIX_PASSWORD": "letta_bot_password", // Letta Bot 的 Matrix 密码
    "LETTA_API_URL": "http://your_letta_api_server:8283", // Letta API 服务器 URL
    "LETTA_TOKEN": "your_letta_api_token", // 访问 Letta API 的认证令牌
    "DATABASE_URL": "postgresql://letta:letta@localhost:5432/matrix_letta", // 数据库连接字符串
    "MATRIX_DATA_DIR": "/app/data" // 用于存储会话和映射数据的目录
  },
  "protocol": "stdio", // 或 "websocket", "sse" 等，取决于服务器支持的传输协议
  "features": {
    "resources": ["agent_mappings", "matrix_rooms"], // 服务器提供的资源，例如智能体映射、Matrix 房间信息
    "tools": ["matrix_send_message", "matrix_agent_message"], // 服务器提供的工具，例如发送 Matrix 消息、智能体间消息
    "prompts": ["default_agent_prompt"] // 服务器提供的 Prompt 模板
  }
}

server_name: 为您的 Letta-Matrix MCP 服务器命名。
command: 启动 MCP 服务器的主命令，例如 'python'。
args: 传递给 'command' 的参数列表。
- 'src/main.py': 启动服务器的主 Python 文件路径，这需要根据实际项目结构来确认。
- '--mcp-port': MCP 服务器监听的端口号，如果服务器默认使用某个端口，此项可选。
- '--log-level': 日志级别。
env: MCP 服务器运行所需的环境变量。请将 'your_matrix_homeserver'、'your_matrix_domain.com'、'your_admin_password'、'letta_bot_password'、'your_letta_api_server'、'your_letta_api_token' 替换为您的实际配置。
protocol: MCP 客户端与服务器通信的传输协议，例如 'stdio' (标准输入输出)、'websocket' 或 'sse'。
features: 服务器声明支持的 MCP 功能，包括可用的 'resources' (资源)、'tools' (工具) 和 'prompts' (Prompt模板)。这部分需要根据实际服务器实现进行调整。

基本使用方法

启动 MCP 服务器： 根据您的部署方式，启动 Letta-Matrix MCP 服务器。例如，在命令行中：

# 确保在项目根目录且激活了虚拟环境
python src/main.py # 假设 src/main.py 是服务器启动文件

配置 LLM 客户端： 使用上述“服务器配置”示例 JSON 片段来配置您的 LLM 客户端（例如，一个支持 MCP 的 LLM 框架或集成环境），使其能够连接到 Letta-Matrix MCP 服务器。
LLM 客户端交互： 一旦连接成功，LLM 客户端可以开始通过 MCP 协议向 Letta-Matrix 服务器发送请求：
- 获取资源： 例如，请求智能体的映射信息或 Matrix 房间列表。
- 调用工具： LLM 可以通过调用 'matrix_send_message' 工具，向指定的 Matrix 房间发送消息；或调用 'matrix_agent_message' 与其他 Letta 智能体进行对话。
- 渲染 Prompt： 使用服务器定义的 Prompt 模板来格式化 LLM 的输入。

关键词

信息