Multimodel MCP

🤖 多模型MCP-全栈AI助手

全面 全栈应用程序 合作演出 双子座AI 与 模型上下文协议（MCP） 用于多模式交互的服务器。将自然语言处理与实时天气数据和安全的文件系统操作相结合 网络界面 和 CLI客户端.

🌟 主要亮点

• 🤖 Gemini AI集成 -由谷歌Gemini 2.5 Pro提供技术支持
• 🌤️ 实时天气 -美国国家气象局API集成
• 📁 安全文件操作 -路径验证文件系统管理
• 🌐 web界面 -现代Next.js React应用程序
• 💻 CLI客户端 -基于终端的直接交互
• 🔄 MCP协议 -行业标准工具调用架构
• ⚡ FastAPI桥 -HTTP垫片将web前端连接到MCP服务器
• 🎨 现代用户界面 -顺风CSS+TypeScript+React组件

🏗️ 架构概述

系统架构

┌─────────────────────────────────────────────────────────────────────┐
│                          🌐 Web Frontend                             │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  Next.js React App (Port 3000)                                │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │ │
│  │  │  Chat Page  │ │ Weather Page│ │ Files Page │              │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘              │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────┘
                      │ HTTP API Calls (REST)
                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        ⚡ HTTP Shim (Port 8003)                      │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  FastAPI Bridge Application                                   │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │ │
│  │  │ /api/chat   │ │ /api/weather│ │ /api/fs     │              │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘              │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────┘
                      │ MCP Protocol
           ┌──────────┴──────────┐
           │                     │
           ▼                     ▼
┌─────────────────────┐ ┌─────────────────────┐
│   🌤️ Weather       │ │   📁 File System    │
│   MCP Server        │ │   MCP Server        │
│  (Port 8001)        │ │  (Port 8002)        │
│                     │ │                     │
│  ┌─────────────┐    │ │  ┌─────────────┐    │
│  │ NWS API     │    │ │  │ Local FS    │    │
│  │ weather.gov │    │ │  │ Operations  │    │
│  └─────────────┘    │ │  └─────────────┘    │
└─────────────────────┘ └─────────────────────┘
           │                     │
           └──────────┬──────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        🧠 Gemini AI Agent                           │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  Natural Language Processing                                  │ │
│  │  Tool Calling & Orchestration                                 │ │
│  │  Multi-step Task Execution                                    │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

数据流示例

用户请求: *“检查加利福尼亚州的天气并将今天的预报保存到文件中”*

1. User → Web Frontend (React Component)
2. Frontend → HTTP API (/api/chat)
3. API Route → HTTP Shim (FastAPI)
4. HTTP Shim → Gemini AI Agent (via MCP)
5. Agent → Weather Server (get_alerts)
6. Agent → File Server (write_file)
7. Results → HTTP Shim → Frontend → User

技术栈

• 主要亮点
• 架构概述
• 特性
• 项目结构
• 安装
• 快速开始
• 使用指南
• web界面
• CLI接口
• api参考
• 发展
• 故障排除
• 贡献

✨ 核心功能

🤖 高级AI集成

• 双子座2.5 Pro：最先进的多模式语言模型
• 自然语言处理：理解复杂的请求和意图
• 工具调用架构：用于可靠功能执行的MCP协议
• 对话记忆：情境感知多回合对话
• 智能规划：将复杂任务分解为可执行步骤

🌐 双界面选项

Web界面（推荐）

• 现代用户界面：Next.js 16+React 19+TypeScript
• 响应式设计：顺风CSS样式
• 实时聊天：带有加载状态的流式响应
• 专用页面：聊天、天气和文件管理的单独界面
• API集成：连接到MCP后端的RESTful端点

CLI接口

• 终端接入：直接命令行交互
• 脚本自动化：易于与其他工具集成
• 后台处理：运行长时间运行的任务
• 调试支持：详细的日志记录和错误报告

🛠️ MCP服务器生态系统

• 天气服务器：实时NWS API集成（50个状态）
• 文件系统服务器：通过路径验证保护本地文件操作
• HTTP Shim：连接web前端和MCP服务器的FastAPI桥
• 并发执行：多台服务器同时运行
• 协议遵从：完全遵守MCP规范

🔒 安全性和可靠性

• 路径安全：系统目录中的文件操作被阻止(/etc, /usr, C:\Windows)
• 输入验证：所有用户输入都经过验证和消毒
• 误差边界：全面的错误处理和用户反馈
• API保护：限速和配额管理
• 安全操作：对敏感资源的受控访问

📊 丰富的数据集成

• 天气情报：官方NWS数据，包括警报、预报和条件
• 文件元数据：完整的文件信息（大小、权限、时间戳）
• 结构化输出：所有操作中一致的JSON响应
• 实时更新：来自外部API和本地文件系统的实时数据
• 交叉平台的：适用于Windows、macOS和Linux

🔄 系统架构和工作流程

架构图

┌─────────────────────────────────────────────────────────────────┐
│                    🤖 User Interaction Layer                     │
│  "Check California weather and save today's forecast to file"   │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                🧠 Gemini AI Agent (mcp-use)                     │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Natural Language Processing                           │    │
│  │  Task Planning & Decomposition                         │    │
│  │  Multi-step Execution Orchestration                    │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────────────┘
                      │
           ┌──────────┴──────────┐
           │                     │
           ▼                     ▼
┌─────────────────────┐ ┌─────────────────────┐
│   🌤️ Weather       │ │   📁 File System    │
│   MCP Server        │ │   MCP Server        │
│  (Port 8001)        │ │  (Port 8002)        │
│                     │ │                     │
│  ┌─────────────┐    │ │  ┌─────────────┐    │
│  │ NWS API     │    │ │  │ File Ops    │    │
│  │ weather.gov │    │ │  │ Local FS    │    │
│  └─────────────┘    │ │  └─────────────┘    │
└─────────────────────┘ └─────────────────────┘
           │                     │
           └──────────┬──────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                    📊 Results & Responses                       │
│  "Weather data saved to california_forecast.txt"               │
└─────────────────────────────────────────────────────────────────┘

工作流序列

1. User Query → 2. Gemini Processing → 3. Task Planning → 4. MCP Tool Calls
      ↓              ↓                      ↓                      ↓
   "What's the    "I need to:         "First get weather,     "Call get_alerts('CA')
    weather in     1. Query weather     then save to file"     and write_file(...)"
    California?    2. Save results
    Save it to a   to file"
    file"

数据流示例

User: "Get California weather alerts and save them to alerts.txt"

Gemini AI: Analyzes request → Plans: weather query + file write

MCP Tools Execution:
├── Weather Server: get_alerts("CA") → Returns alert data
└── File Server: write_file("alerts.txt", alert_data) → Saves file

Response: "California weather alerts have been saved to alerts.txt"

🏗️ 项目结构

multimodel-mcp/
├── 🔧 Backend (Python/FastAPI)
│   ├── 🧠 gemini-client.py          # CLI Gemini AI chat interface
│   ├── 🌤️ server.py                 # Weather MCP server (NWS API)
│   ├── 📁 file-system-mcp-server.py # File system MCP server (CRUD ops)
│   ├── 🌐 http_shim.py              # HTTP bridge for web frontend
│   ├── ⚙️ config.json               # MCP server configuration
│   ├── 📋 pyproject.toml            # Python dependencies & config
│   └── 🔒 uv.lock                   # Python dependency lock file
│
├── 🌐 Frontend (Next.js/React)
│   ├── src/app/
│   │   ├── page.tsx                # Home (redirects to chat)
│   │   ├── chat/page.tsx           # Main chat interface
│   │   ├── weather/page.tsx        # Weather dashboard
│   │   ├── files/page.tsx          # File management
│   │   └── api/                    # REST API routes
│   │       ├── chat/route.ts        # Chat endpoint
│   │       ├── weather/             # Weather API routes
│   │       └── fs/                  # File system API routes
│   ├── package.json                # Node.js dependencies
│   ├── tailwind.config.*           # CSS framework config
│   └── tsconfig.json               # TypeScript configuration
│
└── 📚 Configuration & Docs
    ├── 📖 README.md                 # This documentation
    ├── 🔐 .env.example              # Environment variables template
    ├── 🎯 .gitignore                # Git ignore rules
    ├── 🐍 .python-version          # Python version specification
    └── 📄 LICENSE                   # Project license

组件体系结构

🚀 安装

先决条件

• Python 3.11+ 随着 uv包管理器
• Node.js 18+ 随着 npm/纱线
• 谷歌人工智能API密钥 (在这里买一个)

后端设置（Python/FastAPI）

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and enter project
git clone 
cd multimodel-mcp

# Install Python dependencies
uv sync

# Setup environment variables
cp .env.example .env
# Edit .env and add: GOOGLE_API_KEY=your_actual_api_key_here

前端设置（Next.js/React）

# Navigate to frontend directory
cd frontend

# Install Node.js dependencies
npm install
# or
yarn install

🚀 快速开始

选项1：Web界面（推荐）

# Terminal 1: Start the backend HTTP shim
uv run python http_shim.py

# Terminal 2: Start the frontend
cd frontend && npm run dev

# Open http://localhost:3000 in your browser

选项2:CLI界面

# Start the CLI client directly
uv run python gemini-client.py

尝试这些多模式示例

🌤️ Weather Operations:
"What weather alerts are there for California?"
"Get the 5-day forecast for New York City"

📁 File Operations:
"List all files in the current directory"
"Read the README.md file and summarize it"
"Create a new file called notes.txt with meeting notes"

🔄 Combined Operations:
"Check California weather and save the results to weather_report.txt"
"Read all Python files and check for TODO comments"
"Create a weather summary for Seattle and store it in reports/"

可用命令（CLI）

• help -显示可用操作和示例
• clear -清除对话历史记录
• exit 或 quit -结束会话

🌐 web界面

启动Web应用程序

# Terminal 1: Start HTTP shim (backend API)
uv run python http_shim.py

# Terminal 2: Start Next.js frontend
cd frontend && npm run dev

可用页面

聊天页面(/chat)-主界面

• 实时AI聊天 使用Gemini 2.5 Pro
• 消息历史记录 持续的对话
• 加载状态 以及错误处理
• 响应式设计 适用于所有屏幕尺寸

天气页面(/weather)-天气仪表板

• 交互式天气查询 通过REST API
• 实时数据 来自NWS API
• 状态选择 以及基于位置的预测
• 警报监控 预测可视化

文件页面(/files)-文件管理

• 目录浏览 具有安全验证功能
• 文件操作 （读、写、删除）
• 元数据显示 （大小、权限、日期）
• 安全操作 有路径限制

API终点

• GET/POST /api/chat -AI对话界面
• GET/POST /api/weather/alerts -各州天气警报
• GET/POST /api/weather/forecast -基于位置的预测
• GET/POST /api/fs/list -目录列表
• GET/POST /api/fs/read -文件读取
• GET/POST /api/fs/write -文件写入

💻 CLI接口

直接终端接入

# Start interactive CLI session
uv run python gemini-client.py

CLI功能

• 持续会话 有对话记忆
• 后台处理 用于长时间运行的任务
• 详细日志记录 用于调试
• 脚本集成 能力
• 无需网络浏览器

CLI命令

help     - Display available operations and examples
clear    - Reset conversation history
exit     - End the session gracefully
quit     - Same as exit

💡 对话示例

天气和文件操作相结合

You: "What's the weather like in Florida and save today's forecast to a file"

Assistant: I'll check the weather in Florida and save the forecast to a file.

[Gets Florida weather alerts and forecast]
[Creates and writes to florida_weather.txt]

Weather information has been saved to florida_weather.txt

复杂的多步骤任务

You: "Read the project README, understand what this does, then create a summary file"

Assistant: I'll read the README file, analyze the project, and create a summary.

[Reads README.md]
[Analyzes content]
[Creates project_summary.txt with key points]

Project summary has been created in project_summary.txt

🎯 多模式人工智能能力

Gemini AI如何支持多模式交互

系统使用 谷歌Gemini 2.5 Pro 通过集成AI模型 mcp使用 库，提供天气数据和文件系统操作之间的智能编排。Gemini不仅执行命令，它还了解上下文，计划多步操作，并提供自然响应。

🌤️ 天气情报示例

基本天气查询

"Show me weather alerts for California"
"Get the 5-day forecast for New York City"
"What's the weather like in Miami right now?"
"Are there any severe weather warnings in Texas?"

高级天气分析

"Compare weather between San Francisco and Seattle"
"Find the best day for outdoor activities in Denver this week"
"Summarize all active weather alerts across the US"

📁 文件系统操作

文件管理

"Read the contents of README.md"
"Show me all Python files in this directory"
"Create a backup directory and copy all .py files there"
"Find the largest file in the current directory"

内容运营

"Create a new file called 'notes.txt' with today's date and meeting notes"
"Read the project configuration and show me the dependencies"
"Search for all files containing the word 'weather'"
"Generate a summary of all text files in the docs folder"

🔄 跨域工作流

天气+文件操作

"Check California weather and save the results to california_weather.txt"
"Get today's forecast for Seattle and append it to my weather_log.txt"
"Monitor weather alerts and create a daily report file"

数据分析任务

"Read the weather data file, analyze trends, and create a summary report"
"Compare weather patterns from multiple cities and save analysis to file"
"Collect weather data for a week and generate statistical reports"

项目管理

"Review all project files, check for TODOs, and create a task summary"
"Analyze code files, check weather API usage, and document findings"
"Create documentation for the weather and file system APIs"

🧠 AI驱动的功能

自然语言理解

• 情境感知：了解“今天的天气”与“本周的预报”
• 位置智能：识别城市名称、坐标和州代码
• 文件类型识别：知道如何处理不同的文件格式

智能任务规划

• 多步操作：将复杂的请求分解为连续的操作
• 错误恢复：妥善处理API故障和文件权限问题
• 数据验证：确保天气数据的准确性和文件操作安全

记忆与连续性

• 对话历史：记住会话中以前的交互
• 上下文保护：维护相关操作的状态
• 逐步细化：从用户反馈中学习以改进响应

📖 使用指南

🎯 主界面：多模式Gemini聊天

与系统交互的主要方式是通过 Gemini AI聊天客户端，它为天气和文件系统功能提供了一个自然语言界面。

启动聊天界面

uv run python gemini-client.py

交互式命令

• help -显示可用操作和示例
• clear -重置对话历史记录
• exit 或 quit -结束会话

🛠️ 单个MCP服务器

虽然主要界面是多模式聊天，但您也可以为特定用例运行单独的服务器：

气象MCP服务器(server.py)

目的：使用美国国家气象局API的专用天气数据服务器。

可用工具：

• get_alerts(state) -获取美国各州的天气警报
• get_forecast(lat, lon) -获取5天天气预报

# Start weather server
uv run python server.py

# Test with MCP inspector
uv run mcp-inspector python server.py

文件系统MCP服务器(file-system-mcp-server.py)

目的：具有安全控制的专用文件系统操作服务器。

可用工具：

• read_file(path) -读取文本文件内容
• write_file(path, content) -将内容写入文件
• list_directory(path) -列出目录内容
• create_directory(path) -创建新目录
• delete_file(path) -安全删除文件
• get_file_info(path) -获取详细的文件元数据

# Start file system server
uv run python file-system-mcp-server.py

# Test with MCP inspector
uv run mcp-inspector python file-system-mcp-server.py

🔧 配置(config.json)

系统使用JSON配置文件来编排多个MCP服务器：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "E:\\MCP\\multimodel-mcp\\server.py"]
    },
    "filesystem": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "E:\\MCP\\multimodel-mcp\\file-system-mcp-server.py"]
    }
  }
}

此配置使Gemini AI代理能够通过mcp使用库同时访问两台服务器。

🔌 集成示例

游标IDE集成

添加到光标MCP配置中：

{
  "mcpServers": {
    "multimodal": {
      "command": "uv",
      "args": ["run", "--project", "E:\\MCP\\multimodel-mcp", "python", "gemini-client.py"],
      "cwd": "E:\\MCP\\multimodel-mcp"
    }
  }
}

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "multimodal": {
      "command": "uv",
      "args": ["run", "python", "gemini-client.py"],
      "cwd": "path/to/multimodel-mcp"
    }
  }
}

使用SSE传输运行（默认）

cd mcpserver
uv run python server.py
# Server starts on http://localhost:8001

使用Stdio Transport运行

# Edit server.py line 100:
transport = "stdio"  # Change from "sse"

# Then run:
uv run python server.py

可用工具

• get_alerts(state: str)：天气警报（与基本服务器相同）
• get_forecast(latitude: float, longitude: float)：5天天气预报

示例用法

# Weather alerts
get_alerts("FL")

# Location forecast (Miami, FL coordinates)
get_forecast(25.7617, -80.1918)

🔌 集成示例

游标IDE集成

1. 查找MCP配置:

- 窗户： %APPDATA%\Cursor\User\globalStorage\cursor.mcp.json - macOS： ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp.json - Linux： ~/.config/Cursor/User/globalStorage/cursor.mcp.json

1. 添加天气服务器配置:

   {
     "mcpServers": {
       "weather": {
         "command": "uv",
         "args": ["run", "python", "server/weather.py"],
         "cwd": "E:\\MCP\\weather-retriever-mcp"
       }
     }
   }

1. 重新启动游标 并使用代理模式：

   "Get weather alerts for California"
   "What are the current warnings in Texas?"
   "Are there any active alerts in Florida?"

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "--project", "E:\\MCP\\weather-retriever-mcp", "python", "server/weather.py"]
    }
  }
}

其他MCP客户端

服务器通过将其配置为运行以下命令与任何MCP兼容的客户端一起工作：

uv run python server/weather.py

🧪 开发与测试

运行测试

1.测试标准运输

cd mcpserver
uv run python client-stdio.py

2.测试SSE传输

# Terminal 1: Start server
cd mcpserver
uv run python server.py

# Terminal 2: Run client
cd mcpserver
uv run python client-sse.py

3.测试MCP检查员

uv run mcp-inspector python server/weather.py

开发工作流程

添加新的天气工具

1. 编辑 server/weather.py 或 mcpserver/server.py
2. 添加新的 @mcp.tool() 装饰功能
3. 与MCP检查员一起测试
4. 如果需要，更新客户端配置

修改AI客户端

1. 编辑 server/client.py
2. 更改LLM模型或参数
3. 更新环境变量
4. 测试交互功能

🔧 api参考

REST API端点（Web界面）

聊天API

POST /api/chat

目的：向Gemini AI发送消息以进行多模式处理 请求:

{
  "message": "What weather alerts are there for California?",
  "history": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
  ]
}

回应:

{"reply": "There are currently no active weather alerts for California..."}

天气API

GET/POST /api/weather/alerts
POST /api/weather/forecast

天气警报:

{
  "state": "CA",
  "alerts": [
    {
      "event": "Special Weather Statement",
      "area": "Mountain Areas",
      "severity": "Minor",
      "description": "Gusty winds expected..."
    }
  ]
}

天气预报:

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "forecast": [
    {
      "period": "Today",
      "temperature": "68°F",
      "wind": "5 mph W",
      "conditions": "Sunny"
    }
  ]
}

文件系统API

GET/POST /api/fs/list
GET/POST /api/fs/read
POST /api/fs/write

目录列表:

{
  "path": ".",
  "contents": [
    {"name": "README.md", "type": "file", "size": 2048},
    {"name": "src", "type": "directory", "size": 0}
  ]
}

文件读/写:

{
  "path": "notes.txt",
  "content": "Meeting notes content...",
  "success": true
}

MCP工具参考

气象MCP服务器工具

• get_alerts(state: str) -获取美国各州的活跃天气警报
• get_forecast(latitude: float, longitude: float) -获取5天天气预报

文件系统MCP服务器工具

• read_file(file_path: str) -读取文本文件内容
• write_file(file_path: str, content: str, create_dirs: bool) -将内容写入文件
• list_directory(dir_path: str, show_hidden: bool) -列出目录内容
• create_directory(dir_path: str, create_parents: bool) -创建目录
• delete_file(file_path: str) -安全删除文件
• get_file_info(file_path: str) -获取详细的文件元数据

配置文件

MCP服务器配置(config.json)

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "server.py"]
    },
    "filesystem": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "file-system-mcp-server.py"]
    }
  }
}

环境变量(.env)

GOOGLE_API_KEY=your_actual_google_ai_api_key_here

🛠️ 发展

开发设置

后端开发

# Install Python dependencies
uv sync

# Run individual MCP servers for testing
uv run python server.py                    # Weather server (port 8001)
uv run python file-system-mcp-server.py    # File server (port 8002)

# Run HTTP shim for web integration
uv run python http_shim.py                 # API bridge (port 8003)

# Test CLI client
uv run python gemini-client.py

前端开发

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev                                # Next.js dev server (port 3000)

# Build for production
npm run build
npm start                                  # Production server

项目结构详图

后端组件

• server.py：与NWS API集成的FastMCP天气服务器
• file-system-mcp-server.py：通过路径验证保护文件操作
• http_shim.py：连接MCP服务器和web前端的FastAPI桥
• gemini-client.py：使用mcp use库的CLI界面
• config.json：MCP服务器编排配置

前端组件

• frontend/：完成Next.js 16+React 19应用程序
• API路线：连接到HTTP填充程序的REST端点
• 页面：聊天、天气仪表板和文件管理界面
• 组件：使用TypeScript的可重用UI组件

添加新功能

新天气特征

# In server.py, add new MCP tool
@mcp.tool()
async def get_weather_history(state: str, days: int) -> str:
    """Get historical weather data."""
    # Implementation here
    pass

新建文件操作

# In file-system-mcp-server.py
@mcp.tool()
async def search_files(directory: str, pattern: str) -> str:
    """Search for files matching a pattern."""
    # Implementation here
    pass

新建网页

// In frontend/src/app/new-feature/page.tsx
export default function NewFeaturePage() {
  // Implementation here
}

测试

后端测试

# Test MCP servers individually
uv run mcp-inspector python server.py
uv run mcp-inspector python file-system-mcp-server.py

# Test HTTP shim API
curl http://localhost:8003/docs  # FastAPI docs

前端测试

cd frontend
npm run lint    # ESLint checking
npm run build   # Build verification

🐛 故障排除

常见问题及解决方案

❌ “API密钥无效”错误

问题：Gemini AI身份验证失败 解决方案:

# Get API key from https://makersuite.google.com/app/apikey
# Update .env file:
GOOGLE_API_KEY=your_actual_api_key_here

❌ “连接被拒绝”/“服务器未运行”

问题：后端服务不可访问 解决方案:

# Start required services:
uv run python http_shim.py          # For web interface
# OR
uv run python gemini-client.py      # For CLI interface

❌ “找不到模块”错误

问题：缺少Python依赖项 解决方案:

uv sync  # Install/update all Python dependencies

❌ 前端构建错误

问题：Node.js依赖或TypeScript问题 解决方案:

cd frontend
rm -rf node_modules package-lock.json
npm install  # Fresh installation

❌ 文件权限错误

问题：文件系统操作被阻止 解决方案：服务器自动限制对以下内容的访问：

• 系统目录(/etc, /usr, C:\Windows)
• 敏感路径和受保护的文件
• 在项目目录中使用相对路径

❌ 天气API错误

问题：NWS API连接问题 解决方案:

• 验证互联网连接
• 检查有效的州代码（CA、NY、TX、FL等）
• NWS API可能会出现暂时中断

🔍 调试命令

# Backend diagnostics
uv run python -c "import server; print('Weather server: OK')"
uv run python -c "import http_shim; print('HTTP shim: OK')"
uv run python -c "from mcp_use import MCPClient; print('MCP client: OK')"

# Frontend diagnostics
cd frontend && npm run lint  # Check for errors
cd frontend && npm run build  # Test build process

# Network diagnostics
netstat -an | findstr "3000\|8001\|8002\|8003"  # Check port availability
curl http://localhost:8003/health  # Test HTTP shim

📊 性能和限制

• API双子星：免费等级~50个请求/分钟，付费等级更高
• 天气API：实时NWS数据，偶尔出现延迟
• 文件操作：本地文件系统，即时响应
• 内存使用：每个运行的服务约100-200MB
• 并发用户：Web界面支持多个会话

🤝 贡献

入门指南

git clone 
cd multimodel-mcp

# Backend setup
uv sync
cp .env.example .env  # Add your GOOGLE_API_KEY

# Frontend setup
cd frontend && npm install

开发工作流程

后端捐款

1. MCP服务器扩展：向添加新工具 server.py 或 file-system-mcp-server.py
2. API增强功能：扩展 http_shim.py 具有新端点
3. CLI改进：增强 gemini-client.py 特征

前端贡献

1. UI组件：在中添加新页面 frontend/src/app/
2. API集成：为后端功能创建新的API路由
3. 用户体验改进：增强用户体验和响应能力

示例：添加新的天气特征

# In server.py
@mcp.tool()
async def get_weather_trends(state: str, days: int = 7) -> str:
    """Analyze weather trends for the past N days."""
    # Implementation here
    return f"Weather trends for {state} over {days} days..."

示例：添加新文件操作

# In file-system-mcp-server.py
@mcp.tool()
async def find_files_by_content(directory: str, search_text: str) -> str:
    """Find files containing specific text."""
    # Implementation with security validation
    return f"Files containing '{search_text}' in {directory}..."

测试您的更改

后端测试

# Test MCP servers
uv run mcp-inspector python server.py
uv run mcp-inspector python file-system-mcp-server.py

# Test HTTP shim
uv run python http_shim.py
curl http://localhost:8003/docs

前端测试

cd frontend
npm run lint
npm run build
npm run dev

代码指南

Python（后端）

• 类型提示：使用完整类型注释
• 文档字符串：全面的功能文档
• 错误处理：适当的异常管理
• 安全：输入验证和路径安全
• 异步/等待：对I/O操作使用异步模式

TypeScript（前端）

• 类型安全：严格的TypeScript使用
• 部件结构：可重复使用、结构良好的组件
• 误差边界：React中正确的错误处理
• API集成：一致的API调用模式
• 样式：顺风CSS最佳实践

提交变化

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

贡献领域

• 🌤️ 天气特征：历史数据、天气图、恶劣天气跟踪
• 📁 文件操作：搜索、压缩、批处理操作、文件分析
• 🤖 AI增强功能：自定义提示、专门的工作流程、多语言支持
• 🎨 UI/UX：更好的界面、移动响应、可访问性
• 📊 分析：使用情况跟踪、性能监控、错误报告
• 🔒 安全：加强验证、审计记录、许可系统

📄 许可证

MIT许可证 -请参阅 许可证 文件以获取完整详细信息。

该项目是开源的，在MIT许可证下可用，允许自由使用、修改和分发，并具有适当的归属。

🙏 致谢

核心技术

• 谷歌人工智能 -Gemini 2.5 Pro多模式语言模型
• 国家气象局 -官方weather.gov API
• 模型上下文协议 -行业标准AI工具集成
• FastMCP -轻量级MCP服务器框架
• mcp使用 -Python MCP客户端库

Web技术

• Next.js 16 -带有App Router的React框架
• 反应19 -UI组件库
• TypeScript -类型安全的JavaScript
• 顺风CSS -实用程序优先的CSS框架
• 快速API -现代Python web框架

开发工具

• 紫外线 -快速Python包管理器
• 埃斯林特 -JavaScript/TypeScript linting
• 更漂亮 -代码格式

______________________________________________________________________

内置于❤️ 实现无缝的人机协作

______________________________________________________________________

⭐ 如果你觉得这个仓库有用，就把它标上！