使用说明

项目简介

Ragaman 是一个利用检索增强生成（RAG）技术构建的个人笔记管理系统。它不仅可以通过传统的 REST API 访问，还实现了 Model Context Protocol (MCP) 服务器，使得大型语言模型（LLM）客户端能够以标准化的方式与之交互，获取上下文信息和执行笔记管理功能。

主要功能点

笔记管理: 支持创建、检索、更新和删除个人笔记。
语义搜索: 利用 OpenAI 的嵌入模型，实现基于内容相似度的笔记搜索功能。
MCP 协议支持: 实现了 MCP 服务器，可以通过标准的 JSON-RPC 协议与 LLM 客户端进行通信，提供笔记管理和搜索工具。
多种传输协议: 支持 Stdio 和 HTTP 两种 MCP 传输协议。

安装步骤

由于该仓库没有提供明确的安装步骤，通常的 Python 项目，可以按以下步骤尝试：

克隆仓库:

git clone https://github.com/npiv/ragaman.git
cd ragaman

配置环境变量: Ragaman 依赖以下环境变量进行配置，请根据需要设置：
- 'OPENAI_API_KEY': 您的 OpenAI API 密钥，用于文本嵌入。（必需）
- 'DB_PATH': SQLite 数据库文件路径，默认为 'notes.db'。
- 'EMBEDDING_MODEL': OpenAI 嵌入模型名称，默认为 'text-embedding-3-small'。
- 'MCP_NAME': MCP 服务器名称，默认为 'ragaman'。
- 'MCP_TRANSPORT': MCP 传输模式，可选 'stdio' 或 'http'，默认为 'stdio'。
- 'MCP_HTTP_PORT': MCP HTTP 服务器端口，仅当 'MCP_TRANSPORT' 为 'http' 时有效，默认为 '8080'。
您可以通过导出环境变量或在运行环境中设置这些变量。例如，在 Linux/macOS 系统中，可以编辑 '.bashrc' 或 '.zshrc' 文件添加 'export OPENAI_API_KEY=YOUR_API_KEY' 等配置。

服务器配置

为了使 MCP 客户端能够连接到 Ragaman MCP 服务器，您需要提供如下配置信息。这是一个 JSON 格式的配置示例，客户端需要根据此配置启动和连接服务器：

{
  "serverName": "ragaman",
  "command": "python",
  "args": [
    "-m",
    "ragaman.main",
    "--transport",
    "<transport_mode>"  //  传输模式，根据实际需要选择 "stdio" 或 "http"
  ],
  "transport": "<transport_mode>" // 传输模式，与 args 中保持一致
}

配置参数说明:

'serverName': MCP 服务器的名称，这里应为 'ragaman'。
'command': 启动服务器的命令，通常为 'python'。
'args': 启动命令的参数列表，包括：
- '-m ragaman.main': 运行 'ragaman.main' 模块作为主程序。
- '--transport <transport_mode>': 指定 MCP 服务器的传输模式，需要替换为 'stdio' 或 'http'。
'transport': 与 'args' 中指定的传输模式保持一致，表明客户端期望使用的传输方式。

基本使用方法

启动 MCP 服务器: 根据您选择的传输模式 ('stdio' 或 'http')，配置并启动 Ragaman MCP 服务器。例如，使用 Stdio 传输，在终端中运行：

export OPENAI_API_KEY=YOUR_API_KEY  # 如果尚未设置 OpenAI API 密钥
python -m ragaman.main --transport stdio

或者使用 HTTP 传输：

export OPENAI_API_KEY=YOUR_API_KEY  # 如果尚未设置 OpenAI API 密钥
python -m ragaman.main --transport http

使用 MCP 客户端: 使用任何兼容 MCP 协议的客户端（例如 'mcp-cli' 或在 LLM 应用中集成 MCP 客户端库），根据上面提供的服务器配置信息连接到 Ragaman MCP 服务器。
调用 MCP 工具: 连接成功后，您可以使用客户端调用 Ragaman 提供的 MCP 工具，例如：
- 'create_note': 创建新笔记。
- 'get_note': 根据 ID 获取笔记。
- 'get_all_notes': 获取所有笔记。
- 'delete_note': 根据 ID 删除笔记。
- 'search_notes': 根据关键词搜索相似笔记。
具体工具的使用方法请参考 MCP 客户端的文档和 Ragaman 项目 'src/ragaman/mcp_server.py' 文件中 '@mcp.tool()' 注解的函数定义。

关键词

使用说明

信息