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：安装 （包括一切） - 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)
______________________________________________________________________
用法
- 跑
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架构、工具规范 |
| 在Ubuntu/Debian上安装Docker CE | |
| Metno 代理 | Nginx代理配置 |
| 可观测性 | 度量、日志记录、调试 |
| ETL管道 | 正在重新生成places.db（仅限开发人员） |
| 历史 | 实施历史 |
| 路线图 | 未来计划 |
看 docs/README.md 查看完整的文档索引。
______________________________________________________________________
许可证
VæR是根据MIT许可证授权的开源软件。然而，作者恭敬地要求不要将其用于军事、战争或监视应用。