接口说明

接入说明

基础地址按站点域名拼接，所有请求使用 HTTPS。
接口统一返回 JSON，成功结构为 { "ok": true, "toolName": "...", "data": ... }。
分页类工具统一返回 pageIndex/pageSize/totalPageCount/totalItemCount/isPreviousPage/isNextPage/items。

鉴权方式

X-API-Key: your_api_key

GET /mcp

返回服务元信息和工具入口地址。

{
  "name": "HSCIQ2 MCP",
  "version": "1.0",
  "toolsEndpoint": "/mcp/tools/list",
  "callEndpoint": "/mcp/tools/call"
}

POST /mcp/tools/list

返回可用工具与输入参数定义。

curl -X POST "https://www.hsciq.com/mcp/tools/list" ^
  -H "Content-Type: application/json" ^
  -H "X-API-Key: your_api_key"

{
  "version": "1.0",
  "tools": [
    { "name": "search_instance" },
    { "name": "search_code" },
    { "name": "search_unified" },
    { "name": "get_code_detail" }
  ]
}

POST /mcp/tools/call（search_instance / search_code / search_unified）

前三个工具都通过该入口调用，返回统一分页结构。

curl -X POST "https://www.hsciq.com/mcp/tools/call" ^
  -H "Content-Type: application/json" ^
  -H "X-API-Key: your_api_key" ^
  -d "{
    ""toolName"": ""search_code"",
    ""arguments"": {
      ""keywords"": ""塑料软管"",
      ""country"": ""CN"",
      ""pageIndex"": 1,
      ""pageSize"": 10,
      ""filterFailureCode"": true
    }
  }"

分页外层字段：pageIndex、pageSize、totalPageCount、totalItemCount、isPreviousPage、isNextPage、items。
items 类型：search_instance → InstanceSearchResult[]，search_code → CNCode[]/JPCode[]/USCode[]，search_unified → CIQ[]/HazardousChemicals[]/PortSearchResult[]。

POST /mcp/tools/call（get_code_detail）

按国家+编码返回非分页详情对象。

{
  "toolName": "get_code_detail",
  "arguments": {
    "country": "CN",
    "code": "3926909090"
  }
}

详细返回字段见下方 get_code_detail 接口章节。

search_instance 返回参数字段说明

items 类型：InstanceSearchResult[]

字段	类型	说明
`pageIndex`	int	当前页
`pageSize`	int	每页条数
`totalPageCount`	int	总页数
`totalItemCount`	int	总条数
`isPreviousPage`	bool	是否有上一页
`isNextPage`	bool	是否有下一页
`items[].InstanceName`	string	实例名（高亮版本）
`items[].InstanceNamePlain`	string	实例名纯文本
`items[].Count`	int	关联条数
`items[].IndexDocumentId`	string	索引文档ID
`items[].IndexTokens`	string[]	检索分词
`items[].IndexInstanceNameTokens`	string[]	实例名分词
`items[].IndexInstanceNameAsciiTokens`	string[]	实例名ASCII分词
`items[].IndexCategoryNameTokens`	string[]	类目分词
`items[].Index2CodeNameTokens`	string[]	2位类目分词
`items[].Index4CodeNameTokens`	string[]	4位类目分词
`items[].Index6CodeNameTokens`	string[]	6位类目分词
`items[].MatchRank`	double	匹配排序得分
`items[].ShortNamePenalty`	double	短词惩罚项
`items[].ChineseHitPenalty`	double	中文命中惩罚项
`items[].PrimaryHitPenalty`	double	主命中惩罚项
`items[].MissingTokens`	int	未命中词数
`items[].MissingRatio`	double	未命中比例
`items[].MatchedTokens`	int	命中词数
`items[].OrderPenalty`	double	顺序惩罚
`items[].SpanLen`	int	跨度长度
`items[].FirstPos`	int	首命中位置
`items[].NameLength`	int	名称长度
`items[].MaxScore`	double	最大原始分值
`items[].CategoryResults`	array	类目树结果

search_code 返回参数字段说明

items 类型：CNCode[] / JPCode[] / USCode[]

分页外层字段

字段	类型	说明
`pageIndex`	int	当前页
`pageSize`	int	每页条数
`totalPageCount`	int	总页数
`totalItemCount`	int	总条数
`isPreviousPage`	bool	是否有上一页
`isNextPage`	bool	是否有下一页
`items`	array	结果列表，具体项类型取决于 country

公共字段（CN/JP/US）

字段	类型	说明
`Status`	int	状态值
`CreateTime`	datetime?	创建时间
`UpdateTime`	datetime?	更新时间
`Unit1`	string?	法定第一计量单位
`Unit2`	string?	法定第二计量单位
`UnitofMeasure`	string?	计量单位描述
`Code`	string	海关编码
`Name`	string	编码名称
`CategoryId`	string?	类目ID
`CategoryName`	string?	类目名称
`_2Code`	string	2位编码
`_2CodeName`	string	2位编码名称
`_4Code`	string	4位编码
`_4CodeName`	string	4位编码名称
`_6Code`	string	6位编码
`_6CodeName`	string	6位编码名称

CNCode 扩展字段

字段	类型	说明
`OldData`	object	中国税则原始对象
`Import`	string?	进口税率摘要
`Export`	string?	出口税率摘要
`RCEP`	string?	RCEP税率摘要
`CT`	string?	协定税率摘要
`ExportRebateCode`	string?	出口退税码
`Remark`	string?	备注
`Tokens`	string[]	检索分词
`DocumentId`	string	索引文档ID

JPCode 扩展字段

字段	类型	说明
`General`	string?	一般税率
`Temporary`	string?	暂定税率
`WTO`	string?	WTO税率
`GSP`	string?	普惠税率
`LDC`	string?	最不发达国家税率
`Asean`	string?	东盟税率
`Singapore`	string?	新加坡税率
`Mexico`	string?	墨西哥税率
`Malaysia`	string?	马来西亚税率
`Chile`	string?	智利税率
`Thailand`	string?	泰国税率
`Indonesia`	string?	印尼税率
`Brunei`	string?	文莱税率
`Philippines`	string?	菲律宾税率
`Switzerland`	string?	瑞士税率
`Vietnam`	string?	越南税率
`India`	string?	印度税率
`Peru`	string?	秘鲁税率
`Australia`	string?	澳大利亚税率
`Mongolia`	string?	蒙古税率
`CPTPP`	string?	CPTPP税率
`EU`	string?	欧盟税率
`UK`	string?	英国税率
`US`	string?	美国税率
`RCEP_China`	string?	RCEP中国税率
`RCEP_Korea`	string?	RCEP韩国税率
`RCEP_Australia`	string?	RCEP澳洲税率
`Law`	string?	法律备注
`Tokens`	string[]	检索分词
`DocumentId`	string	索引文档ID

USCode 扩展字段

字段	类型	说明
`Indent`	string?	层级缩进标记
`GeneralRateofDuty`	string?	一般税率
`SpecialRateofDuty`	string?	特别税率
`Column2RateofDuty`	string?	第二栏税率
`QuotaQuantity`	string?	配额数量
`AdditionalDuties`	string?	附加税说明
`Tokens`	string[]	检索分词
`DocumentId`	string	索引文档ID

search_unified 返回参数字段说明

items 类型：CIQ[] / HazardousChemicals[] / PortSearchResult[]

分页外层字段

字段	类型	说明
`pageIndex`	int	当前页
`pageSize`	int	每页条数
`totalPageCount`	int	总页数
`totalItemCount`	int	总条数
`isPreviousPage`	bool	是否有上一页
`isNextPage`	bool	是否有下一页
`items`	array	结果列表，具体项类型取决于 unifiedType

当 unifiedType=ciq（CIQ）

字段	类型	说明
`Status`	int	状态值
`CreateTime`	datetime?	创建时间
`UpdateTime`	datetime?	更新时间
`Code`	string	海关编码
`Id`	string	CIQ项目编号
`Name`	string	CIQ项目名称
`Number`	string	监管条件编号
`Tokens`	string[]	检索分词
`DocumentId`	string	索引文档ID

当 unifiedType=hazardous（HazardousChemicals）

字段	类型	说明
`Id`	int	危化品主键
`Name`	string	危化品名称
`Alias`	string?	别名
`CAS`	string?	CAS号
`HSCode`	string?	关联HS编码
`Remarks`	string?	备注
`CreateTime`	datetime	创建时间
`Tokens`	string[]	检索分词
`DocumentId`	string	索引文档ID

当 unifiedType=port（PortSearchResult）

字段	类型	说明
`Id`	int	港口主键
`Code`	string	港口代码（高亮版本）
`CodePlain`	string	港口代码纯文本
`CName`	string	中文名（高亮版本）
`CNamePlain`	string	中文名纯文本
`EName`	string	英文名（高亮版本）
`ENamePlain`	string	英文名纯文本
`Country`	object?	国家对象，含 `Id`/`Name`
`ShippingLine`	object?	航线对象，含 `Id`/`Name`

get_code_detail 返回参数字段说明

返回对象类型：MCPCodeDetailResult（非分页）

顶层字段

字段	类型	说明
`Country`	string	国家：CN / JP / US
`Code`	string	海关编码
`Name`	string	编码名称
`Status`	int	状态值
`UpdateTime`	datetime?	更新时间
`Unit1`	string?	法定第一计量单位
`Unit2`	string?	法定第二计量单位
`UnitOfMeasure`	string?	计量单位描述
`Remark`	string?	备注
`Taxes`	Dictionary<string,string>	税率键值映射
`Extensions`	object	分国家扩展对象

Taxes 常见键

国家	键名示例	说明
CN	`mfnImportRate`、`generalImportRate`、`vatRate`、`exportTaxRebateRate`	中国税率键
JP	`general`、`temporary`、`wto`、`rcepChina`	日本税率键
US	`generalRateOfDuty`、`specialRateOfDuty`、`column2RateOfDuty`	美国税率键

Extensions.Cn

字段	类型	说明
`Reporting`	array	申报要素列表（MCPCodeItem）
`Regulatory`	Dictionary<string,string>	监管条件映射
`Inspect`	Dictionary<string,string>	检验检疫映射
`Ciqs`	array	CIQ列表（MCPCodeItem）
`HsMap`	array	税号注释映射（MCPCodeItem）
`ExportRebateCodes`	array	出口退税码列表（MCPExportRebateCodeItem）
`Ct`	Dictionary<string,string>	协定税率映射
`Rcep`	Dictionary<string,string>	RCEP税率映射

Extensions.Jp

字段	类型	说明
`AgreementRates`	Dictionary<string,string>	日本协定税率映射

Extensions.Us

字段	类型	说明
`QuotaQuantity`	string?	配额数量
`AdditionalDuties`	string?	附加税说明

明细对象

对象	字段	说明
`MCPCodeItem`	`Key`	键值（代码/序号）
`MCPCodeItem`	`Value`	显示文本
`MCPCodeItem`	`IsRequired`	是否必填
`MCPExportRebateCodeItem`	`Id`	退税扩展码
`MCPExportRebateCodeItem`	`Name`	退税名称
`MCPExportRebateCodeItem`	`Rate`	退税率

错误码说明

HTTP	error	含义
401	`invalid_api_key`	API key 无效或缺失
400	`invalid_params`	参数不合法
400	`forbidden_keyword`	关键词触发拦截
500	`internal_error`	服务器内部错误