omi-mcp

🚀 Omi MCP 服务器

此项目提供了一个与 Omi API 交互的 Model Context Protocol (MCP) 服务器。该服务器为用户提供了读取对话和记忆、创建新对话和记忆的工具，方便与 Omi API 进行数据交互。

🚀 快速开始

安装完成后，运行以下命令启动服务器：

npm start

启动成功后，您可以访问 http://localhost:3000 使用提供的测试客户端。

✨ 主要特性

• 提供与 Omi API 交互的 MCP 服务器。
• 支持读取对话和记忆、创建新对话和记忆的功能。
• 内置日志记录功能，方便调试和监控服务器活动。

📦 安装指南

依赖项

• Node.js (版本要求：14.17.0 或更高)
• npm (版本要求：6.0.0 或更高)

安装步骤

1. 克隆仓库：

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. 安装依赖项：

   npm install
   

3. 创建包含以下变量的 .env 文件：
   • OMI_API_KEY: Omi API 的密钥
   • PORT: 服务器运行的端口（默认为 3000）

环境变量配置

创建一个 .env 文件并添加以下内容：

OMI_API_KEY=your-api-key-here
PORT=3000

💻 使用示例

基础用法

获取对话

GET /conversations?userId=test-user-123

获取记忆

GET /memories?userId=test-user-123

创建对话

{
  "content": "这是一个新的对话",
  "source": "message",
  "startedAt": "2024-01-01T00:00:00Z",
  "finishedAt": "2024-01-01T01:00:00Z",
  "language": "en",
  "geolocation": {
    "latitude": 0,
    "longitude": 0
  },
  "sourceSpec": "测试创建对话"
}

创建记忆

{
  "text": "这是一些文本内容",
  "memories": [
    {
      "content": "这是一条记忆",
      "tags": ["测试"]
    }
  ],
  "source": "other_text",
  "sourceSpec": "测试创建记忆"
}

📚 详细文档

工具说明

获取对话

• 请求 URL：GET /conversations
• 查询参数：
  • userId: 必填，字符串类型，用户 ID。
• 响应格式：

{
  "data": [
    {
      "id": string,
      "content": string,
      "source": string,
      "createdAt": string,
      "updatedAt": string
    }
  ],
  "message": string
}

获取记忆

• 请求 URL：GET /memories
• 查询参数：
  • userId: 必填，字符串类型，用户 ID。
• 响应格式：

{
  "data": [
    {
      "id": string,
      "content": string,
      "tags": [string],
      "source": string,
      "createdAt": string,
      "updatedAt": string
    }
  ],
  "message": string
}

创建对话

• 请求方法：POST /conversations
• 请求体参数：

{
  "content": string,        // 对话内容
  "source": string,         // 内容来源，可选值：audio_transcript、message、other_text
  "startedAt": string,      // 开始时间（ISO 8601 格式）
  "finishedAt": string,     // 结束时间（ISO 8601 格式）
  "language": string,       // 语言代码，默认为 en
  "geolocation": {
    "latitude": number,     // 纬度坐标
    "longitude": number     // 经度坐标
  },
  "sourceSpec": string      // 内容来源的额外说明
}

创建记忆

• 请求方法：POST /memories
• 请求体参数：

{
  "text": string,          // 文本内容（可选）
  "memories": [
    {
      "content": string,    // 内容
      "tags": [string]     // 标签数组（可选）
    }
  ],
  "source": string,         // 内容来源（可选）
  "sourceSpec": string      // 内容来源的额外说明（可选）
}

测试

使用提供的测试客户端进行测试：

node test-mcp-client.js

这将启动一个交互式测试客户端，允许您执行以下操作：

1. 获取对话
2. 获取记忆
3. 创建对话
4. 退出 所有操作均使用默认测试用户 ID (test-user-123)。

日志记录

MCP 服务器包含内置的日志记录功能，默认将日志输出到控制台和文件中。这对于调试和监控服务器活动非常有用。

日志文件位置

日志写入 logs/mcp-server.log 文件。日志内容包括：

• 服务器启动和关闭
• 所有 API 请求和响应
• 错误消息和堆栈跟踪
• Omi API 调用记录
• 请求参数和响应数据

查看日志

使用以下命令实时查看日志：

tail -f logs/mcp-server.log

日志格式

每条日志记录的格式如下：

[2024-03-21T12:34:56.789Z] Log message here

时间戳采用 ISO 8601 格式，便于事件关联和调试。