Raku MCP SDK

关键词

模型上下文协议服务器实现JSON-RPC资源管理工具执行

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个 MCP（Model Context Protocol）服务器端的完整解决方案，覆盖服务器端核心能力：托管资源、注册/执行工具、定义与渲染提示模板，以及基于 JSON-RPC 2.0 的通信协议实现。支持多种传输协议（如 Stdio、HTTP/2 SSE，含向后兼容的 SSE），并具备会话管理、能力宣告、订阅通知、任务与取消、以及扩展能力等特性。

  • 主要功能点

    • JSON-RPC 2.0 全面支持：请求/响应、错误处理、通知等标准化消息格式。
    • 传输实现：内置的 Stdio 传输、HTTP 传输（带 SSE 的流式能力），并提供兼容的历史 SSE 路径。
    • 资源、工具、提示管理：支持资源列表、读取；工具的定义、元数据、参数化输入/输出；提示（Prompts）的创建、获取与生成。
    • 分页与检索：对列表接口提供游标分页，适用于工具、资源、提示等的遍历。
    • 会话与权限：会话管理、能力声明、订阅更新等机制，便于多用户/多会话的安全协作。
    • 监听与通知：资源订阅、更新通知、进度和取消等通知能力。
    • 扩展能力（Extensions 框架，实验性实现）：通过实验能力协商进行扩展方法路由及能力对接。
    • 安全与认证：内置 OAuth 2.1 支持、PKCE、令牌管理、元数据发现与动态客户端注册。
    • 客户端示例：提供客户端与服务端交互示例，演示如何列出工具、调用工具、读取资源等典型场景。
    • 支持多语言与生态：提供与 MCP 官方 TypeScript/Python SDK 的对齐思路与互操作性参考。

  • 安装步骤

    • 先决条件：需要安装 Raku 环境与 zef 包管理工具（仓库使用 zef 安装 MCP 模块）。
    • 直接使用 zef 安装 MCP（模块级安装，适用于已准备好的运行环境）。
    • 或者从源码安装：
      • 克隆仓库
      • 进入仓库目录
      • 运行 zef install .
    • 参考 README 的快速起步示例，结合你自己的服务器入口脚本，实现并运行 MCP 服务器。

  • 服务器配置（MCP 客户端需要配置启动服务器的命令与参数，用于在客户端侧按需启动服务器进程并连接）

    • 服务器名称（serverName）用于 MCP 客户端在连接时的标识。
    • 启动命令（command）指定用来启动服务器的可执行文件或解释器。
    • 启动参数（args）给定启动服务器时的参数列表，包含入口脚本路径、库路径等。
    • 下面给出一个示意性的文本配置（JSON 形式文本，供参考，实际路径请以你实际部署为准）： { "serverName": "raku-mcp-server", "command": "raku", "args": [ "-Ilib", "path/to/server-entry.raku" ] } 注释说明：
    • serverName 指定客户端在连接时使用的可读标识。
    • command 指向可执行 MCP 服务器的解释器（本实现基于 Raku）。
    • args 为启动命令的参数，path/to/server-entry.raku 需要替换为实际入口脚本的位置，入口脚本中应按 README 的示例创建并启动 MCP 服务器实例。
    • 该配置仅用于 MCP 客户端在本地或远程执行服务器进程时的启动信息，客户端本身不需要解析内部实现细节。

  • 基本使用方法

    • 快速示例流程（按 README 的快速启动思路）：

      • 编写一个 Raku 脚本，创建 MCP::Server::Server 实例，指定实现信息、传输层（如 Stdio 或 HTTP Transport），并注册工具、资源、提示等能力。
      • 调用服务器的 serve（或等价的事件循环启动方法）进入事件循环，监听并响应来自 MCP 客户端的 JSON-RPC 请求。
      • 使用 MCP 客户端（示例代码中给出 API，如列出工具、调用工具、读取资源等）进行交互，观察服务器端的回传和通知。

    • 典型交互点（客户端操作，不需要关心实现细节）：

      • 列出可用工具、分页读取、调用工具并处理结果。
      • 读取资源、获取和渲染 Prompts、订阅资源更新通知、跟踪执行进度与取消行为。
      • 根据需要通过 Extensions 框架扩展能力、开启或关闭日志、调整进度/取消策略等。

  • 运行与验证

    • 通过 README 提到的示例和 Makefile 目标（如 run-example、http-server 等）来验证不同传输与场景的工作状态。
    • 使用集成测试与 CI 流水线进行验证，确保 JSON-RPC 消息处理、传输接入、资源/工具/提示管理等功能完整可用。

  • 备注

    • 本实现及示例以 MCP 规范为准，具体部署时请结合实际工作环境调整配置、路径、证书与鉴权等安全策略。

服务器信息

访问项目