Poznote MCP Server

关键词

Model Context ProtocolAI assistantsnotes APImulti-userJSON-RPC

使用说明（简要，面向开发与运维人员）：

  • 项目简介

    • Poznote 的 MCP 服务器组件，基于 Model Context Protocol (MCP) 提供资源、工具与交互能力，便于 LLM 客户端以统一的 JSON-RPC 方式获取笔记数据、执行操作、以及进行工作区/文件夹等管理。

  • 主要功能点

    • 资源管理：读取和列出笔记、获取具体笔记内容、工作区与文件夹信息、以及与笔记相关的附件、标签等元数据。
    • 工具执行：提供多种工具函数，例如获取笔记、列出笔记、搜索笔记、创建/更新/删除笔记、创建/列出/重命名文件夹、管理工作区等，方便 LLM 进行上下文驱动的操作。
    • 安全与多用户：支持多用户数据分离，通过会话、用户标识与权限控制进行访问，具备基于环境变量的配置和对齐 Poznote Web 端的认证体系。
    • 通信协议与传输：通过 FastMCP 实现 MCP 服务器，默认在 HTTP streamable 模式下与 MCP 客户端进行 JSON-RPC 请求/响应。
    • 部署友好：提供可执行入口，支持通过 CLI 启动（如 poznote-mcp serve --host 0.0.0.0 --port 8045），并且与 Poznote 的多组件生态协同工作。

  • 安装步骤

    • 准备环境
      • 确保系统上安装了 Python 3.x（推荐 Python 3.11 及以上）。
      • 安装所需的 MCP 库及依赖（如 FastMCP、mcp 相关包）。
    • 获取代码
      • 将仓库克隆到本地或服务器：包含 mcp-server 子目录下的实现代码。
    • 运行服务
      • 进入 mcp-server 目录，执行服务启动命令（示例，实际请以项目文档为准）： poznote-mcp serve --host 0.0.0.0 --port 8045
      • 服务器将以 streamable-http 传输方式暴露，LLM 客户端通过 JSON-RPC 与之交互。
    • 配置与证书
      • 如需通过环境变量定制 HOST、PORT、以及 Poznote API 的访问位置，请参考项目中的环境变量配置方式。
      • MCP 客户端无需本地修改代码，只需通过配置文件提供服务器信息即可连接。

  • 服务器配置（MCP 客户端需要的被动配置信息，示例为 JSON 描述，实际客户端不需要在代码中执行） { "server_name": "poznote-mcp", "command": "poznote-mcp", "args": [ "serve", "--host", "0.0.0.0", "--port", "8045" ], "transport": "streamable-http", "description": "MCP 服务端用于 Poznote 的笔记上下文、工具与提示交互的 JSON-RPC 通道" } 说明：

    • server_name：服务器标识，便于客户端在多服务器场景中区分。
    • command/args：用于启动服务器的命令及参数；MCP 客户端不需要对该字段执行代码，只用于生成运行指令示例。
    • transport：传输模式，此实现使用 streamable-http（HTTP 流传输）作为 MCP 要求的传输之一。
    • 备注：客户端无需在此处直接运行该命令；本字段用于描述如何在自动化环境中启动 MCP 服务器。

  • 基本使用方法

    • 客户端侧：通过 MCP 客户端（示例库）向 poznote-mcp 服务器发起 JSON-RPC 请求，调用工具、查询笔记、读取资源等。
    • 典型用例（由客户端发起的请求类型）：
      • list_notes(workspace, limit, user_id) 读取指定工作区的笔记列表
      • get_note(id, workspace, user_id) 获取指定笔记的完整内容
      • search_notes(query, workspace, limit, user_id) 按文本查询笔记
      • create_note(title, content, workspace, tags, folder, note_type, user_id) 新建笔记
      • update_note(id, workspace, content, title, tags, user_id) 更新现有笔记
      • delete_note(id, workspace, user_id) 删除笔记
    • 传输与兼容性：通过 Streamable HTTP 传输实现 JSON-RPC 的流式交互，适合与 LLM 框架的异步对话场景对接。

  • 备注与扩展

    • MCP 服务器的实现遵循 Poznote 的多用户数据模型，结合 notes, folders, workspaces 等实体，具备基本的资源、工具集合以及对外暴露的接口集合。
    • 如需自定义 Prompts、扩展 Tools、或定义新的资源，建议基于现有 Tools 架构扩展新的工具函数和资源定义。

服务器信息

访问项目