MCP 集成

Model Context Protocol (MCP) 让 AI 代理（Claude、GPT 等）能原生调用 IconHash 的全部能力。

快速上手

如果你只想最快跑通，直接用 Claude Code 的 SKILLS 插件：推荐 一行命令即可，详见 Claude Code 集成。

什么是 MCP

MCP 是一个开放协议，标准化了 AI 代理与外部工具的通信方式。IconHash 实现了完整的 MCP 服务器，暴露 5 个工具。

关于 MCP 协议

MCP 由 Anthropic 提出，基于 JSON-RPC 2.0，通过 stdio 或 HTTP 传输。它解决了"每个 AI 代理都要重复对接每个工具"的 N×M 问题——只需一套协议，任意客户端对接任意服务器。详见 modelcontextprotocol.io。

5 个 MCP 工具

工具	输入	输出	对应 CLI
iconhash_url	url	哈希+指纹	iconhash url
iconhash_base64	data	哈希	iconhash base64
iconhash_file	path	哈希	iconhash file
iconhash_discover	url	图标列表+哈希	iconhash discover
iconhash_lookup	hash	指纹详情	iconhash lookup

工具选择建议

• 输入是 网站 URL 且想要完整指纹 → iconhash_discover 最常用
• 已有图标的 Base64 数据 → iconhash_base64
• 图标存为 本地文件 → iconhash_file
• 只有一个 mmh3 哈希值，想反查指纹 → iconhash_lookup

完整工具 schema（tools/list 返回）

{
  "tools": [
    {
      "name": "iconhash_url",
      "description": "计算给定 URL favicon 的 mmh3 哈希并匹配指纹",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "favicon 的完整 URL" }
        },
        "required": ["url"]
      }
    },
    {
      "name": "iconhash_discover",
      "description": "自动发现网站的 favicon 并计算哈希、匹配指纹",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "目标网站根 URL" }
        },
        "required": ["url"]
      }
    },
    {
      "name": "iconhash_lookup",
      "description": "根据 mmh3 哈希反查指纹库详情",
      "inputSchema": {
        "type": "object",
        "properties": {
          "hash": { "type": "string", "description": "mmh3 哈希值" }
        },
        "required": ["hash"]
      }
    }
    // base64 / file 工具结构类似，省略
  ]
}

两种部署形态

模式	命令	适合
stdio	iconhash mcp	本地 Claude Code 集成
HTTP	iconhash server（含 /mcp 端点）	远程 / 多客户端

如何选择

• stdio 模式 零配置：Claude Code 直接 fork 子进程，无需端口、无需鉴权，适合个人开发机。
• HTTP 模式 需暴露端口：常驻服务，多客户端共享，适合团队 / 服务器部署，注意做好访问控制。

Claude Code 集成

方式一：SKILLS 插件（最简）

# 一键安装，自动配置 MCP
/plugin install cyberspacesec/iconhash-skills

为什么推荐插件

插件不仅自动写入 MCP 配置，还会一并加载 SKILLS.md——AI 因此知道"何时该用哪个工具"。手动配置只装了协议层，缺失语义层指导。详见 与 SKILLS 的关系。

方式二：手动配置 MCP

在 .claude/settings.json 中添加：

前置条件

确保 iconhash 二进制已安装在 PATH 中，否则 Claude 启动时会找不到命令。可用 iconhash version 验证。

.claude/settings.json 完整配置

{
  "mcpServers": {
    "iconhash": {
      "command": "iconhash",
      "args": ["mcp"]
    }
  }
}

如果 iconhash 不在 PATH，可用绝对路径：

{
  "mcpServers": {
    "iconhash": {
      "command": "/usr/local/bin/iconhash",
      "args": ["mcp"]
    }
  }
}

协议交互流程

发现工具（tools/list）

请求：

tools/list 请求体

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

响应会列出全部 5 个工具及其 inputSchema（见下方折叠的"完整工具 schema"）。

调用工具（tools/call）

请求示例：

tools/call 请求体

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "iconhash_discover",
    "arguments": { "url": "https://example.com" }
  },
  "id": 2
}

注意参数校验

• name 必须是 5 个工具名之一，否则服务器返回 Method not found。
• arguments 中的 url 需带协议头（http:// / https://），否则内部分发器会拒绝。
• 工具调用是同步阻塞的，iconhash_discover 抓取远程图标可能耗时数秒，注意设置合理的客户端超时。

端到端调用链

一次 iconhash_discover 调用在服务器内部经过的完整链路：

完整 MCP 通信时序

从 Claude 启动到拿到第一次工具结果，客户端与服务器之间的完整往返：

与 SKILLS 的关系

SKILLS 与 MCP 是两个层次的能力，常一起使用：

• SKILLS：声明性的技能描述，让 AI 知道"有什么能力、什么场景该用"
• MCP：标准化的调用协议，让 AI 能"实际执行工具调用"

一句话总结

SKILLS 告诉 AI "何时用"，MCP 让 AI "能用"。 用了 SKILLS 插件，两层一次性都配齐；纯手动配 MCP，只配了"能用"这一层。

其他 AI 代理

MCP 是开放协议，不限于 Claude：

任何兼容 MCP 的客户端都可接入。

非 Claude 客户端怎么接

• GPT 等无原生 MCP 的模型：通过 mcp-proxy 或社区桥接器把 MCP 工具转成 OpenAI function calling。
• 自建 Agent：直接走 HTTP 模式，对 /mcp 端点发 JSON-RPC 请求即可，无需任何 SDK。
• Cursor / Continue 等：参考各自文档的 "MCP Servers" 配置项，填入 iconhash mcp 命令。

---

下一篇：指纹数据库。