MCP shanhe API
统一的 MCP (Model Context Protocol) 网关服务,提供 AI 视觉分析、联网搜索、网页阅读与 GitHub 仓库理解能力。
快速开始
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 端点
| 端点 | 方法 | 说明 |
|---|---|---|
/mcp | POST | Streamable HTTP 传输 |
/sse | GET | SSE 传输 |
/messages | POST | SSE 消息发送 |
/health | GET | 健康检查 |
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. |
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). |
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. |
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...). |
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. |
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" |
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
|
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
}
联网搜索 (2 个工具)
web_search
通过 AI 增强的搜索引擎获取结构化网络信息,支持多维度过滤。返回结果包含标题、摘要、链接及内容长度控制,可限定特定域名、时间范围和内容体量。
使用场景
- • 竞品官网信息监控
- • 学术论文时效性检索
- • 新闻事件多源验证
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
query |
string | 是 | 搜索关键词(支持布尔逻辑) |
count |
number | 否 | 返回结果数量(1-50) |
domain_filter |
string | 否 | 限定域名(如 example.com) |
recency_filter |
string | 否 |
时间范围(天数) 可选值: noLimit, oneDay, oneWeek, oneMonth, oneYear
|
content_size |
string | 否 |
内容长度限制(字符数) 可选值: low, medium, high
|
调用示例
{
"name": "web_search",
"arguments": {
"query": "quantum computing breakthrough",
"count": 5,
"domain_filter": "nature.com",
"recency_filter": 30,
"content_size": 500
}
}
返回示例
{
"content": [
{
"title": "New Quantum Algorithm Achieves...",
"link": "https:\/\/nature.com\/articles\/...",
"snippet": "Researchers demonstrate 100x speedup..."
}
],
"isError": false
}
web_search_in_chat
结合实时搜索与 AI 生成的智能问答系统。先获取网络信息作为上下文,再通过自定义提示词生成结构化回答,支持领域知识增强和输出格式控制。
使用场景
- • 客服系统实时知识更新
- • 研究报告动态数据整合
- • 多语言信息交叉验证
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
query |
string | 是 | 核心搜索问题 |
prompt |
string | 否 | 回答生成指令(如'用表格对比') |
count |
number | 否 | 参考结果数量 |
domain_filter |
string | 否 | 可信域名白名单 |
recency_filter |
string | 否 |
信息时效要求(天数) 可选值: noLimit, oneDay, oneWeek, oneMonth, oneYear
|
调用示例
{
"name": "web_search_in_chat",
"arguments": {
"query": "2024 奥运会新增项目",
"prompt": "用 bullet points 列出项目并说明起源国家",
"count": 3,
"domain_filter": "olympics.com",
"recency_filter": 90
}
}
返回示例
{
"content": "• 霹雳舞(法国)\n• 滑板(日本)\n• 攀岩(奥地利)",
"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\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 以潮科技