MCP Agent Mail

关键词

模型上下文协议资源管理工具执行JSON-RPCHTTP API

使用说明（简要、便于快速上手）

  • 项目简介

    • 该仓库实现了一个基于 MCP 协议的后端服务器，用于向 LLM 客户端提供统一的资源访问、工具调用以及可渲染的 Prompt 模板等能力，并通过 JSON-RPC 方式进行通信，同时提供人机友好的 Web UI 以便人工审阅和管理。

  • 主要功能点

    • Resource（资源层）：提供对项目内数据的标准化读取接口，便于 LLM 客户端获取上下文数据和历史信息。
    • Tools（工具层）：注册并执行外部功能，LLM 可以通过调用这些工具实现外部任务。
    • Prompts（提示模板/渲染）：定义和渲染用于与 LLM 交互的提示模板，支持可定制的交互模式。
    • JSON-RPC 协议通信：客户端通过 JSON-RPC 请求服务器执行工具、读取资源、获取或渲染 Prompt。
    • 会话与能力声明：服务器端维护会话、用户/代理能力，以及多传输协议支持。
    • 多传输与 UI 支持：HTTP/HTTPS 传输、Web UI、以及可选的 SSE/WebSocket 等传输扩展（文档中指出为 HTTP-only FastMCP，UI 作为人机界面提供）。
    • 审计与安全：Git + SQLite 的双重持久化，支持审计、 leases（文件/资源的临时占用），以及权限控制等。
    • 安全特性与容错：ACL/RBAC、JWT/Bearer Token 认证、错误处理、并发与锁的保护机制、以及诊断工具。

  • 安装步骤（简化版）

    • 准备环境：需要 Python（仓库文档推荐 Python 3.14）以及依赖工具。建议在虚拟环境中执行。
    • 获取代码：克隆本仓库到本地或服务器。
    • 安装依赖并准备环境：按照项目文档的启动方案设置虚拟环境并安装所需依赖。
    • 启动服务器：按照仓库提供的启动方式之一启动 MCP HTTP 服务器（示例方式见文档中的启动命令，如通过 uvicorn/uvrun 运行 mcp_agent_mail.http，监听指定 host/port）。
    • 配置与启动脚本：按照文档提供的脚本与配置选项进行端口、路径等配置，确保服务器能够对外提供 MCP 接口。
    • 客户端接入：MCP 客户端通过提供的服务器信息（名称、启动命令与参数）进行连接。配置示例（JSON）将在下一小节给出。

  • 服务器配置（给 MCP 客户端的连接信息，格式为 JSON，包含 server name、command、args 等；非代码片段，便于人读）

    • server_name: "MCP Agent Mail HTTP API"
    • command: "uvicorn"
    • args: ["mcp_agent_mail.http:build_http_app", "--factory", "--host", "0.0.0.0", "--port", "8765"]
    • 注释说明：这是服务器对外暴露的 MCP HTTP API 启动配置参数，客户端只需要知道该服务器的名称、启动命令及参数以建立连接。具体的监听地址、端口号可按实际部署调整，确保与客户端一致。

  • 基本使用方法

    • 启动后，LLM 客户端通过 MCP 的 HTTP API 发送 JSON-RPC 请求来读取资源、调用工具、获取或渲染 Prompts。
    • 客户端可以通过资源端点（Resource）、工具端点（Tools）以及 Prompts 端点来获取需要的上下文信息、执行外部功能以及获取/渲染模板。
    • 服务器端负责会话管理、能力声明、以及对多种传输协议的支持，确保上下文服务对 LLM 应用是安全、可扩展的。

  • 额外说明

    • 本实现包含完整的服务器端代码、测试用例和若干辅助工具，旨在提供一个可运行的 MCP 服务器实现，而非仅仅示例或学习材料。
    • 如需快速验证，可参考仓库中的测试用例与文档中的快速启动说明进行实践。

服务器信息

访问项目