vaer (Bitjungle)

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

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

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

______________________________________________________________________

MCP客户端使用示例

Vær in Claude Desktop

______________________________________________________________________

入门指南

# 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：安装 （包括一切） - Linux服务器：从Docker的官方仓库安装Docker CE——请参阅

• 地点数据库 （含）

- 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)

______________________________________________________________________

用法

1. 跑 metno-proxy

启动基于Nginx的代理 api.met.no.

1. 运行Be服务器

启动MCP服务器进程（通过 node, npm, pnpm，或Docker），指向 METNO_PROXY_BASE_URL.

1. 从MCP客户端连接

配置您的MCP兼容客户端以连接到此服务器：

- 通过 标准 （本地） - 或通过 超文本传输协议 （远程），使用配置的端口和可选的API密钥。

1. 从客户端调用工具

客户端现在可以调用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清单
• 安全注意事项
• 监控和操作

______________________________________________________________________

文档

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

______________________________________________________________________

许可证

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