使用说明

VæR-模型上下文协议天气+地点服务器

一 有主见的模型上下文协议（MCP）服务器 它提供高级、LLM友好的天气工具，由 MET挪威天气API(api.met.no)，通过内部 metno-proxy （Nginx反向代理+缓存）。

该服务器旨在供MCP兼容客户端（如AI助手、IDE、自定义应用程序）使用，以获取结构化的天气信息和简单的“天气服务”，如活动规划和海上旅行风险评估。

MCP客户端使用示例

入门指南

# Clone the repository
git clone git@github.com:bitjungle/vaer.git
# git clone https://github.com/bitjungle/vaer.git
cd vaer

# Start the stack (requires Docker)
make compose-build && make up

# Verify it's running
curl http://localhost:8080/healthz   # → ok
curl http://localhost:3000/health    # → {"status":"ok","transport":"http"}

就是这样——你现在有一个正在运行的MCP服务器。看文档接下来的步骤。

特性

观点化的天气工具
- weather_get_location_forecast –标准化小时预测
- weather_get_nowcast –短期降水和条件
- weather_get_air_quality –挪威各地的空气质量和空气质量指数
- weather_get_recent_observations –最近观测到的天气（霜冻）
- weather_get_marine_conditions –沿海/海洋概述
- weather_assess_outdoor_activity_window “外面什么时候好？”
- weather_assess_marine_trip_risk –简单的海洋风险评估
挪威地名解析 （28115个名额）
- places_resolve_name –将挪威地名解析为坐标
- 由Kartverket Stedsnavn（挪威官方地名注册）提供技术支持
- 支持“卑尔根的天气怎么样？”
- 通过FTS5全文搜索、置信度评分和消歧进行智能匹配
- 本地SQLite数据库（6.09 MB），约5ms查询延迟
MCP本地
- 暴露工具, 资源，以及提示使用MCP规范。
- 支持标准和 超文本传输协议 运输。
支持 metno-proxy
- 使用现有的Nginx代理：
  - 适当的 User-Agent 处理（MET挪威要求）
  - 缓存和速率限制
  - 健康检查
结构化、一致的输出
- 标准化单位（°C、m/s、mm/h等）
- 结构化的类似JSON的响应+简短的文本摘要
- 包括有关数据源、许可和缓存新鲜度的元数据
归因与合规
- MET挪威许可证和信贷额度的内置资源。
- 旨在遵守MET使用指南。

建筑

高层架构：

MCP Client (ChatGPT, IDE, custom app)
        │  (MCP / JSON-RPC)
        ▼
   Vær Server
        ├─ Weather Domain (MET-backed)
        │    │  (HTTP, internal)
        │    ▼
        │  metno-proxy (Nginx: cache, UA, rate limit)
        │    │  (HTTPS)
        │    ▼
        │  api.met.no (MET Norway Weather API)
        │
        └─ Places Domain (Norway gazetteer)
             │  (local SQLite query)
             ▼
           data/places.db (Stedsnavn-derived)

MCP服务器 从不打电话 api.met.no 直接.
所有上游交通都经过 metno-proxy.
地名解析使用 本地SQLite数据库 （无网络呼叫）。

需求

运行时
- Node.js 24+（LTS或更新版本）
MET代理
- 跑步 metno-proxy 集装箱或服务：
  - 代理 /weatherapi/... 到 https://api.met.no/...
  - 设置合规 User-Agent
  - 可选择启用缓存和速率限制
Docker+Compose v2 （适用于Docker部署）
- macOS/Windows：安装 Docker 桌面版（包括一切）
- Linux服务器：从Docker的官方仓库安装Docker CE——请参阅 docs/docker-linux.md
地点数据库 （含）
- data/places.db （28115个挪威位置，6.09 MB）包含在存储库中
- 无需设置-使用后即可开箱即用 git clone
- 开发人员可以从源代码重新生成--请参阅 docs/etl-pipeline.md
MCP客户端
- 通过stdio或HTTP支持MCP服务器的任何客户端。

配置

MCP服务器通过环境变量配置：

必需

METNO_PROXY_BASE_URL Nginx代理的基本URL（例如。 http://localhost:8080 对于dev来说， http://metno-proxy:80 Docker）。

代理和超时

METNO_TIMEOUT_MS --上游HTTP超时（默认值： 5000ms）
METNO_CONNECT_TIMEOUT_MS --连接超时（默认值： 2000ms）

霜冻API（观测结果）

FROST_CLIENT_ID -Frost API的客户端ID（从https://frost.met.no/auth/requestCredentials.html)
FROST_BASE_URL -覆盖Frost API基础URL（默认值： https://frost.met.no)
FROST_TIMEOUT_MS -Frost API超时（默认值： 10000ms）

服务器

VAER_PORT --HTTP传输端口。如果未设置，服务器将使用stdio传输。
VAER_LOG_LEVEL --日志记录级别： debug, info, warn, error （默认值： info)

认证

VAER_AUTH_MODE --身份验证模式： none, api-key, jwt （默认值： none)
VAER_API_KEY -API密钥值（如果 VAER_AUTH_MODE=api-key)

地点数据库

PLACES_DB_PATH --SQLite放置数据库的路径（默认： ./data/places.db)

用法

跑 metno-proxy 启动基于Nginx的代理 api.met.no.
运行Be服务器 启动MCP服务器进程（通过 node, npm, pnpm，或Docker），指向 METNO_PROXY_BASE_URL.
从MCP客户端连接 配置您的MCP兼容客户端以连接到此服务器：
- 通过标准（本地）
- 或通过 超文本传输协议 （远程），使用配置的端口和可选的API密钥。
从客户端调用工具 客户端现在可以调用7个已实现的工具中的任何一个：

数据工具：
- weather_get_location_forecast –全球天气预报
- weather_get_nowcast –北欧2小时降水
- weather_get_air_quality –挪威空气质量和空气质量指数
- weather_get_marine_conditions –沿海海洋天气
- weather_get_recent_observations –观测天气（霜冻API）
维修工具：
- weather_assess_outdoor_activity_window –活动计划与舒适度评分
- weather_assess_marine_trip_risk –海上旅行风险评估
放置工具：
- places_resolve_name –将挪威地名解析为坐标

仓库布局

.
├─ src/                       # TypeScript source code
│  ├─ index.ts               # MCP server entry point
│  ├─ tools/                 # 8 MCP tools (weather_* + places_*)
│  ├─ resources/             # MCP resources
│  ├─ prompts/               # MCP prompts
│  ├─ domain/                # Shared utilities
│  └─ places/                # Places module
├─ data/
│  └─ places.db              # Norwegian places database (included)
├─ docs/                      # Documentation
│  ├─ getting-started.md     # Deployment guide
│  ├─ development.md         # Developer setup
│  ├─ design.md              # Architecture & API specs
│  └─ ...                    # See docs/README.md
├─ metno-proxy/               # Nginx reverse proxy
├─ scripts/etl/               # Places ETL (developer-only)
├─ tests/                     # Test suites
├─ docker-compose.yml         # Full stack orchestration
└─ Makefile                   # Build commands

快速启动（开发）

先决条件

Node.js 24+LTS
Docker桌面（macOS/Windows）或Docker+Compose v2（Linux——请参阅需求)

运行全栈

# Build and start all services
make compose-build
make up

# Verify services are running
docker compose ps

# Test endpoints
curl http://localhost:8080/healthz
curl http://localhost:3000/health

这两项服务都应该显示为“健康”：

metno 代理: http://localhost:8080 （nginx代理到api.meet.no）
瓦埃尔: http://localhost:3000 （带HTTP传输的MCP服务器）

有关详细的设置说明，请参阅 docs/development.md.

测试

# Run all tests
npm test

# Unit tests only
npm run test:unit

# Integration tests (requires metno-proxy running)
METNO_PROXY_BASE_URL=http://localhost:8080 npm run test:integration

# Test with MCP Inspector
npm run build
METNO_PROXY_BASE_URL=http://localhost:8080 npx @modelcontextprotocol/inspector node dist/index.js

有关详细的测试说明，请参阅 docs/development.md.

部署

Vær服务器可以通过多种方式部署：

Docker Compose（推荐）

使用单个命令部署整个堆栈（metno proxy+vaer）：

# 1. Build and start all services
make compose-build
make up

# 2. Verify deployment
docker compose ps
curl http://localhost:8080/healthz

# 3. View logs
make compose-logs

# 4. Stop services
make down

环境配置：

创建一个 .env 项目根目录中的文件：

# Required: Your User-Agent for MET Norway API
METNO_USER_AGENT=my-service/1.0 contact@example.com

# Optional: Frost API credentials for observations
FROST_CLIENT_ID=your-frost-client-id

# Optional: Logging level
VAER_LOG_LEVEL=info

独立Docker

直接构建并运行MCP服务器映像：

# Build image
docker build -t vaer:latest .

# Run with environment variables
docker run -d \
  --name vaer \
  -e METNO_PROXY_BASE_URL=http://metno-proxy:80 \
  -e VAER_LOG_LEVEL=info \
  vaer:latest

注： places.db数据库在构建过程中被烘焙到映像中。不要安装 ./data 作为一个卷，它会导致权限问题。

MCP客户端配置

将MCP客户端（Claude Desktop、VS Code等）连接到服务器：

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vaer": {
      "command": "node",
      "args": ["/path/to/vaer/dist/index.js"],
      "env": {
        "METNO_PROXY_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

基于Docker的设置：

{
  "mcpServers": {
    "vaer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "vaer_vaer-network",
        "-e", "METNO_PROXY_BASE_URL=http://metno-proxy:80",
        "vaer:latest"
      ]
    }
  }
}

看 examples/client-configs/ 更多配置示例。

生产部署

有关生产部署，请参阅 docs/getting-started.md:

Docker编写生产配置
Kubernetes清单
安全注意事项
监控和操作

文档

指南	说明
入门指南	生产部署指南
发展	本地设置、测试、贡献
设计	架构、API架构、工具规范
Linux上的Docker	在Ubuntu/Debian上安装Docker CE
Metno 代理	Nginx代理配置
可观测性	度量、日志记录、调试
ETL管道	正在重新生成places.db（仅限开发人员）
历史	实施历史
路线图	未来计划

看 docs/README.md 查看完整的文档索引。

许可证

VæR是根据MIT许可证授权的开源软件。然而，作者恭敬地要求不要将其用于军事、战争或监视应用。

使用说明

VæR-模型上下文协议天气+地点服务器

MCP客户端使用示例

入门指南

特性

建筑

需求

配置

必需

代理和超时

霜冻API（观测结果）

服务器

认证

地点数据库

用法

仓库布局

快速启动（开发）

先决条件

运行全栈

测试

部署

Docker Compose（推荐）

独立Docker

MCP客户端配置

生产部署

文档

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器