MCP shanhe API 帮助文档
AI 模式 文档更新于 2026-03-24 20:22:07

MCP shanhe API

统一的 MCP (Model Context Protocol) 网关服务,提供 AI 视觉分析、联网搜索、网页阅读与 GitHub 仓库理解能力。

15
注册工具
14
可用工具
4
工具分类
2
传输协议

快速开始

1. 接入 Claude Code

先在用户门户「API 密钥」页面创建一把 oki- 密钥(与大模型 API 共用)。推荐用命令注册(用户级,一条搞定):

claude mcp add --transport http shanhe https://mcp.0ki.cn/mcp \
  --header "Authorization: Bearer oki-你的密钥"

或手动写入 ~/.claude.json / 项目 .mcp.json:

{
  "mcpServers": {
    "shanhe": {
      "type": "http",
      "url": "https://mcp.0ki.cn/mcp",
      "headers": {
        "Authorization": "Bearer oki-你的密钥"
      }
    }
  }
}

接入后在 Claude Code 运行 /mcp,应能看到 shanhe 及其全部工具。

2. API 端点

端点 方法 说明
/mcpPOSTStreamable HTTP 传输
/sseGETSSE 传输
/messagesPOSTSSE 消息发送
/healthGET健康检查

3. 认证与计费

所有请求需在 Header 携带 API 密钥(oki- 为平台用户密钥,mcp-key- 为本网关独立密钥):

Authorization: Bearer oki-xxxxxxxx        # 推荐(平台用户)
X-API-Key: oki-xxxxxxxx                    # 等价写法
Authorization: Bearer mcp-key-xxxxxxxx      # 本网关独立密钥

计费说明

• 有套餐用户:走套餐的 MCP 工具调用配额,每个 tools/call 计 1 次,用尽返回 429。

• 无套餐用户:按量付费,每个 tools/call 从现金余额扣 ¥0.01;余额不足则工具不执行。

• initialize / tools/list / ping 免费,不计费。

4. MCP 协议示例

Initialize 初始化:

POST /mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}

tools/list 获取工具列表:

POST /mcp
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

tools/call 调用工具(如联网搜索):

POST /mcp
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"智谱 GLM 最新动态"}}}

工具分类

视觉分析 (8 个工具)

analyze_image

使用 AI 视觉模型分析图片。支持远程 URL、base64 数据 URI 或本地文件路径。返回图片内容的详细分析,包括物体、文字、颜色、构图等。

可用

参数

参数名 类型 必填 说明
imageSource string 是 Remote URL or base64 data URI of the image to analyze.
prompt string 否 Optional custom prompt describing what to analyze. If not provided, a general analysis will be performed.
AI 增强描述暂未生成

extract_text_from_image

使用 AI 驱动的 OCR 从图片中提取文字。支持远程 URL、base64 数据 URI 或本地文件路径。保留原始格式、换行和结构。

可用

参数

参数名 类型 必填 说明
image_source string 是 Local file path, remote URL, or base64 data URI of the image.
prompt string 否 Optional instructions for text extraction (e.g., focus on specific areas, language).
AI 增强描述暂未生成

analyze_chart

分析图表、图形和数据可视化。识别图表类型,提取数据点,识别趋势和规律,提供关键洞察。支持远程 URL、base64 数据 URI 或本地文件路径。

可用

参数

参数名 类型 必填 说明
image_source string 是 Local file path, remote URL, or base64 data URI of the chart image.
prompt string 否 Optional custom prompt for what to analyze in the chart.
AI 增强描述暂未生成

upload_image

将 base64 编码的图片上传到服务器并返回 URL。接受 data URI 格式(如 data:image/png;base64,...)。上传后的图片可在其他视觉工具中通过 URL 引用。

可用

参数

参数名 类型 必填 说明
image_data string 是 Base64-encoded image data with data URI prefix (e.g., data:image/png;base64,iVBOR...).
AI 增强描述暂未生成

batch_analyze_images

批量分析多张图片。支持逐个分析、对比模式和摘要模式。图片源以 JSON 数组形式提供(URL 或 base64 数据 URI)。

可用

参数

参数名 类型 必填 说明
sources string 是 JSON array of image sources (URLs or base64 data URIs). Example: ["https://example.com/img1.png","https://example.com/img2.jpg"]
mode string 否 Analysis mode: "individual" (analyze each separately), "compare" (compare images), or "summary" (analyze and generate a summary).
可选值: individual, compare, summary
prompt string 否 Analysis prompt. For "compare" mode, describes what to compare. For "individual" mode, applied to each image.
AI 增强描述暂未生成

preprocess_image

使用 GD 库在分析前预处理图片。支持缩放、裁剪、旋转、锐化、模糊、灰度化、对比度、亮度和反色。操作按顺序依次执行。

可用

参数

参数名 类型 必填 说明
image_source string 是 Local file path, remote URL, or base64 data URI of the image.
operations string 否 Comma-separated operations. Format: "type:param1=val1;param2=val2,type2:param=val". Types: resize (width;height), crop (x;y;width;height), rotate (angle), sharpen, blur (radius), grayscale, contrast (level), brightness (level), invert. Example: "resize:800;600,sharpen,contrast:20"
AI 增强描述暂未生成

compare_image_similarity

使用感知哈希算法比较两张图片的相似度。支持 phash(默认)、ahash、dhash 和像素比较方法。返回 0 到 1 之间的相似度分数。

可用

参数

参数名 类型 必填 说明
image_source_1 string 是 First image source: local file path, remote URL, or base64 data URI.
image_source_2 string 是 Second image source: local file path, remote URL, or base64 data URI.
method string 否 Comparison method: "phash" (perceptual hash, default), "ahash" (average hash), "dhash" (difference hash), or "pixel" (direct pixel comparison).
可选值: phash, ahash, dhash, pixel
AI 增强描述暂未生成

extract_image_metadata

提取图片的完整元数据信息,包括物理尺寸(宽高像素)、文件大小(字节)、MIME 类型、EXIF 拍摄参数(如相机型号/曝光时间)及主导颜色分析。支持三种输入源:HTTP(S) 远程地址、Base64 编码数据 URI 或服务器本地文件路径。

可用

使用场景

  • • 图片内容审核时验证拍摄设备信息
  • • 设计素材库自动标注颜色方案
  • • 社交媒体图片合规性检查

参数

参数名 类型 必填 说明
image_source string 是 图片来源路径(URL/base64/本地路径)
include_exif boolean 否 是否包含 EXIF 元数据(布尔值)
include_colors boolean 否 是否分析主导颜色(布尔值)

调用示例

{
    "name": "extract_image_metadata",
    "arguments": {
        "image_source": "https:\/\/example.com\/photo.jpg",
        "include_exif": true,
        "include_colors": true
    }
}

返回示例

{
    "content": {
        "dimensions": "1920x1080",
        "file_size": 245678,
        "mime_type": "image\/jpeg",
        "exif": {
            "camera": "Canon EOS 5D",
            "exposure": "1\/500s"
        },
        "dominant_colors": [
            "#2A5C82",
            "#F4A460"
        ]
    },
    "isError": false
}

reader (1 个工具)

read_web_page

深度解析网页内容并转换为 Markdown 格式,保留标题层级、正文结构和可选图片引用。支持缓存策略控制和超时保护,适用于文档抓取和内容归档场景。

可用

使用场景

  • • 技术文档版本比对
  • • 新闻内容长期存档
  • • 多语言网站内容提取

参数

参数名 类型 必填 说明
url string 是 目标网页地址
return_format string 否 输出格式(markdown/text)
可选值: markdown, text
retain_images boolean 否 保留图片链接(布尔值)
no_cache boolean 否 强制刷新缓存(布尔值)
timeout integer 否 请求超时时间(秒)

调用示例

{
    "name": "read_web_page",
    "arguments": {
        "url": "https:\/\/docs.example.com\/guide",
        "return_format": "markdown",
        "retain_images": true,
        "no_cache": false,
        "timeout": 10
    }
}

返回示例

{
    "content": "# 用户指南\n![流程图](image.png)\n## 安装步骤\n1. 下载安装包...",
    "isError": false
}

zread (3 个工具)

search_doc

在 GitHub 仓库的文档和代码中进行全文搜索,支持关键词匹配文件路径、代码片段及提交历史。可快速定位功能实现位置、追踪问题修复记录、分析核心模块依赖关系,返回匹配文件的相对路径及内容摘要。

可用

使用场景

  • • 新项目技术栈调研时快速定位核心模块
  • • 查找特定功能(如认证逻辑)的代码实现位置
  • • 追踪某个 Issue 相关的代码修改记录
  • • 分析最近 Commit 涉及的文件变更范围

参数

参数名 类型 必填 说明
repo_name string 是 必填,GitHub 仓库标识符,格式为'所有者/仓库名'(例:octocat/Hello-World)
query string 是 必填,搜索关键词,支持代码符号、函数名、错误信息等(例:'authentication middleware')

调用示例

{
    "name": "search_doc",
    "arguments": {
        "repo_name": "tensorflow\/tensorflow",
        "query": "gradient descent optimization"
    }
}

返回示例

{
    "content": [
        {
            "path": "tensorflow\/core\/optimizer.py",
            "matches": [
                "class GradientDescentOptimizer...",
                "def _apply_dense(..."
            ]
        },
        {
            "path": "docs\/guide\/optimizers.md",
            "matches": [
                "## 梯度下降优化器",
                "学习率调整策略..."
            ]
        }
    ],
    "isError": false
}

get_repo_structure

可视化展示 GitHub 仓库的目录树结构,支持递归展开子目录。帮助开发者理解项目模块划分、识别配置文件位置、定位测试用例目录,可指定子目录路径进行局部结构查看。

可用

使用场景

  • • 初次接触开源项目时快速掌握代码组织方式
  • • 定位特定功能模块所在的子目录(如 src/api)
  • • 评估项目是否符合标准目录规范(如 MVC 结构)
  • • 查找配置文件(如 Dockerfile、.gitignore)位置

参数

参数名 类型 必填 说明
repo_name string 是 必填,GitHub 仓库标识符,格式为'所有者/仓库名'
dir_path string 否 可选,子目录路径(例:'src/components'),默认为根目录'/'

调用示例

{
    "name": "get_repo_structure",
    "arguments": {
        "repo_name": "vuejs\/vue",
        "dir_path": "src\/platforms"
    }
}

返回示例

{
    "content": {
        "type": "directory",
        "children": [
            {
                "name": "web",
                "type": "directory"
            },
            {
                "name": "weex",
                "type": "directory"
            },
            {
                "name": "README.md",
                "type": "file"
            }
        ]
    },
    "isError": false
}

read_file

获取 GitHub 仓库中任意文件的完整原始内容,支持代码文件、配置文件、文档等。适用于代码审查、实现逻辑分析、依赖检查等场景,返回内容保留原始格式和注释。

可用

使用场景

  • • 审查核心算法文件的具体实现逻辑
  • • 分析 package.json 中的依赖版本配置
  • • 检查 CI/CD 配置文件(如.github/workflows)
  • • 定位 Bug 时查看异常抛出位置的代码上下文

参数

参数名 类型 必填 说明
repo_name string 是 必填,GitHub 仓库标识符,格式为'所有者/仓库名'
file_path string 是 必填,文件在仓库中的完整路径(例:'src/utils/auth.js')

调用示例

{
    "name": "read_file",
    "arguments": {
        "repo_name": "microsoft\/vscode",
        "file_path": "src\/vs\/workbench\/api\/common\/extHost.api.impl.ts"
    }
}

返回示例

{
    "content": "\/*---------------------------------------------------------------------------------------------\n *  Copyright (c) Microsoft Corporation...\n *--------------------------------------------------------------------------------------------*\/\n\nimport * as vscode from 'vscode';\n\nexport function createExtHostAPI(...",
    "isError": false
}

完整工具 Schema

tools/list 返回的完整工具定义(JSON 格式):

{
    "vision": [
        {
            "name": "analyze_image",
            "description": "使用 AI 视觉模型分析图片。支持远程 URL、base64 数据 URI 或本地文件路径。返回图片内容的详细分析,包括物体、文字、颜色、构图等。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "imageSource": {
                        "type": "string",
                        "description": "Remote URL or base64 data URI of the image to analyze."
                    },
                    "prompt": {
                        "type": "string",
                        "description": "Optional custom prompt describing what to analyze. If not provided, a general analysis will be performed."
                    }
                },
                "required": [
                    "imageSource"
                ]
            }
        },
        {
            "name": "extract_text_from_image",
            "description": "使用 AI 驱动的 OCR 从图片中提取文字。支持远程 URL、base64 数据 URI 或本地文件路径。保留原始格式、换行和结构。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_source": {
                        "type": "string",
                        "description": "Local file path, remote URL, or base64 data URI of the image."
                    },
                    "prompt": {
                        "type": "string",
                        "description": "Optional instructions for text extraction (e.g., focus on specific areas, language)."
                    }
                },
                "required": [
                    "image_source"
                ]
            }
        },
        {
            "name": "analyze_chart",
            "description": "分析图表、图形和数据可视化。识别图表类型,提取数据点,识别趋势和规律,提供关键洞察。支持远程 URL、base64 数据 URI 或本地文件路径。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_source": {
                        "type": "string",
                        "description": "Local file path, remote URL, or base64 data URI of the chart image."
                    },
                    "prompt": {
                        "type": "string",
                        "description": "Optional custom prompt for what to analyze in the chart."
                    }
                },
                "required": [
                    "image_source"
                ]
            }
        },
        {
            "name": "upload_image",
            "description": "将 base64 编码的图片上传到服务器并返回 URL。接受 data URI 格式(如 data:image\/png;base64,...)。上传后的图片可在其他视觉工具中通过 URL 引用。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_data": {
                        "type": "string",
                        "description": "Base64-encoded image data with data URI prefix (e.g., data:image\/png;base64,iVBOR...)."
                    }
                },
                "required": [
                    "image_data"
                ]
            }
        },
        {
            "name": "batch_analyze_images",
            "description": "批量分析多张图片。支持逐个分析、对比模式和摘要模式。图片源以 JSON 数组形式提供(URL 或 base64 数据 URI)。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "sources": {
                        "type": "string",
                        "description": "JSON array of image sources (URLs or base64 data URIs). Example: [\"https:\/\/example.com\/img1.png\",\"https:\/\/example.com\/img2.jpg\"]"
                    },
                    "mode": {
                        "type": "string",
                        "description": "Analysis mode: \"individual\" (analyze each separately), \"compare\" (compare images), or \"summary\" (analyze and generate a summary).",
                        "enum": [
                            "individual",
                            "compare",
                            "summary"
                        ]
                    },
                    "prompt": {
                        "type": "string",
                        "description": "Analysis prompt. For \"compare\" mode, describes what to compare. For \"individual\" mode, applied to each image."
                    }
                },
                "required": [
                    "sources"
                ]
            }
        },
        {
            "name": "preprocess_image",
            "description": "使用 GD 库在分析前预处理图片。支持缩放、裁剪、旋转、锐化、模糊、灰度化、对比度、亮度和反色。操作按顺序依次执行。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_source": {
                        "type": "string",
                        "description": "Local file path, remote URL, or base64 data URI of the image."
                    },
                    "operations": {
                        "type": "string",
                        "description": "Comma-separated operations. Format: \"type:param1=val1;param2=val2,type2:param=val\". Types: resize (width;height), crop (x;y;width;height), rotate (angle), sharpen, blur (radius), grayscale, contrast (level), brightness (level), invert. Example: \"resize:800;600,sharpen,contrast:20\""
                    }
                },
                "required": [
                    "image_source"
                ]
            }
        },
        {
            "name": "compare_image_similarity",
            "description": "使用感知哈希算法比较两张图片的相似度。支持 phash(默认)、ahash、dhash 和像素比较方法。返回 0 到 1 之间的相似度分数。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_source_1": {
                        "type": "string",
                        "description": "First image source: local file path, remote URL, or base64 data URI."
                    },
                    "image_source_2": {
                        "type": "string",
                        "description": "Second image source: local file path, remote URL, or base64 data URI."
                    },
                    "method": {
                        "type": "string",
                        "description": "Comparison method: \"phash\" (perceptual hash, default), \"ahash\" (average hash), \"dhash\" (difference hash), or \"pixel\" (direct pixel comparison).",
                        "enum": [
                            "phash",
                            "ahash",
                            "dhash",
                            "pixel"
                        ]
                    }
                },
                "required": [
                    "image_source_1",
                    "image_source_2"
                ]
            }
        },
        {
            "name": "extract_image_metadata",
            "description": "提取图片元数据,包括尺寸、文件大小、MIME 类型、EXIF 信息(如有)和主要颜色。支持远程 URL、base64 数据 URI 或本地文件路径。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "image_source": {
                        "type": "string",
                        "description": "Local file path, remote URL, or base64 data URI of the image."
                    },
                    "include_exif": {
                        "type": "boolean",
                        "description": "Whether to include EXIF data. Default: true."
                    },
                    "include_colors": {
                        "type": "boolean",
                        "description": "Whether to include color analysis (dominant colors). Default: true."
                    }
                },
                "required": [
                    "image_source"
                ]
            }
        }
    ],
    "search": [
        {
            "name": "web_search",
            "description": "使用 AI 增强搜索引擎进行网络搜索。返回结构化结果(标题、链接、摘要等)。支持域名过滤、时间范围过滤和内容长度控制。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query string."
                    },
                    "count": {
                        "type": "number",
                        "description": "Number of results to return (1-50). Default: 10."
                    },
                    "domain_filter": {
                        "type": "string",
                        "description": "Only search within this domain (e.g., \"github.com\")."
                    },
                    "recency_filter": {
                        "type": "string",
                        "description": "Time range filter for results.",
                        "enum": [
                            "noLimit",
                            "oneDay",
                            "oneWeek",
                            "oneMonth",
                            "oneYear"
                        ]
                    },
                    "content_size": {
                        "type": "string",
                        "description": "Length of content summary.",
                        "enum": [
                            "low",
                            "medium",
                            "high"
                        ]
                    }
                },
                "required": [
                    "query"
                ]
            }
        },
        {
            "name": "web_search_in_chat",
            "description": "联网搜索并结合 AI 生成智能回答。搜索结果提供上下文,自定义提示词可指导回答的结构和内容。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query string."
                    },
                    "prompt": {
                        "type": "string",
                        "description": "Custom prompt guiding how to organize and present the answer. Default: provide a comprehensive answer based on search results."
                    },
                    "count": {
                        "type": "number",
                        "description": "Number of search results (1-50). Default: 10."
                    },
                    "domain_filter": {
                        "type": "string",
                        "description": "Only search within this domain (e.g., \"github.com\")."
                    },
                    "recency_filter": {
                        "type": "string",
                        "description": "Time range filter.",
                        "enum": [
                            "noLimit",
                            "oneDay",
                            "oneWeek",
                            "oneMonth",
                            "oneYear"
                        ]
                    }
                },
                "required": [
                    "query"
                ]
            }
        }
    ],
    "reader": [
        {
            "name": "read_web_page",
            "description": "读取并解析指定 URL 的网页内容,返回 Markdown 格式的正文、标题和描述。可用于读取文章、文档、新闻等网页。支持缓存控制和图片保留选项。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "url": {
                        "type": "string",
                        "description": "需要读取的网页 URL 地址"
                    },
                    "return_format": {
                        "type": "string",
                        "description": "返回格式",
                        "enum": [
                            "markdown",
                            "text"
                        ]
                    },
                    "retain_images": {
                        "type": "boolean",
                        "description": "是否保留图片(默认 true)"
                    },
                    "no_cache": {
                        "type": "boolean",
                        "description": "是否禁用缓存(默认 false)"
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "请求超时时间(秒),默认 20"
                    }
                },
                "required": [
                    "url"
                ]
            }
        }
    ],
    "zread": [
        {
            "name": "search_doc",
            "description": "在 GitHub 仓库的文档和代码中进行搜索。可用于快速了解仓库功能、核心模块、关键流程、最近 Issue 和 Commit 等。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "repo_name": {
                        "type": "string",
                        "description": "GitHub 仓库,如 \"owner\/repo\""
                    },
                    "query": {
                        "type": "string",
                        "description": "搜索关键词或问题"
                    }
                },
                "required": [
                    "repo_name",
                    "query"
                ]
            }
        },
        {
            "name": "get_repo_structure",
            "description": "查看 GitHub 仓库或子目录的结构。了解项目的模块拆分与目录组织方式,快速识别关键子目录。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "repo_name": {
                        "type": "string",
                        "description": "GitHub 仓库,如 \"owner\/repo\""
                    },
                    "dir_path": {
                        "type": "string",
                        "description": "子目录路径(可选),不填则返回根目录结构"
                    }
                },
                "required": [
                    "repo_name"
                ]
            }
        },
        {
            "name": "read_file",
            "description": "读取 GitHub 仓库中单个文件的完整内容。可用于审查核心文件实现、分析模块细节、做重构建议或 Bug 分析。",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "repo_name": {
                        "type": "string",
                        "description": "GitHub 仓库,如 \"owner\/repo\""
                    },
                    "file_path": {
                        "type": "string",
                        "description": "文件在仓库中的路径,如 \"src\/index.ts\""
                    }
                },
                "required": [
                    "repo_name",
                    "file_path"
                ]
            }
        }
    ]
}

MCP shanhe v1.2.0 · Protocol: 2025-06-18 · Powered by 以潮科技