feat: 新增 ALAPI 接口平台 MCP 接入文档，更新 go.mod 依赖版本，添加 LICENSE 文件，优化主程序配置加载，支持 OpenAPI 工具初始化，注册自定义工具，完善 README 使用指南。添加腾讯云开发 MCP 接入

Author: anhao

DOC.md

@@ -0,0 +1,47 @@
+# ALAPI接口平台 MCP 接入
+
+通过 MCP 协议提供与 ALAPI 接口平台交互，可快捷查询IP归属地、天气情况、数据热榜、文本审核、短网址缩短等操作
+
+[前往云开发平台运行 MCP Server](https://tcb.cloud.tencent.com/dev#/ai?tab=mcp&p&mcp-template=mcp-alapi-cn)
+
+---
+
+## 环境变量
+
+- 需要将 **ALAPI_TOKEN** 配置为您在 ALAPI 上创建的 [TOKEN](https://www.alapi.cn/dashboard/data/token)
+
+## 🗺️ 功能清单
+
+以下仅罗列部分功能，具体请以实际调用为准
+
+| 命令名称                          | 功能描述                                          | 核心参数          |
+|-------------------------------|-----------------------------------------------|---------------|
+| user_apis                     | 获取已申请的接口列表                                    |               |
+| /api/ip                       | 查询IP归属地信息                                     | ip            |
+| /api/tianqi                   | 查询国内天气详情、包含天气信息、天气预警、天气指数、AQI 等               | city          |
+| /api/tophub                   | 查询今日热榜数据，包含抖音热搜、头条热榜、知乎、36k、百度热搜、搜狗热搜、微博热搜等数据 | id,type       |
+| /api/censor/text              | 查询文本是否违规,特别适合AI内容审核                           | text          |
+| /api/url                      | 短网址缩短，将长网址缩短为短网址，方便短信发送、二维码生成等场景              | url           |
+| /api/qr/decode                | 支持一图多码，支持数十二维码，条形码的识别                         | url           |
+| /api/eventHistory             | 历史上的今天,查历史上的指定日期发生的大事                         | date          |
+| /api/exchange                 | 汇率查询,根据货币代码查询货币汇率和换算，支持全球170+个国家和地区货币查询       | money,from,to |
+| /api/enterprise/simple_search | 企业工商信息搜索,根据企业名称或统一社会信用代码查询企业基本工商信息            | keyword       |
+| /api/kd                       | 快递查询V1,免费查询快递物流轨迹，支持中通、申通、顺丰、极兔、百世、圆通等        | numner,phone  |
+| /api/star                     | 星座运势查询,提供星座运势查询服务，支持查询十二星座今日或明日、本周、本月、本年的运势。  | star          |
+| /api/gold                     | 查询当前黄金的实时价格，最高价，最低价，品牌黄金的价格                   | market        |
+
+## 仓库地址
+
+[https://cnb.cool/alapi/mcp-alapi-cn](https://cnb.cool/alapi/mcp-alapi-cn)
+
+---
+
+## 🔌 使用方式
+
+- [在云开发 Agent 中使用](https://docs.cloudbase.net/ai/mcp/use/agent)
+- [在 MCP Host 中使用](https://docs.cloudbase.net/ai/mcp/use/mcp-host)
+- [通过 SDK 接入](https://docs.cloudbase.net/ai/mcp/use/sdk)
+
+---
+
+[云开发 MCP 控制台](https://tcb.cloud.tencent.com/dev#/ai?tab=mcp)  

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 ALAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,92 +1,117 @@
-# ALAPI MCP Server
+# 🔥 ALAPI MCP Server
 
 [![smithery badge](https://smithery.ai/badge/@ALAPI-SDK/mcp-alapi-cn)](https://smithery.ai/server/@ALAPI-SDK/mcp-alapi-cn)
+![License](https://img.shields.io/badge/license-MIT-green)
 
-这是一个基于 [ALAPI](https://www.alapi.cn) 的 MCP (Model Control Protocol) 服务器实现，可以通过MCP协议直接调用ALAPI的接口
+这是一个基于 [ALAPI](https://www.alapi.cn) 的 MCP (Model Context Protocol) 服务器实现，可以通过MCP协议直接调用ALAPI的接口，轻松将ALAPI丰富的API资源集成到各类支持MCP的AI应用中。
 
-## 功能特点
+## ✨ 功能特点
 
-- 自动加载 ALAPI OpenAPI 规范
-- 支持加载全部或指定 API (短视频解析、天气查询、每天60秒读懂世界、企业查询...)
-- 符合 MCP 协议标准
-- 统一的错误处理和响应格式
-- 支持环境变量配置
+- 🔍 **丰富API资源** - 提供IP查询、天气查询、热搜榜单、企业信息等100+种常用API服务
+- 🧩 **MCP 协议支持** - 完全兼容 Model Context Protocol，轻松集成到各类AI应用
+- 🔄 **自动加载** - 自动加载 ALAPI OpenAPI 规范，无需手动配置
+- 🎯 **灵活调用** - 支持加载全部或指定API，按需使用（短视频解析、天气查询、每天60秒读懂世界、企业查询等）
+- 🛡️ **统一响应** - 提供统一的错误处理和响应格式，简化开发流程
+- ⚙️ **可配置性** - 支持环境变量配置，轻松适应不同使用场景
 
-## 环境要求
+## 📖 使用指南
 
-- Go 1.24.1 或更高版本
-- 有效的 ALAPI Token
-- 支持 MCP 的客户端（如 Claude Desktop、Continue、Cursor 等）
+首先需要了解 [MCP](https://modelcontextprotocol.io/introduction) 协议，然后按照以下配置添加 ALAPI MCP 服务。
 
-## 安装
+## 在 MCP 客户端中使用
 
-### Installing via Smithery
+ALAPI MCP Server 设计为与支持 MCP 协议的客户端配合使用，不支持独立的命令行配置。请按照以下步骤在您的 MCP 客户端中配置使用：
 
-To install mcp-alapi-cn for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ALAPI-SDK/mcp-alapi-cn):
+### 方法一：使用 Smithery 自动安装
 
-```bash
-npx -y @smithery/cli install @ALAPI-SDK/mcp-alapi-cn --client claude
-```
+通过 [Smithery](https://smithery.ai/server/@ALAPI-SDK/mcp-alapi-cn) 安装 ALAPI MCP Server，适用于 Claude Desktop 客户端：
 
-### 构建安装
 ```bash
-#Github
-git clone https://github.com/alapi-sdk/mcp-alapi-cn.git
-
-#CNB 国内加速地址
-#git clone https://cnb.cool/alapi/mcp-alapi-cn.git
-
-cd mcp-server
-go mod tidy
-go build
+npx -y @smithery/cli install @ALAPI-SDK/mcp-alapi-cn --client claude
 ```
 
-### 下载已构建的软件包
-下载对应系统的软件包
+### 方法二：直接使用预编译二进制文件（推荐，不用安装依赖）
 
-Github: https://github.com/ALAPI-SDK/mcp-alapi-cn/releases
+1. 访问 [Releases 页面](https://github.com/ALAPI-SDK/mcp-alapi-cn/releases) 下载最新版本 
+   > 国内加速下载地址：https://cnb.cool/alapi/mcp-alapi-cn/-/releases
 
-CNB(国内加速):  https://cnb.cool/alapi/mcp-alapi-cn/-/releases
+2. 根据您的操作系统选择对应最新的版本：
+   - Windows: `mcp-alapi-cn.exe`
+   - macOS: `mcp-alapi-cn-macos`
+   - Linux: `mcp-alapi-cn-linux`
 
-## 配置和使用
+3. 在支持 MCP 的客户端（如 Claude Desktop）中配置：
+   - 打开 MCP 客户端设置
+   - 添加新的 MCP 服务器
+   - 指定下载的二进制文件路径
+   - 配置必要的环境变量（如 `ALAPI_TOKEN`）
 
-### 环境变量配置
+### 配置环境变量
 
-项目使用以下环境变量：
+#### `ALAPI_TOKEN` - ALAPI平台访问令牌（必填）
 
-- `ALAPI_TOKEN`（必需）：ALAPI 的认证令牌,在 [token管理](https://www.alapi.cn/dashboard/data/token) 里面创建, **如果不设置，mcp 会启动不了**
-- `ALAPI_ID`（可选）：指定要加载的 API ID，不设置则加载所有 API（实际的API_id 可通过 [ALAPI](https://www.alapi.cn)  官网查看，可在我的API里面查询）
+需要配置为您在 ALAPI 平台上创建的 [TOKEN](https://www.alapi.cn/dashboard/data/token)，用于接口认证。
 
+### MCP 客户端配置示例
 
-### Cursor配置方式
+在 Claude Desktop 或其他支持 MCP 的客户端中，可以参考以下配置：
 
-1. 打开Cursor设置 > 扩展 > MCP工具
-2. 添加新的MCP工具
-3. 按照以下格式填写配置：
+#### JSON 配置（使用本地二进制文件）
 
 ```json
 {
-    "mcpServers": {
-        "mcp-alapi-cn": {
-            "command": "C:\\Users\\Administrator\\实际目录\\mcp-alapi-cn.exe",
-            "env": {
-                "ALAPI_TOKEN": "xxxx",
-                "ALAPI_API_ID": "0"
-            }
-        }
+  "mcpServers": {
+    "alapi": {
+      "path": "/path/to/mcp-alapi-cn",
+      "env": {
+        "ALAPI_TOKEN": "在 ALAPI 平台申请创建的 token"
+      }
     }
+  }
 }
 ```
 
-### CherryStudio配置方式
-1. 打开 CherryStudio 设置 -> MCP 服务器 
-2. 添加MCP服务器
-3. 配置说明：
 
-名称： `MCP-ALAPI-CN`  
-类型： `STDIO`    
-命令： `C:\\Users\\Administrator\\实际目录\\mcp-alapi-cn.exe`  
-环境变量：
-```
-ALAPI_TOKEN=你的token
-```
+### 支持的 MCP 客户端
+
+根据 [MCP 文档](https://modelcontextprotocol.io/clients)，以下客户端支持 MCP 工具集成：
+
+- Claude Desktop App
+- Claude Code
+- Cursor
+- Continue
+- Cline
+- 等其他支持 MCP 协议的客户端
+
+> 注意：确保您的 MCP 客户端支持工具集成功能，请参考各客户端的具体文档进行配置。
+
+## 🛠️ 支持的功能
+
+以下是部分支持的功能，完整功能请以实际调用为准：
+
+| 功能名称     | 描述                                                                          |
+| ------------ | ----------------------------------------------------------------------------- |
+| IP查询       | 查询IP归属地信息，支持IPv4和IPv6                                              |
+| 天气查询     | 查询国内天气详情，包含天气信息、天气预警、天气指数、AQI等                     |
+| 今日热榜     | 查询今日热榜数据，包含抖音热搜、头条热榜、知乎、36k、百度热搜、微博热搜等数据 |
+| 文本审核     | 查询文本是否违规，特别适合AI内容审核                                          |
+| 短网址       | 短网址缩短，将长网址缩短为短网址，方便短信发送、二维码生成等场景              |
+| 二维码识别   | 支持一图多码，支持数十二维码，条形码的识别                                    |
+| 历史上的今天 | 查询历史上的指定日期发生的大事                                                |
+| 汇率查询     | 根据货币代码查询货币汇率和换算，支持全球170+个国家和地区货币查询              |
+| 企业查询     | 根据企业名称或统一社会信用代码查询企业基本工商信息                            |
+| 快递查询     | 免费查询快递物流轨迹，支持中通、申通、顺丰、极兔、百世、圆通等                |
+| 星座运势     | 提供星座运势查询服务，支持查询十二星座今日或明日、本周、本月、本年的运势      |
+| 黄金价格     | 查询当前黄金的实时价格，最高价，最低价，品牌黄金的价格                        |
+
+## 🔗 相关链接
+
+- [ALAPI官网](https://www.alapi.cn) - 获取API服务和Token
+- [MCP协议文档](https://modelcontextprotocol.io) - 了解更多MCP协议相关信息
+
+## 🙏 鸣谢
+
+- [ALAPI](https://www.alapi.cn) - 提供强大的API支持
+- [Model Context Protocol](https://modelcontextprotocol.io) - 提供协议标准
+
+

go.mod

@@ -5,7 +5,7 @@ go 1.24.1
 require (
 	github.com/getkin/kin-openapi v0.131.0
 	github.com/go-resty/resty/v2 v2.16.5
-	github.com/mark3labs/mcp-go v0.17.0
+	github.com/mark3labs/mcp-go v0.20.0
 )
 
 require (

go.sum

@@ -22,6 +22,8 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/mark3labs/mcp-go v0.17.0 h1:5Ps6T7qXr7De/2QTqs9h6BKeZ/qdeUeGrgM5lPzi930=
 github.com/mark3labs/mcp-go v0.17.0/go.mod h1:KmJndYv7GIgcPVwEKJjNcbhVQ+hJGJhrCCB/9xITzpE=
+github.com/mark3labs/mcp-go v0.20.0 h1:NYZDZ10GBKHVz4SdQ2tPFSDFQFKCTrTZJLn4wj6jAaw=
+github.com/mark3labs/mcp-go v0.20.0/go.mod h1:KmJndYv7GIgcPVwEKJjNcbhVQ+hJGJhrCCB/9xITzpE=
 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw=
 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8=
 github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 h1:G7ERwszslrBzRxj//JalHPu/3yz+De2J+4aLtSRlHiY=

internal/config/config.go

@@ -1,31 +1,58 @@
 package config
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"os/exec"
 	"strings"
 )
 
+// 定义 context key 类型，避免与其他包的 key 冲突
+type contextKey string
+
+// ConfigKey 是在 context 中存储 Config 的 key
+const ConfigKey contextKey = "config"
+
 type Config struct {
-	ServerName string
-	Version    string
-	OpenAPIURL string
-	BaseURL    string
-	Token      string
+	ServerName string `yaml:"server_name"`
+	Version    string `yaml:"version"`
+	BaseURL    string `yaml:"base_url"`
+	Token      string `yaml:"token"`
+	OpenAPIURL string `yaml:"openapi_url"`
 }
 
 // getVersion 从 Git tag 获取版本号
 func getVersion() string {
 	cmd := exec.Command("git", "describe", "--tags", "--abbrev=0")
 	output, err := cmd.Output()
 	if err != nil {
-		return "unknown"
+		return "latest"
 	}
 	return strings.TrimSpace(strings.TrimPrefix(string(output), "v"))
 }
 
-func NewConfig() (*Config, error) {
+// WithConfig 返回带有配置信息的新 context
+func WithConfig(ctx context.Context, cfg *Config) context.Context {
+	return context.WithValue(ctx, ConfigKey, cfg)
+}
+
+// FromContext 从 context 中获取配置信息
+func FromContext(ctx context.Context) (*Config, bool) {
+	cfg, ok := ctx.Value(ConfigKey).(*Config)
+	return cfg, ok
+}
+
+// MustFromContext 从 context 中获取配置信息，如果不存在则 panic
+func MustFromContext(ctx context.Context) *Config {
+	cfg, ok := FromContext(ctx)
+	if !ok {
+		panic("config not found in context")
+	}
+	return cfg
+}
+
+func NewConfig(ctx context.Context) (*Config, error) {
 	token := os.Getenv("ALAPI_TOKEN")
 	if token == "" {
 		return nil, fmt.Errorf("ALAPI_TOKEN environment variable is required")

internal/handler/tool_handler.go renamed to internal/handler/openapi_tool_handler.go

@@ -10,21 +10,21 @@ import (
 	"github.com/mark3labs/mcp-go/mcp"
 )
 
-type ToolHandler struct {
+type OpenAPIToolHandler struct {
 	baseURL string
 	token   string
 	client  *resty.Client
 }
 
-func NewToolHandler(baseURL string, token string) *ToolHandler {
-	return &ToolHandler{
+func NewOpenAPIToolHandler(baseURL string, token string) *OpenAPIToolHandler {
+	return &OpenAPIToolHandler{
 		baseURL: baseURL,
 		token:   token,
 		client:  resty.New(),
 	}
 }
 
-func (h *ToolHandler) Handle(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+func (h *OpenAPIToolHandler) Handle(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	arguments := request.Params.Arguments
 	uri := request.Params.Name
 
@@ -49,8 +49,7 @@ func (h *ToolHandler) Handle(ctx context.Context, request mcp.CallToolRequest) (
 		return nil, fmt.Errorf("unmarshal response failed: %w", err)
 	}
 	if baseResp.Code != 200 {
-		// return nil, fmt.Errorf("api response failed:%s", baseResp.Message)
-		return mcp.NewToolResultText(baseResp.Message), nil
+		return nil, fmt.Errorf("request params error: %s", baseResp.Message)
 	}
 
 	// 只返回 data 部分的数据