hyper-mcp

一个快速、安全的MCP服务器，可通过WebAssembly插件扩展其功能。

它是什么？

hyper-mcp 让为你的应用添加AI功能变得简单。它与Claude Desktop、Cursor IDE以及其他兼容MCP的应用程序协同工作。你可以用自己喜欢的语言编写插件，通过容器注册表分发，并在任何地方运行——从云端到边缘设备。

特性

• 可以使用任何编译成WebAssembly的语言编写插件
• 通过标准OCI注册表（如Docker Hub）分发插件
• 基于 Extism 构建，提供稳固可靠的插件支持
• 使用WASM进行沙箱隔离：可限制网络、文件系统和内存访问
• 轻量级设计，适合资源受限的环境
• 支持stdio传输协议
• 部署灵活：无服务器、边缘计算、移动端、物联网设备等
• 开箱即用地支持跨平台
• 提供工具名称前缀，防止工具名称冲突
• 动态加载和卸载插件（可配置）

安全性

以安全为先的设计理念：

• 沙箱化的插件无法在未经许可的情况下访问你的系统
• 内存安全执行并设置资源限制
• 通过容器注册表安全地分发插件
• 对宿主函数进行细粒度的访问控制
• OCI插件镜像在发布时签名，在加载时通过 sigstore 进行验证。

快速开始

1. 创建配置文件：
   • Linux: $HOME/.config/hyper-mcp/config.json
   • Windows: {FOLDERID_RoamingAppData}\hyper-mcp\config.json。例如：C:\Users\Alice\AppData\Roaming\hyper-mcp\config.json
   • macOS: $HOME/Library/Application Support/hyper-mcp/config.json

{
  "plugins": {
    "time": {
      "url": "oci://ghcr.io/hyper-mcp-rs/time-plugin:latest",
      "description": "获取当前时间并进行时间计算"
    },
    "qr_code": {
      "url": "oci://ghcr.io/hyper-mcp-rs/qrcode-plugin:latest",
      "description": "根据文本生成二维码"
    },
    "hash": {
      "url": "oci://ghcr.io/hyper-mcp-rs/hash-plugin:latest"
    },
    "myip": {
      "url": "oci://ghcr.io/hyper-mcp-rs/myip-plugin:latest",
      "description": "获取你当前的公网IP地址",
      "runtime_config": {
        "allowed_hosts": ["1.1.1.1"]
      }
    },
    "fetch": {
      "url": "oci://ghcr.io/hyper-mcp-rs/fetch-plugin:latest",
      "runtime_config": {
        "allowed_hosts": ["*"],
        "memory_limit": "100 MB",
      }
    }
  }
}

📖 有关详细的配置选项，包括身份验证设置、运行时配置及高级功能，请参阅 RUNTIME_CONFIG.md

支持的URL方案：

• oci:// - 用于符合OCI标准的注册表（如Docker Hub、GitHub Container Registry等）需要COSIGN
• file:// - 用于本地文件
• http:// 或 https:// - 用于远程文件
• s3:// - 用于Amazon S3对象（需要在环境中配置AWS凭据）

2. 启动服务器：

$ hyper-mcp

• 使用stdio传输协议。
• 如果需要调试，可以设置RUST_LOG=debug。
• 如果加载未签名的OCI插件，需要将insecure_skip_signature标志或环境变量HYPER_MCP_INSECURE_SKIP_SIGNATURE设置为true。

以SSE/流式HTTP运行：为此，可以将hyper-mcp包裹在支持相应网络传输方式且为每个客户端连接创建hyper-mcp实例的代理中。

输出日志

hyper-mcp会自动将所有输出记录到每日滚动的日志文件中，以便进行调试和监控。

日志位置：

• Linux: $HOME/.config/hyper-mcp/logs/mcp-server.log
• Windows: {FOLDERID_RoamingAppData}\hyper-mcp\logs\mcp-server.log
• macOS: $HOME/Library/Application Support/hyper-mcp/logs/mcp-server.log

自定义日志路径：

可以通过设置HYPER_MCP_LOG_PATH环境变量来覆盖默认的日志目录：

export HYPER_MCP_LOG_PATH=/path/to/your/logs
hyper-mcp

日志级别：

使用RUST_LOG环境变量控制日志的详细程度：

# 信息级别（默认）
RUST_LOG=info hyper-mcp

# 调试级别（详细，适用于故障排除）
RUST_LOG=debug hyper-mcp

# 警告级别（仅显示警告和错误）
RUST_LOG=warn hyper-mcp

特点：

• 每日日志轮转（每天创建新文件）
• 非阻塞写入，避免影响性能
• 包含时间戳、行号和目标信息
• 适用于stdio传输（日志不会干扰MCP通信）

与Cursor IDE配合使用

你可以为所有项目全局配置hyper-mcp，也可以针对单个项目进行特定配置。

1. 对于项目范围的配置，在项目根目录下创建.cursor/mcp.json：

{
  "mcpServers": {
    "hyper-mcp": {
      "command": "/path/to/hyper-mcp"
    }
  }
}

2. 在Cursor的设置中配置hyper-mcp：

3. 通过聊天开始使用工具：

可用插件

我们维护了几款插件供你快速上手：

V1 插件

这些插件使用 v1 插件接口。虽然目前仍受支持，但新插件应使用 v2 接口。

• time：获取当前时间并进行时间计算（Rust）
• qr_code：生成二维码（Rust）
• hash：生成多种类型的哈希值（Rust）
• myip：获取当前 IP 地址（Rust）
• crypto_price：获取加密货币价格（Go）
• fs：文件系统操作（Rust）
• github：GitHub 插件（Go）
• eval_py：使用 RustPython 评估 Python 代码（Rust）
• arxiv：搜索并下载 arXiv 论文（Rust）
• memory：基于 SQLite 的内存存储与检索工具（Rust）
• sqlite：与 SQLite 数据库交互（Rust）
• crates-io：获取 crate 的基本信息及最新版本（Rust）
• gomodule：获取 Go 模块信息及版本号（Rust）
• qdrant：将记忆保存并检索至 Qdrant 向量搜索引擎（Rust）
• gitlab：GitLab 插件（Rust）
• meme_generator：表情包生成器（Rust）
• think：思考工具（Rust）
• maven：Maven 插件（Rust）
• serper：Serper 网页搜索插件（Rust）

V2 插件

这些插件使用 v2 插件接口。新插件应使用此接口。

• context7：查找库文档（Rust）
• defuddle：以 Markdown 格式提取任意页面的主要内容（Rust）
• fetch：基础网页抓取功能（Rust）
• monty：用 Rust 编写的极简且安全的 Python 解释器，专为 AI 使用（Rust）
• rstime：获取当前时间并进行时间计算（Rust）

社区构建的插件

• hackernews：该插件连接到 Hacker News API，获取当前热门新闻，并显示其标题、评分、作者和 URL。
• release-monitor-id：该插件从 release-monitoring.org 获取项目 ID，帮助跟踪已发布软件的版本。
• yahoo-finance：该插件连接到 Yahoo Finance API，根据公司名称或股票代码提供股票价格（OHLCV）。
• rand16：该插件生成随机 16 字节缓冲区，并以 base64uri 格式提供，非常适合在线对称加密。

文档

• 内置工具参考 — 包含以下 hyper_mcp-* 工具的文档：
  • hyper_mcp-list_plugins — 列出所有已加载的插件
  • hyper_mcp-load_plugin — 在运行时动态加载插件
  • hyper_mcp-unload_plugin — 在运行时动态卸载插件
• 运行时配置指南 — 关于配置选项的全面指南，包括：
  • 身份验证设置（Basic、Token 和 Keyring）
  • 插件运行时配置
  • 安全注意事项及最佳实践
  • 针对 macOS、Linux 和 Windows 的特定平台 Keyring 设置
  • 身份验证问题的故障排除
• 跳过工具模式指南 — 使用正则表达式模式过滤工具的全面指南：
  • 模式语法及示例
  • 常见用法及最佳实践
  • 针对不同环境的过滤策略
  • 高级正则表达式技术
  • 迁移与故障排除

创建插件

有关创建插件的完整说明，请参阅 CREATING_PLUGINS.md。

如需现成的 Rust 和 Go 插件模板，请参阅 TEMPLATES.md。

许可证

Apache 2.0

星标历史

hyper-mcp 快速上手指南

hyper-mcp 是一个快速、安全的 MCP（Model Context Protocol）服务器，支持通过 WebAssembly (WASM) 插件扩展 AI 能力。它兼容 Claude Desktop、Cursor IDE 等工具，允许你使用任意可编译为 WASM 的语言编写插件，并通过 OCI 镜像仓库分发。

环境准备

系统要求

• 操作系统：Linux, macOS, Windows
• 架构：跨平台兼容（x86_64, ARM64 等）

前置依赖

• Cosign：如果你计划从 OCI 仓库（如 GitHub Container Registry）加载插件，必须安装 cosign 用于验证插件签名。
  • 安装参考：Sigstore Cosign 安装文档
• MCP 客户端：已安装支持 MCP 协议的客户端（如 Cursor IDE 或 Claude Desktop）。

注意：国内开发者若访问 GitHub Container Registry (ghcr.io) 较慢，建议配置网络加速或使用支持代理的环境。目前官方未提供专门的国内镜像源。

安装步骤

1. 下载二进制文件 前往 GitHub Releases 页面，根据你的操作系统和架构下载最新的 hyper-mcp 二进制文件。

2. 赋予执行权限并移动路径

   Linux / macOS:

   chmod +x hyper-mcp
   sudo mv hyper-mcp /usr/local/bin/
   

   Windows: 将下载的 .exe 文件移动到环境变量包含的目录（例如 C:\Windows\System32 或自定义路径并添加到 PATH）。

3. 验证安装

   hyper-mcp --version
   # 或者直接运行查看帮助（若无版本参数）
   hyper-mcp
   

   注：首次运行若无配置文件可能会退出或报错，属正常现象，下一步将创建配置。

基本使用

1. 创建配置文件

hyper-mcp 需要配置文件来定义加载哪些插件。根据你的系统创建以下路径的 config.json 文件：

• Linux: $HOME/.config/hyper-mcp/config.json
• macOS: $HOME/Library/Application Support/hyper-mcp/config.json
• Windows: %APPDATA%\hyper-mcp\config.json (例如 C:\Users\Alice\AppData\Roaming\hyper-mcp\config.json)

示例配置 (config.json)： 复制以下内容到配置文件中，这将加载几个官方基础插件（时间、二维码、哈希等）：

{
  "plugins": {
    "time": {
      "url": "oci://ghcr.io/hyper-mcp-rs/time-plugin:latest",
      "description": "Get current time and do time calculations"
    },
    "qr_code": {
      "url": "oci://ghcr.io/hyper-mcp-rs/qrcode-plugin:latest",
      "description": "Generate QR codes from text"
    },
    "hash": {
      "url": "oci://ghcr.io/hyper-mcp-rs/hash-plugin:latest"
    },
    "fetch": {
      "url": "oci://ghcr.io/hyper-mcp-rs/fetch-plugin:latest",
      "runtime_config": {
        "allowed_hosts": ["*"],
        "memory_limit": "100 MB"
      }
    }
  }
}

安全提示：默认情况下，加载 OCI 插件需要签名验证。如果你在测试未签名的插件或遇到网络验证问题，可以设置环境变量跳过签名检查（生产环境慎用）：

export HYPER_MCP_INSECURE_SKIP_SIGNATURE=true

2. 启动服务器

在终端中直接运行：

hyper-mcp

• 默认使用 stdio 传输协议，适合被其他程序调用。
• 如需调试查看详细日志，可使用：

  RUST_LOG=debug hyper-mcp
  

3. 在 Cursor IDE 中集成

以 Cursor IDE 为例，将 hyper-mcp 接入开发环境：

1. 项目级配置：在你的项目根目录下创建 .cursor/mcp.json 文件：

   {
     "mcpServers": {
       "hyper-mcp": {
         "command": "/usr/local/bin/hyper-mcp" 
       }
     }
   }
   

   (Windows 用户请将 command 路径改为 hyper-mcp.exe 的实际路径)

2. 启用功能：重启 Cursor，打开聊天窗口。你现在可以在对话中调用配置中的工具，例如询问“生成一个包含 'Hello World' 的二维码”或“计算当前时间与明天的时间差”。

4. 查看日志

如果遇到错误，可以查看滚动日志文件进行排查：

• Linux/macOS: $HOME/.config/hyper-mcp/logs/mcp-server.log (macOS 路径略有不同，见上文环境准备部分)
• Windows: %APPDATA%\hyper-mcp\logs\mcp-server.log

你可以通过环境变量自定义日志路径：

export HYPER_MCP_LOG_PATH=/path/to/custom/logs