介绍
MCSearch 统一 API 概览 —— 基础地址、通用响应头与公共参数。
MCSearch 对外提供统一的 HTTP / SSE API,覆盖服务器状态查询、状态 Banner、服务器图标、
Mod 聚合搜索与 Wiki 代理等能力。所有接口无需鉴权,默认允许跨域调用(支持 OPTIONS 预检)。
基础地址
线上服务部署于 https://search.tecostudio.cn,所有接口位于 /api/v1 路径下,例如:
https://search.tecostudio.cn/api/v1/server/status?host=mc.hypixel.net
通用响应头
每个 /api/v1/* 接口都会返回以下响应头:
| 响应头 | 说明 |
|---|---|
X-Powered-By | 固定为 MCSearch |
X-Cache | HIT 命中缓存 / MISS 未命中 |
X-Response-Time | 服务端处理耗时(毫秒) |
Access-Control-Allow-Origin | *,允许任意来源跨域 |
限流
除 /api/v1/health 外的 /api/v1/* 接口按客户端 IP 限流(默认每分钟 60 次,可由
RATE_LIMIT_RPM 配置;未配置 Redis 时不限流)。每个响应附带以下响应头,超限时返回
429 并带 Retry-After:
| 响应头 | 说明 |
|---|---|
X-RateLimit-Limit | 当前窗口的请求上限 |
X-RateLimit-Remaining | 当前窗口剩余可用次数 |
X-RateLimit-Reset | 窗口重置的 Unix 时间戳(秒) |
公共参数
服务器类接口共用以下查询参数:
| 参数 | 必填 | 说明 |
|---|---|---|
host | 是 | 服务器地址(域名或 IP) |
port | 否 | 端口;缺省时走 SRV 解析或版本默认端口 |
edition | 否 | java(默认)/ bedrock / auto |
接口一览
- 服务器状态查询 — SSE 实时状态
- 状态 Banner — PNG 状态横幅
- 服务器图标 — PNG favicon
- Mod 聚合搜索 — 多来源聚合搜索
- Mod 搜索来源列表 — 可用来源发现
- Wiki 全文搜索 — zh.minecraft.wiki 全文搜索
- Wiki 词条摘要 — 词条摘要 + 缩略图
- Wiki 搜索建议 — 标题自动补全
想直接试一试?打开 Playground 在浏览器里调用任意接口。