MCP Server

MCP（Model Context Protocol）让 AI 工具以结构化方式调用 crt.sh。本项目提供 20 个工具，支持 stdio / SSE / HTTP 三种传输。

cmd/mcp-server20 工具stdio/SSE/HTTPmark3labs/mcp-go

三种传输模式

📟stdio

本地 AI 客户端默认；子进程通信，零网络

📡SSE

Server-Sent Events；需 `--base-url` 公网可达

🌐HTTP

Streamable HTTP；现代推荐

按部署场景选传输：

flowchart TD Q["AI 客户端在哪跑？"] --> Q1{本地同一台机?} Q1 -->|是| STDIO["stdio
子进程，零网络，默认"] Q1 -->|否, 远程访问| Q2{客户端支持
Streamable HTTP?} Q2 -->|是| HTTP["http
现代推荐"] Q2 -->|否, 只支持 SSE| SSE["sse
需 --base-url 公网可达"]

三种启动方式

# mcp-server --transport stdio
# mcp-server --transport sse --addr :8080 --base-url https://my.host
# mcp-server --transport http --addr :8080
# SSE/HTTP 带 SIGINT/SIGTERM 优雅关停；--version 看版本

接入 Claude Code / Desktop

json

{
  "mcpServers": {
    "crt-sh-skills": {
      "command": "go",
      "args": ["run", "github.com/cyberspacesec/crt.sh-skills/cmd/mcp-server@latest", "--transport", "stdio"]
    }
  }
}

用预编译二进制更稳

见 Release 发布流程下载对应平台的二进制，把 command 换成二进制路径、args 去掉 go run，启动更快、不依赖 Go 工具链。

20 个工具一览

工具	关键参数	对应 SDK 方法
`search_certificates`	`query`、`search_type`、`match`、`exclude_expired`、`deduplicate`、`issuer_ca_id`、`group`、`sort`、`dir`、`linter`、`lint_type`、`page`、`page_size`	`SearchCertificates`
`export_search_json`	同上	`FetchSearchJSON`
`export_search_csv`	同上	`FetchSearchCSV`
`export_search_atom`	同上	`FetchSearchAtomFeed`
`get_certificate`	`id`、`opt`（nometadata/ocsp/pkimetal）	`GetCertificateByID`
`get_ct_entry`	`ct_entry_id`	`FetchCTEntryByID`
`get_atom_feed`	`identity`、`match`、`exclude_expired`	`FetchAtomFeed`
`get_raw_certificate`	`id`	`FetchRawCertificate`
`generate_add_chain`	`certificate_pem`	`GenerateAddChainJSON`
`get_asn1_view`	`id`	`FetchASN1View`
`get_hierarchy_view`	`id`	`FetchHierarchyView`
`get_graph_view`	`id`	`FetchGraphView`
`get_path_validation_view`	`id`	`FetchPathValidationView`
`get_advanced_search_page`	—	`FetchAdvancedSearchPage`
`get_cert_populations`	`group`（可选 RootOwner）	`FetchCertificatePopulations`
`get_info_page`	`page`（13 选 1）	`FetchInfoPage`
`get_ca`	`ca_id`	`FetchCAByID`
`get_issuer_certificates`	`ca_id`	`FetchIssuerCertificatesByCAID`
`search_censys`	`search_type`、`value`	`BuildCensysURL`
`list_supported_options`	—	registry + InfoPages

一次工具调用的完整流程

sequenceDiagram participant AI as AI 客户端 participant SRV as mcp-server participant SDK as pkg/crtsh participant CRT as crt.sh AI->>SRV: MCP RPC: search_certificates(query=...) SRV->>SRV: 参数映射 → QueryParams SRV->>SDK: client.SearchCertificates(ctx, params) SDK->>SDK: Validate + buildQuery + 限流 SDK->>CRT: HTTP GET ?q=...&output=json CRT-->>SDK: JSON + Link header SDK-->>SRV: []Certificate + Pagination SRV->>SRV: 格式化为 MCP 结果 SRV-->>AI: 工具返回（结构化）

每个工具处理函数只做三件事：参数映射 → 调 SDK → 格式化输出，零业务逻辑——这是分层的好处。

list_supported_options 的妙用

flowchart LR AI[AI 不确定有哪些合法选项] --> LSO["调 list_supported_options"] LSO --> RG["registry 单一来源"] RG --> R["拿到全部搜索类型/匹配模式/linter/信息页"] R --> AI2["AI 据此正确填参"] AI2 --> CALL["再调业务工具"]

为什么这是关键

AI 不靠硬编码或猜选项，而是自服务地发现合法值。这让 AI "真正会用" crt.sh，而不是瞎填参数碰运气。

错误透传

SDK 的 typed error 被翻译成工具调用错误返回，AI 能据此做不同决策：

⚠️InvalidError

参数填错 → AI 修正后重试

🔍NotFoundError

真没这个证书 → AI 换思路

⏳RateLimitError

被限流 → AI 等待重试

🔥ServerError

crt.sh 5xx → AI 退避

CLI 命令行

MCP Server ​

三种传输模式 ​

接入 Claude Code / Desktop ​

20 个工具一览 ​

一次工具调用的完整流程 ​

list_supported_options 的妙用 ​

错误透传 ​