技术文档摘要

<!-- 项目质量徽章 -->

🌤️ 天气MCP服务器 - 清洁架构版 [Docker + Redis]

<div align="center">

</div>

天气MCP服务器 - 适用于Claude桌面的清洁架构版本 - 生产就绪

Claude AI通过SOLID原则转变为专业气象站

<br>

🎉 当前版本：2.0.0 - 完整的清洁架构 ✅ 重构完成 • ✅ 零遗留代码 • ✅ 生产就绪

📊 项目状态

外观	状态	描述
构建		TypeScript编译 + Docker构建
测试		单元测试 + 集成测试
安全		Trivy漏洞扫描 + npm审计
Docker		优化的多阶段构建
部署		自动化的CI/CD流水线

🔄 CI/CD流水线

此项目实现了完整的CI/CD流水线，使用GitHub Actions：

🔍 代码检查与类型检查 → 🧪 测试 → 🏗️ 构建 → 🔒 安全 → 🐳 Docker → 🚀 部署

流水线阶段：

• 🔍 代码检查与类型检查：ESLint + TypeScript编译检查
• 🧪 测试：单元测试（带模拟）+ 集成测试（使用PostgreSQL/Redis）
• 🏗️ 构建：TypeScript编译 + 生成工件
• 🔒 安全：Trivy漏洞扫描器 + npm审计
• 🐳 Docker：多阶段构建 + 推送到GitHub容器注册表
• 🚀 部署：自动部署到staging/生产环境

本地测试命令：

npm run test:unit        # 单元测试（无依赖）
npm run test:integration # 集成测试（需要Docker）
npm run test:ci          # CI测试带覆盖率

---

🎯 这个项目是什么？

天气MCP服务器 是一个模型上下文协议（MCP） 服务器，扩展了Claude桌面的功能，使其能够使用干净且专业的架构从世界各地获取实时天气信息。

🧠 理解MCP（模型上下文协议）

MCP 是Anthropic开发的一个协议，允许Claude AI：

• 🔌 连接外部API 和数据库
• 🛠️ 使用自定义工具 由社区创建
• 📊 访问实时数据 不在知识库中的数据
• 🎮 执行特定操作 通过插件

换句话说，MCP将Claude从一个知识有限的AI转变为可以访问来自现实世界的更新信息 的AI！

🌟 可用功能

🎯 功能	📋 描述	💡 使用示例
🌡️ 当前气候	检查温度、湿度、气压和当前天气状况	"圣保罗现在的温度是多少？"
🔮 天气预报 提供未来5天的详细预报。"伦敦明天的天气会怎么样？"
📊 历史天气 跟踪所有查询记录。"显示我最近做的天气检查"
⚡ 智能缓存	使用Redis系统进行超快速查询	95%的查询来自缓存

---

🚀 实际演示

之前（没有MCP的Claude桌面）：

🙋 你："东京现在的温度是多少？"
🤖 Claude："对不起，我没有实时气象数据的访问权限..."

之后（带有天气MCP服务器的Claude桌面）：

🙋 你："东京现在的温度是多少？"
🤖 Claude："🌤️ 东京现在：
           🌡️ 温度：23°C（体感温度：25°C）
           💧 湿度：68%
           🌬️ 风速：12公里/小时
           ☁️ 天气状况：部分多云
           📊 数据实时更新，来自OpenWeatherMap"

---

🏗️ 清洁 + SOLID架构

graph TB
    subgraph "🎮 表现层"
        A[👤 Claude桌面] --> B[🤖 MCP服务器]
        B --> C[🎮 天气控制器]
        B --> D[🎮 历史控制器]
    end
    
    subgraph "🔧 应用层（用例）"
        C --> E[🌤️ 获取天气用例]
        C --> F[🔮 获取预报用例]  
        C --> G[📊 获取缓存统计用例]
        D --> H[📚 获取历史用例]
    end
    
    subgraph "🏛️ 领域层"
        E --> I[⚡ 天气实体]
        F --> I
        H --> J[📊 历史实体]
        K[🔗 仓库接口]
    end
    
    subgraph "🏗️ 基础设施层（适配器）"
        E --> L[🌍 OpenWeather API仓库]
        E --> M[🗄️ PostgreSQL仓库]
        E --> N[⚡ Redis缓存仓库]
        F --> L
        F --> N
        H --> M
        L --> O[🌤️ OpenWeatherMap API]
        M --> P[🗄️ PostgreSQL数据库]
        N --> Q[⚡ Redis缓存]
    end

✅ 应用的SOLID原则：

🔤 原则	✅ 如何应用	💡 好处
S - 单一职责	每个类只有一个责任	更干净、更专注的代码
O 开闭原则	通过接口可扩展，对修改关闭	添加新API很容易
L 里氏替换原则	通过契约实现可互换的实现	总的灵活性
I 接口隔离原则	小而具体的接口	没有不必要的依赖
D 依赖倒置原则	通过抽象注入依赖	可测试性和解耦

---

📋 先决条件

🔧 所需软件：

📦 软件	📏 最低版本	🔗 下载	✅ 验证
Node.js	18.0+	nodejs.org	node --version
Docker Desktop 最新版本	docker.com	docker --version
Claude Desktop 最新版本	claude.ai/download 打开应用程序。
Git	任意版本	git-scm.com	git --version

🔑 API密钥：

1. 🌍 OpenWeatherMap API密钥（免费）
   • 🔗 访问：openweathermap.org/api
   • 📝 创建免费账户
   • 🗝️ 获取您的API密钥（免费）
   • 💡 允许每天1000次免费查询

---

📥 完整安装

🗂️ 步骤1：下载项目

# 克隆仓库
git clone https://github.com/glaucia86/weather-mcp-server.git

# 进入文件夹
cd weather-mcp-server

# 查看结构
ls -la

📦 步骤2：安装依赖

# 安装Node.js包
npm install

# 验证安装
npm list --depth=0

⚙️ 步骤3：配置环境

创建文件.env：

# 复制示例
cp .env.example .env

配置.env：

# 🌍 OpenWeatherMap API（必需）
WEATHER_API_KEY=你的API密钥

# 🗄️ 数据库（PostgreSQL）
DATABASE_URL=postgresql://mcp_user:mcp_pass@localhost:5432/weather_mcp

# ⚡ 缓存（Redis） 
REDIS_URL=redis://localhost:6379

# 🖥️ 服务器配置
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

🔨 步骤4：编译并启动

# 编译TypeScript
npm run build

# 启动基础设施（PostgreSQL + Redis）
npm run docker:up

# 等待初始化
sleep 30

# 测试系统
npm run test:manual

---

🎮 Claude桌面配置

📍 查找配置文件：

🖥️ 系统	📂 文件路径
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

⚙️ 配置：

{
  "mcpServers": {
    "weather-mcp": {
      "command": "node",
      "args": ["/完整路径/weather-mcp-server/dist/mcp-entry.js"],
      "env": {
        "WEATHER_API_KEY": "你的OpenWeatherMap API密钥",
        "DATABASE_URL": "postgresql://mcp_user:mcp_pass@localhost:5432/weather_mcp",
        "REDIS_URL": "redis://localhost:6379",
        "NODE_ENV": "production",
        "LOG_LEVEL": "error",
        "MCP_MODE": "true"
      }
    }
  }
}

⚠️ 重要提示：

• 替换 /完整路径/ 为实际路径
• 替换 你的OpenWeatherMap API密钥 为你的OpenWeatherMap密钥
• 完全关闭 Claude桌面，保存后重新打开

---

🎪 如何使用

1️⃣ 当前气候咨询

💬 "圣保罗现在的天气怎么样？"
💬 "伦敦现在的天气怎么样？"
💬 "里约热内卢现在的温度是多少？"

2️⃣ 天气预报

💬 "巴黎明天的天气预报是什么？"
💬 "东京未来三天的天气会怎么样？"
💬 "伦敦未来五天的天气预报"

3️⃣ 历史和分析

💬 "显示我的气象查询历史"
💬 "我最后查询的城市有哪些？"
💬 "圣保罗过去10条记录的气候历史"

4️⃣ 系统统计

💬 "显示Redis缓存的统计信息"
💬 "系统的性能如何？"

---

🛠️ 可用脚本

🎯 目的	💻 命令	📋 描述
启动服务器	npm start	主服务器
MCP服务器	npm run start:mcp	用于Claude桌面的MCP服务器
构建	npm run build 编写TypeScript。
测试MCP	npm run test:manual 测试MCP服务器。
开发模式	npm run dev	带热重载的开发
清理	npm run clean	删除之前的构建
Docker启动	npm run docker:up 启动PostgreSQL + Redis。
Docker停止	npm run docker:down`	停止容器
迁移	npm run migrate	执行数据库迁移

---

🏗️ 项目结构

src/
├── 🏛️ domain/                    # 领域层（业务规则）
│   ├── entities/                # 领域实体
│   │   └── Weather.ts          # 气象模型
│   └── repositories/           # 合同/接口
│       └── IRepositories.ts    # 仓库接口
│
├── 🔧 application/              # 应用层（用例）
│   └── usecases/               # 特定用例
│       ├── GetCurrentWeatherUseCase.ts
│       ├── GetWeatherForecastUseCase.ts
│       ├── GetWeatherHistoryUseCase.ts
│       └── GetCacheStatisticsUseCase.ts
│
├── 🏗️ infrastructure/          # 基础设施层（适配器）
│