使用说明内容（Markdown格式）

GTI 威胁情报 MCP 服务器（独立版）

• 项目简介

  • 这是一个基于 Model Context Protocol 的独立 MCP 服务器实现，用于向 LLM 客户端（如 Claude、Cline、Cursor 等）提供 Threat Intelligence 相关的资源访问、工具执行以及提示模板渲染能力。服务器支持本地开发模式和云端云运行模式，采用 JSON-RPC 与 SSE 通信，具备会话管理、能力声明和多传输协议的扩展能力。

• 主要功能点

  • 资源与数据访问：提供对威胁情报数据的读取和关系查询能力（如域、IP、URL、文件、集合、 threat profiles 等）。
  • 工具注册与执行：暴露多种 Threat Intelligence 工具（如 get_file_report、get_domain_report、search_threats、get_collection_rules 等），供 LLM 调用。
  • 提示模板与渲染：通过工具集合及相关接口，支持将查询结果渲染为可用于对话的文本输出。
  • MCP 传输与认证：支持本地 stdio 与 Cloud SSE 传输，使用 X-Mcp-Authorization 或 Bearer 令牌进行认证。
  • 本地与云部署：提供本地运行方式（uv 工具链）和生产云部署脚本（Cloud Run），方便团队共享服务。
  • 安全与扩展性：服务器端存储能力声明、会话管理、以及按需扩展的 API 调用（每次调用可传递 VT API Key，云端不保存密钥，单次请求中携带）。

• 安装步骤

  • 克隆仓库并进入目录
  • 本地开发（推荐）
    • 安装并运行：uv tool install -e . 或直接 uv run gti_mcp
    • 设置环境变量 VT_APIKEY（VirusTotal 的 API Key）
  • 云端部署（Cloud Run）
    • 使用 gti-remotemcp-deploy.sh 脚本，按提示配置 PROJECT_ID、SERVICE_NAME、REGION
    • 脚本输出：Service URL、SSE Endpoint、Auth Token，请妥善保存
  • 客户端配置与连接
    • MCP 客户端要连接的服务地址以 SSE 接口 /sse 结尾，认证需通过 X-Mcp-Authorization 或 Authorization 头传递
    • 每次工具调用需携带 api_key（用于 VirusTotal 请求），云部署不存储密钥，由客户端自带凭据

• 服务器配置（MCP 客户端连接信息示例，JSON 格式，非代码块展示） { "server_name": "gti", "command": "uv", "args": [ "--directory", "/absolute/path/to/gti-mcp-standalone", "run", "gti_mcp" ], "env": { "VT_APIKEY": "<你的VirusTotal API Key>" }, "description": "本地主机运行 GTI MCP 服务器的配置，用于 Claude Desktop/Cline/Cursor 等客户端连接。" } 说明：

  • server_name 对应 MCP 客户端在工具集合中显示的服务器名称（README 中使用 gti）
  • command 与 args 指定运行服务器的命令及参数
  • env 中可选注入环境变量，如 VT_APIKEY（仅用于本地开发场景，云端不会持久保存 API Key）
  • 客户端连接时需使用 /sse 端点进行 SSE 建连，/messages 用于 JSON-RPC 消息交互，授权头需正确设置

• 基本使用方法

  • 启动本地服务器后，打开相应的 MCP 客户端（如 Claude Desktop/Cline Cursor），在工具列表中应看到 GTI 服务器（名称为 gti）。
  • 连接 GTI 服务器后，可以直接通过工具调用执行 Threat Intelligence 任务，如获取文件、域、IP、URL 报告，或执行 threat 搜索与集合操作。
  • 调用示例（简述）：对某个文件哈希执行 get_file_report，或执行 search_threats 以查询威胁集合，并将 VT API Key 一次性作为参数传入每次工具调用中。
  • 云部署时，请使用 SSE 连接到 /sse，使用 MCP_AUTH_TOKEN 进行鉴权，工具调用中继续传入 api_key（VirusTotal API Key）以完成外部查询。

• 注意事项

  • 不同部署模式的认证方式略有不同，请遵循云端脚本输出的 MCP_AUTH_TOKEN 或本地环境变量配置。
  • VirusTotal API Key 不在服务器端持久存储，需客户端逐次提交以实现基于 Key 的配额与访问控制。
  • 确保通信使用 HTTPS（云端默认支持），本地通过 stdio/uv 提供的通道进行调试。

• 基本使用示例

  • 本地开发：在终端执行 uv run gti_mcp，确保 VT_APIKEY 已在环境变量中。随后在 Claude/Cline Cursor 等客户端中添加服务器配置，使用 /sse 端点建立连接。
  • 云端部署：通过 gti-remotemcp-deploy.sh 部署后，获取服务 URL、SSE 端点、Auth Token，前端客户端使用这些信息连接并进行工具调用。

• 运行与测试注意

  • 仓库内包含针对工具、请求与 VT 客户端的测试用例，实际运行时请确保依赖安装正确并具备外部 API Key 权限。