ice-jade 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f57e6758c88b25a57a7891bed83b7416ae9f511e780bcde4be30bb6f211ee3b3
-  data.tar.gz: 902380ad3fb6f0bfd2bd21f171bc3aa99a9538590455ba4a41f2b582a8a0d326
+  metadata.gz: 8b39e51e5e392d1d9ffd1ee3c991a0e22ea515a03b3ce3f2450642c8b460e595
+  data.tar.gz: 960d1cb2bd5f82023ed99de8ceff20dff679356a409086aecf89b0884b3895a7
 SHA512:
-  metadata.gz: 14d027172321795ad155cc0cd3bbb8f196d18db00b20c9d51cb5c990c84184633bafffd637e7d50c10c1018e70319efc9b136de35b8e1bd364d112a84d79a10a
-  data.tar.gz: e7ddcc89ef4fde4cd0ee17f9ee81d03f4c7fec1f6c8a0c5329741bbf298d77422131c40b86dadb941b93ff6256409b80366c8fd3cd9fc6bac7601601841fc7ca
+  metadata.gz: 8f3a1b54514dde13911ab21a994c6b1b0ff4a1e66facc77328fd69459406090c86eb773bbb7ab24726b31c784a1ec2140703cec161aaecd30053132c4bbf03c9
+  data.tar.gz: 28e26d266c4df37adfc552f4edcab9c883c6922c68196cf40532131571fa88004d225aa2b38e6b1f234b75c6c3f12adf2851d22ed3de21245e9b3035cb74a10e

data/bin/mcp_server.rb

@@ -0,0 +1,551 @@
+# frozen_string_literal: true
+
+# ice-jade MCP Server (zero-dependency, stdio JSON-RPC 2.0)
+#
+# 不依赖 mcp gem，仅使用 Ruby 标准库实现 MCP 协议。
+# 覆盖模块：Quantum / Poster / Getter / HttpPoster / HttpGetter / Cradle
+#
+# 用法：
+#   ruby bin/mcp_server.rb
+#
+# 在 Claude Desktop / Cursor 等客户端的 MCP 配置中：
+#   {
+#     "mcpServers": {
+#       "ice-jade": {
+#         "command": "ruby",
+#         "args": ["E:\\path\\to\\ice-jade\\bin\\mcp_server.rb"]
+#       }
+#     }
+#   }
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'ice_jade'
+require_relative '../lib/http_poster'
+require_relative '../lib/http_getter'
+require 'json'
+require 'uri'
+
+# ============================================================
+# 工具方法
+# ============================================================
+module MCPHelper
+  module_function
+
+  def format_response(resp)
+    {
+      success: resp.success?,
+      code: resp.code,
+      ok: resp.ok,
+      message: resp.message,
+      data: resp.data
+    }.to_json
+  end
+
+  def format_error(e)
+    { error: true, message: e.message, class: e.class.name }.to_json
+  end
+
+  def symbolize_keys(hash)
+    return hash unless hash.is_a?(Hash)
+    hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize_keys(v) }
+  end
+
+  # 构造 MCP text content block
+  def text_content(json_str)
+    [{ type: 'text', text: json_str }]
+  end
+
+  # 构造 MCP tool call 成功响应
+  def ok_result(json_str)
+    { content: text_content(json_str) }
+  end
+
+  # 构造 MCP tool call 失败响应（isError: true）
+  def error_result(json_str)
+    { content: text_content(json_str), isError: true }
+  end
+end
+
+# ============================================================
+# 工具注册表
+# ============================================================
+
+# 运行中的 Cradle 服务器实例（避免被 GC 回收）
+RUNNING_SERVERS = {}
+
+# 每个工具是一个 Hash：{ name:, description:, input_schema:, handler: }
+TOOLS = []
+
+def register_tool(name, description, input_schema, &handler)
+  TOOLS << { name: name, description: description, inputSchema: input_schema, handler: handler }
+end
+
+# ============================================================
+# 1. Quantum — IM 消息发送
+# ============================================================
+
+register_tool('quantum_send_text',
+  '通过 Quantum IM 机器人向群聊发送文本消息，支持@所有人或指定手机号',
+  {
+    type: 'object',
+    properties: {
+      webhook_key: { type: 'string', description: 'Quantum 机器人的 webhook key' },
+      content: { type: 'string', description: '要发送的文本内容' },
+      mention_all: { type: 'boolean', description: '是否@所有人，默认 false' },
+      base_url: { type: 'string', description: '可选，覆盖默认的 webhook 基础 URL' }
+    },
+    required: %w[webhook_key content]
+  }
+) do |args|
+  client = args['base_url'] ?
+    IceJade::Quantum::Client.new(args['webhook_key'], base_url: args['base_url']) :
+    IceJade::Quantum::Client.new(args['webhook_key'])
+  resp = client.send_text(args['content'], mention_all: args.fetch('mention_all', false))
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('quantum_send_news',
+  '通过 Quantum IM 机器人发送图文链接卡片消息',
+  {
+    type: 'object',
+    properties: {
+      webhook_key: { type: 'string', description: 'Quantum 机器人的 webhook key' },
+      title: { type: 'string', description: '卡片标题' },
+      url: { type: 'string', description: '点击卡片跳转的链接' },
+      description: { type: 'string', description: '可选，卡片描述文本' },
+      pic_url: { type: 'string', description: '可选，卡片配图 URL' },
+      base_url: { type: 'string', description: '可选，覆盖默认的 webhook 基础 URL' }
+    },
+    required: %w[webhook_key title url]
+  }
+) do |args|
+  client = args['base_url'] ?
+    IceJade::Quantum::Client.new(args['webhook_key'], base_url: args['base_url']) :
+    IceJade::Quantum::Client.new(args['webhook_key'])
+  resp = client.send_news(args['title'], args['url'], description: args['description'], pic_url: args['pic_url'])
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('quantum_upload_and_send_image',
+  '上传本地图片到 Quantum IM 并立即发送到群聊（两步合一）',
+  {
+    type: 'object',
+    properties: {
+      webhook_key: { type: 'string', description: 'Quantum 机器人的 webhook key' },
+      path: { type: 'string', description: '本地图片文件的完整路径' },
+      height: { type: 'integer', description: '图片高度（像素）' },
+      width: { type: 'integer', description: '图片宽度（像素）' },
+      base_url: { type: 'string', description: '可选，覆盖默认的 webhook 基础 URL' }
+    },
+    required: %w[webhook_key path height width]
+  }
+) do |args|
+  client = args['base_url'] ?
+    IceJade::Quantum::Client.new(args['webhook_key'], base_url: args['base_url']) :
+    IceJade::Quantum::Client.new(args['webhook_key'])
+  resp = client.upload_and_send_image(args['path'], height: args['height'], width: args['width'])
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('quantum_upload_and_send_file',
+  '上传本地文件到 Quantum IM 并立即发送到群聊（两步合一）',
+  {
+    type: 'object',
+    properties: {
+      webhook_key: { type: 'string', description: 'Quantum 机器人的 webhook key' },
+      path: { type: 'string', description: '本地文件的完整路径' },
+      base_url: { type: 'string', description: '可选，覆盖默认的 webhook 基础 URL' }
+    },
+    required: %w[webhook_key path]
+  }
+) do |args|
+  client = args['base_url'] ?
+    IceJade::Quantum::Client.new(args['webhook_key'], base_url: args['base_url']) :
+    IceJade::Quantum::Client.new(args['webhook_key'])
+  resp = client.upload_and_send_file(args['path'])
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# 2. Poster — 通用 HTTP POST 客户端
+# ============================================================
+
+register_tool('poster_post_json',
+  '发送 HTTP POST JSON 请求。支持 base_url + 相对路径或完整 URL，内置超时重试',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整 URL 或相对路径（需配合 base_url）' },
+      params: { type: 'object', description: '要 POST 的 JSON 参数对象' },
+      base_url: { type: 'string', description: '可选，基础 URL，设置后 url 可用相对路径' },
+      headers: { type: 'object', description: '可选，额外请求头' },
+      timeout: { type: 'integer', description: '可选，读取超时秒数，默认 60' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  poster = IceJade::Poster::Client.new(
+    base_url: args['base_url'], headers: args.fetch('headers', {}), timeout: args.fetch('timeout', 60)
+  )
+  resp = poster.post_json(args['url'], args.fetch('params', {}))
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('poster_post_form',
+  '发送 HTTP POST Form 表单请求（application/x-www-form-urlencoded）',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整 URL 或相对路径' },
+      params: { type: 'object', description: '表单参数对象' },
+      base_url: { type: 'string', description: '可选，基础 URL' },
+      headers: { type: 'object', description: '可选，额外请求头' },
+      timeout: { type: 'integer', description: '可选，读取超时秒数，默认 60' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  poster = IceJade::Poster::Client.new(
+    base_url: args['base_url'], headers: args.fetch('headers', {}), timeout: args.fetch('timeout', 60)
+  )
+  resp = poster.post_form(args['url'], args.fetch('params', {}))
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('poster_post_multipart',
+  '发送 HTTP POST Multipart 请求（文件上传）。params 中值为文件路径的字段会自动读取文件',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整 URL 或相对路径' },
+      params: { type: 'object', description: '参数对象，值为文件路径的字段会自动上传该文件' },
+      base_url: { type: 'string', description: '可选，基础 URL' },
+      headers: { type: 'object', description: '可选，额外请求头' }
+    },
+    required: %w[url params]
+  }
+) do |args|
+  poster = IceJade::Poster::Client.new(base_url: args['base_url'], headers: args.fetch('headers', {}))
+  resp = poster.post_multipart(args['url'], MCPHelper.symbolize_keys(args['params']))
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# 3. Getter — 通用 HTTP GET 客户端
+# ============================================================
+
+register_tool('getter_get',
+  '发送 HTTP GET 请求。支持查询参数、自定义请求头，内置超时重试。返回统一 Response 包装',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整 URL 或相对路径（需配合 base_url）' },
+      params: { type: 'object', description: '可选，查询参数对象，自动编码到 query string' },
+      base_url: { type: 'string', description: '可选，基础 URL' },
+      headers: { type: 'object', description: '可选，额外请求头' },
+      timeout: { type: 'integer', description: '可选，读取超时秒数，默认 60' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  getter = IceJade::Getter::Client.new(
+    base_url: args['base_url'], headers: args.fetch('headers', {}), timeout: args.fetch('timeout', 60)
+  )
+  resp = getter.get(args['url'], params: args['params'])
+  MCPHelper.ok_result(MCPHelper.format_response(resp))
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# 4. HttpPoster — 独立模块级 POST 工具
+# ============================================================
+
+register_tool('http_poster_json',
+  '使用 HttpPoster 模块发送 POST JSON 请求（独立模块，零 gem 依赖）。返回解析后的 JSON Hash',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整的请求 URL' },
+      params: { type: 'object', description: '要 POST 的 JSON 参数对象' },
+      headers: { type: 'object', description: '可选，自定义请求头（如 Authorization）' },
+      timeout: { type: 'integer', description: '可选，超时秒数，默认 60' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  result = HttpPoster.post_json(
+    args['url'], args.fetch('params', {}), args.fetch('headers', {}), { timeout: args.fetch('timeout', 60) }
+  )
+  MCPHelper.ok_result(result.is_a?(String) ? result : result.to_json)
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('http_poster_multipart',
+  '使用 HttpPoster 模块发送 POST Multipart 文件上传请求。params 中值为文件路径的字段会自动读取文件',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整的请求 URL' },
+      params: { type: 'object', description: '参数对象，值为文件路径的字段自动上传文件' },
+      headers: { type: 'object', description: '可选，自定义请求头' }
+    },
+    required: %w[url params]
+  }
+) do |args|
+  result = HttpPoster.post_multipart(args['url'], MCPHelper.symbolize_keys(args['params']), args.fetch('headers', {}))
+  MCPHelper.ok_result(result.is_a?(String) ? result : result.to_json)
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# 5. HttpGetter — 独立模块级 GET 工具
+# ============================================================
+
+register_tool('http_getter_json',
+  '使用 HttpGetter 模块发送 GET JSON 请求（独立模块，零 gem 依赖）。返回解析后的 JSON Hash',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整的请求 URL' },
+      params: { type: 'object', description: '可选，查询参数对象' },
+      headers: { type: 'object', description: '可选，自定义请求头' },
+      timeout: { type: 'integer', description: '可选，超时秒数，默认 60' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  result = HttpGetter.get_json(
+    args['url'], args.fetch('params', {}), args.fetch('headers', {}), { timeout: args.fetch('timeout', 60) }
+  )
+  MCPHelper.ok_result(result.is_a?(String) ? result : result.to_json)
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('http_getter_text',
+  '使用 HttpGetter 模块发送 GET 请求并返回纯文本（不做 JSON 解析）。适合获取 HTML、robots.txt 等',
+  {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: '完整的请求 URL' },
+      params: { type: 'object', description: '可选，查询参数对象' },
+      headers: { type: 'object', description: '可选，自定义请求头' }
+    },
+    required: %w[url]
+  }
+) do |args|
+  result = HttpGetter.get_text(args['url'], args.fetch('params', {}), args.fetch('headers', {}))
+  MCPHelper.ok_result(result.to_s)
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# 6. Cradle — HTTP 测试服务器
+# ============================================================
+
+register_tool('cradle_start_server',
+  '启动 Cradle HTTP 测试服务器。返回服务器信息（端口、地址），服务器在独立线程中运行不会阻塞',
+  {
+    type: 'object',
+    properties: {
+      port: { type: 'integer', description: '监听端口，默认 8765' },
+      host: { type: 'string', description: '监听地址，默认 0.0.0.0' }
+    }
+  }
+) do |args|
+  port = args.fetch('port', 8765)
+  host = args.fetch('host', '0.0.0.0')
+  key = "#{host}:#{port}"
+  if RUNNING_SERVERS[key]
+    MCPHelper.ok_result({ already_running: true, host: host, port: port }.to_json)
+  else
+    server = IceJade::Cradle::Server.new(port: port, host: host, silent: true)
+    thread = Thread.new { server.start }
+    RUNNING_SERVERS[key] = { server: server, thread: thread }
+    MCPHelper.ok_result({ started: true, host: host, port: port, message: 'Cradle 测试服务器已启动' }.to_json)
+  end
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('cradle_stop_server',
+  '停止运行中的 Cradle HTTP 测试服务器',
+  {
+    type: 'object',
+    properties: {
+      port: { type: 'integer', description: '要停止的服务器端口，默认 8765' },
+      host: { type: 'string', description: '要停止的服务器地址，默认 0.0.0.0' }
+    }
+  }
+) do |args|
+  port = args.fetch('port', 8765)
+  host = args.fetch('host', '0.0.0.0')
+  key = "#{host}:#{port}"
+  entry = RUNNING_SERVERS.delete(key)
+  if entry
+    entry[:server].stop
+    entry[:thread].kill
+    MCPHelper.ok_result({ stopped: true, host: host, port: port }.to_json)
+  else
+    MCPHelper.ok_result({ stopped: false, message: "未找到运行中的服务器 #{key}" }.to_json)
+  end
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+register_tool('cradle_add_route',
+  '向运行中的 Cradle 测试服务器添加自定义路由，用于模拟 API 响应',
+  {
+    type: 'object',
+    properties: {
+      port: { type: 'integer', description: '目标服务器端口，默认 8765' },
+      host: { type: 'string', description: '目标服务器地址，默认 0.0.0.0' },
+      method: { type: 'string', description: 'HTTP 方法：GET / POST / PUT / DELETE 等' },
+      path: { type: 'string', description: '路由路径，如 /echo 或 /api/users/:id' },
+      status: { type: 'integer', description: '响应状态码，默认 200' },
+      body: { type: 'string', description: '响应体内容' },
+      content_type: { type: 'string', description: '响应 Content-Type，默认 application/json' }
+    },
+    required: %w[method path]
+  }
+) do |args|
+  port = args.fetch('port', 8765)
+  host = args.fetch('host', '0.0.0.0')
+  key = "#{host}:#{port}"
+  entry = RUNNING_SERVERS[key]
+  raise "服务器 #{key} 未运行" unless entry
+
+  server = entry[:server]
+  m = args['method'].to_sym
+  route_path = args['path']
+  route_status = args.fetch('status', 200)
+  route_body = args.fetch('body', '{}')
+  route_ct = args.fetch('content_type', 'application/json')
+  server.route(m, route_path) do |_req|
+    [route_status, { 'Content-Type' => route_ct }, route_body]
+  end
+  MCPHelper.ok_result({ added: true, method: args['method'].upcase, path: route_path, status: route_status }.to_json)
+rescue StandardError => e
+  MCPHelper.error_result(MCPHelper.format_error(e))
+end
+
+# ============================================================
+# MCP 协议层 — 纯标准库 JSON-RPC 2.0 over STDIO
+# ============================================================
+
+PROTOCOL_VERSION = '2025-03-26'
+SERVER_NAME = 'ice-jade-mcp-server'
+SERVER_VERSION = IceJade::VERSION
+
+def handle_initialize(req)
+  {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: { listChanged: false }
+    },
+    serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+  }
+end
+
+def handle_tools_list(req)
+  { tools: TOOLS.map { |t| { name: t[:name], description: t[:description], inputSchema: t[:inputSchema] } } }
+end
+
+def handle_tools_call(req)
+  params = req['params'] || {}
+  tool_name = params['name']
+  arguments = params['arguments'] || {}
+  tool = TOOLS.find { |t| t[:name] == tool_name }
+
+  if tool.nil?
+    return {
+      content: [{ type: 'text', text: { error: true, message: "Unknown tool: #{tool_name}" }.to_json }],
+      isError: true
+    }
+  end
+
+  tool[:handler].call(arguments)
+end
+
+def handle_ping(req)
+  {}
+end
+
+def process_request(req)
+  method = req['method']
+  id = req['id']
+
+  result = case method
+           when 'initialize'      then handle_initialize(req)
+           when 'ping'            then handle_ping(req)
+           when 'tools/list'      then handle_tools_list(req)
+           when 'tools/call'      then handle_tools_call(req)
+           when 'notifications/initialized' then nil  # 通知，无需响应
+           else
+             return {
+               jsonrpc: '2.0',
+               id: id,
+               error: { code: -32601, message: "Method not found: #{method}" }
+             }
+           end
+
+  return nil if result.nil? && id.nil?  # 通知，无响应
+
+  { jsonrpc: '2.0', id: id, result: result }
+rescue StandardError => e
+  { jsonrpc: '2.0', id: id, error: { code: -32603, message: e.message } }
+end
+
+# 主循环：逐行读取 STDIN，解析 JSON-RPC，输出到 STDOUT
+$stdout.sync = true
+$stdin.each_line do |line|
+  line = line.strip
+  next if line.empty?
+
+  begin
+    req = JSON.parse(line)
+  rescue JSON::ParserError
+    # 单行可能包含多个 JSON-RPC 消息（批量），尝试解析为数组
+    begin
+      batch = JSON.parse("[#{line}]")
+      if batch.is_a?(Array)
+        results = batch.map do |item|
+          begin
+            req = JSON.parse(item)
+            process_request(req)
+          rescue JSON::ParserError
+            { jsonrpc: '2.0', id: nil, error: { code: -32700, message: 'Parse error' } }
+          end
+        end.compact
+        puts results.map(&:to_json).join("\n") unless results.empty?
+        next
+      end
+    rescue JSON::ParserError
+      # fall through
+    end
+    puts({ jsonrpc: '2.0', id: nil, error: { code: -32700, message: 'Parse error' } }.to_json)
+    next
+  end
+
+  response = process_request(req)
+  puts response.to_json if response
+end

data/lib/ice_jade/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IceJade
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ice-jade
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Frampt
@@ -24,6 +24,7 @@ files:
 - README.md
 - bin/cradle
 - bin/cradle-instance
+- bin/mcp_server.rb
 - config/cradle/poster_test.yml
 - examples/comparison_getter.rb
 - examples/comparison_poster.rb