Hookmark MCP 服务器

关键词

Hookmarkhook URLsbidirectional linksmacOS automationCLI integration

使用说明（Markdown格式）

  • 项目简介

    • 本仓库实现了一个 Hookmark 的 MCP 服务器，将 Hookmark 的 CLI（hook）作为 MCP 工具对外暴露，使 Claude Code 等 MCP 客户端能够通过标准的 JSON-RPC 调用来创建、查询、管理 Hookmark 的链接（hook），并执行诸如链接、克隆、前台应用取 Hook URL 等操作。服务器基于 Model Context Protocol（MCP）实现，与客户端通过标准的 MCP 传输（本实现使用标准输入输出 Stdio 传输）进行通讯。

  • 主要功能点

    • 将 Hookmark CLI 封装为 MCP 工具，暴露以下操作：
      • hookmark_link：为文件/URL 生成 hook:// URL
      • hookmark_connect：在两个项目间建立双向链接
      • hookmark_list：列出某项的所有链接
      • hookmark_search：按关键词搜索书签
      • hookmark_remove：移除两项之间的链接
      • hookmark_clone：将一个项的链接克隆到另一个项
      • hookmark_frontmost：获取前台应用当前项的 hook:// URL
    • 支持通过环境变量 HOOK_CLI 指定 Hookmark 的 CLI 路径
    • 使用 MCP 标准的 JSON-RPC 格式进行请求/响应，错误输出统一封装
    • 提供对 macOS Hookmark 应用的自动化集成，适用于桌面环境

  • 安装步骤

    • 前提条件
      • macOS 系统，Hookmark 已安装
      • Hook CLI 已可用（通常通过 gem install hookmark 安装，或 Hookmark 自带）
      • Node.js 18+ 或 Bun
    • 从源码安装并运行
      • 克隆仓库并进入项目目录
      • 使用 Bun 安装依赖并编译构建
      • 以 MCP 服务形式启动服务器，服务器会监听标准输入输出进行 MCP 通信
    • 运行时配置
      • 如果需要自定义 Hook CLI 路径，通过环境变量 HOOK_CLI 指定（默认路径在代码中给出默认值，必要时可覆盖）

  • 服务器配置（MCP 客户端所需信息，供参考配置格式，而非客户端代码）

    • 说明：MCP 客户端需要知道如何启动该 MCP 服务器，至少包含服务器名称、启动命令及参数等信息。以下配置示例对应仓库实现的服务器名称和常用启动方式，请据实际部署路径调整参数。
    • JSON 配置示例（用于 MCP 客户端配置，不是服务器实现的代码）： { "mcpServers": { "hookmark": { "serverName": "hookmark-mcp", "command": "node", "args": ["/path/to/Hook/dist/index.js"], "env": { "HOOK_CLI": "/usr/local/bin/hook" // Hookmark CLI 的实际路径，如已通过 HOOK_CLI 环境变量覆盖也可读取该值 } // 该字段用于说明服务器的环境变量及启动参数，具体请以实际部署为准 } } }

  • 基本使用方法

    • 启动与连接
      • 按照上述配置在目标环境中启动 MCP 服务器（Hookmark MCP 服务器），服务器通过标准输出/输入进行 MCP 通信。
      • 在 Claude Code 等 MCP 客户端中将服务器名称设置为 hookmark，使用提供的 command 与 args 启动配置与服务器建立连接。
    • 调用工具
      • 通过 MCP 客户端调用以下工具：hookmark_link、hookmark_connect、hookmark_list、hookmark_search、hookmark_remove、hookmark_clone、hookmark_frontmost，传入相应参数即可完成操作。
    • 错误与排错
      • 如 Hookmark CLI 未正确安装或 HOOK_CLI 路径错误，服务器会返回对应的错误信息，需确保 Hookmark CLI 可在指定路径被执行。
      • 服务器需要 Hookmark.app 处于运行状态以创建 Hookmark 链接等功能，请确认 Hookmark 已打开并可交互。

服务器信息

访问项目