Strands定位服务天气

![CI](https://github.com/CarmenAPuccio/strands-location-service-weather/actions) ![Python 3.10+](https://www.python.org/downloads/) ![Code style: black](https://github.com/psf/black) ![Ruff](https://github.com/astral-sh/ruff)

该项目将亚马逊定位服务MCP服务器与天气数据相结合，使用亚马逊基岩进行自然语言处理，提供基于位置的天气信息。

特性

定位服务：使用亚马逊定位服务搜索地点、获取坐标、计算路线
天气数据：国家气象局的当前天气状况和警报
自然语言处理：由亚马逊基岩（克劳德3十四行诗）提供技术支持
MCP服务器：与使用FastMCP的Amazon Q CLI和其他MCP客户端兼容
高性能：优化HTTP会话重用和简化处理（约18秒响应时间）
可观测性：与跟踪、日志记录和指标完全集成的OpenTetry
错误处理：稳健的错误处理，优雅的降级
OpenAPI模式生成：基岩Agent动作组OpenAPI 3.0模式的自动生成

建筑

该应用程序使用具有多种部署模式的统一架构：

本地模式：直接执行Python进行开发和测试
MCP服务器模式：FastMCP服务器与Amazon Q CLI兼容
基岩介质模式：AWS Lambda功能与Bedrock Agent集成

关键组件

MCP（模型上下文协议）工具提供亚马逊位置服务集成
自定义气象工具从美国国家气象局API获取数据
共享依赖关系和代码的Lambda层（基岩代理模式）
单个LocationWeatherClient类处理所有基岩交互
OpenTetry在所有模式下提供全面的可观察性

部署模式

基岩药剂部署

对于使用Bedrock Agent的生产AWS部署：

# Build Lambda layers and functions
uv run python infrastructure/build_lambda_layers.py

# Deploy AWS infrastructure
cd infrastructure && cdk deploy

这将创建：

Lambda函数具有适当的依赖层
带护栏的基岩剂
CloudWatch日志记录和监控
具有最低权限访问的IAM角色

地方发展

# Run locally
uv run location-weather

# Run as MCP server
uv run location-weather-mcp

开放遥测可观测性

该应用程序通过OpenTetry集成提供全面的可观察性：

跟踪结构

每个用户交互都会创建一个具有以下跨度的分层跟踪：

用户交互：整个请求的顶层跨度

- 代理交互：代理处理和响应生成 - 基岩模型推理：使用令牌使用指标进行LLM推理 - get_weather_api：天气数据检索 - 获取rid_points：NWS网格点查找 - 获取预测：天气预报检索 - 获取_餐厅_警报：天气警报检查 - get_zone_info：区域信息查找 - 获取警报数据：主动警报检索

捕获的指标

令牌使用情况：输入令牌、输出令牌、总令牌
执行时间：总持续时间和周期计数
工具使用：使用的工具和工具数量
HTTP请求：状态代码、URL、响应时间
天气数据：温度、预报条件、警报计数

开发模式

与一起跑步 DEVELOPMENT=true 查看详细的跟踪输出，包括：

JSON格式的跨度，带有跟踪ID和时间
HTTP请求/响应详细信息
模型推理度量
工具执行流程

例子

问自然语言问题，比如：

“西雅图的天气怎么样？”
“查找波士顿现在开放的咖啡店”
“从特伦顿到费城的路线”
47.6062、-122.3321附近的地方
“新泽西州特伦顿的天气怎么样，有什么警报吗？”
“费城是什么样子的？”

项目结构

该项目遵循Python打包最佳实践 src/ 布局：

├── src/
│   └── strands_location_service_weather/
│       ├── __init__.py
│       ├── main.py               # CLI entry point with OpenTelemetry setup
│       └── location_weather.py   # Core module with unified client and tools
├── pyproject.toml                # Modern Python project configuration
└── .kiro/steering/               # AI assistant guidance documents

安装和设置

# Install dependencies
uv sync

# Install with development tools (Black, Ruff, pytest, coverage)
uv sync --extra dev

AWS权限设置

此应用程序需要特定的AWS权限才能访问Amazon Bedrock和Amazon位置服务。标准的AWS管理策略是不够的，因此需要自定义策略。

所需自定义策略

1.亚马逊位置服务访问

AWS不为位置服务提供托管只读策略，因此创建此自定义策略：

政策名称: AmazonLocationServiceReadOnlyAccess

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "geo:DescribeGeofenceCollection",
        "geo:DescribeMap",
        "geo:DescribePlaceIndex",
        "geo:DescribeRouteCalculator",
        "geo:DescribeTracker",
        "geo:GetDevicePosition",
        "geo:GetDevicePositionHistory",
        "geo:GetGeofence",
        "geo:GetMapGlyphs",
        "geo:GetMapSprites",
        "geo:GetMapStyleDescriptor",
        "geo:GetMapTile",
        "geo:ListDevicePositions",
        "geo:ListGeofenceCollections",
        "geo:ListGeofences",
        "geo:ListMaps",
        "geo:ListPlaceIndexes",
        "geo:ListRouteCalculators",
        "geo:ListTagsForResource",
        "geo:ListTrackerConsumers",
        "geo:ListTrackers",
        "geo:SearchPlaceIndexForPosition",
        "geo:SearchPlaceIndexForSuggestions",
        "geo:SearchPlaceIndexForText",
        "geo:CalculateRoute",
        "geo:CalculateRouteMatrix",
        "geo-maps:GetStaticMap",
        "geo-maps:GetTile",
        "geo-places:GetPlace",
        "geo-places:SearchNearby",
        "geo-places:SearchText",
        "geo-places:Suggest",
        "geo-places:ReverseGeocode",
        "geo-places:Geocode",
        "geo-routes:CalculateIsolines",
        "geo-routes:CalculateRoutes",
        "geo-routes:CalculateRouteMatrix"
      ],
      "Resource": "*"
    }
  ]
}

2.亚马逊基岩调用访问

管理 AmazonBedrockReadOnly 策略缺少模型调用权限。创建此自定义策略：

政策名称: AmazonBedrockInvokeAccess

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetFoundationModel",
        "bedrock:ListFoundationModels",
        "bedrock:GetModelInvocationLoggingConfiguration",
        "bedrock:GetProvisionedModelThroughput",
        "bedrock:ListProvisionedModelThroughputs",
        "bedrock:GetModelCustomizationJob",
        "bedrock:ListModelCustomizationJobs",
        "bedrock:ListCustomModels",
        "bedrock:GetCustomModel",
        "bedrock:ListTagsForResource",
        "bedrock:GetFoundationModelAvailability"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BedrockInvokeAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    }
  ]
}

重要提示

亚马逊定位服务：不存在AWS托管的只读策略，因此需要上述自定义策略
亚马逊基岩：The AmazonBedrockReadOnly 托管策略不包括实际模型使用所需的调用权限
这两个策略都遵循最小特权原则，同时为典型的应用程序使用提供必要的权限
位置服务策略包括所有主要操作：地理编码、反向地理编码、地图、路线和地点搜索

配置

应用程序可以通过环境变量或可选的配置文件进行配置。

环境变量

创建一个 .env 如果需要，请提供本地开发文件：

# Create .env file with your overrides
echo "DEVELOPMENT=true" > .env

关键环境变量：

DEVELOPMENT=true -启用详细日志记录和跟踪
BEDROCK_MODEL_ID -要使用的Claude模型
AWS_REGION -基岩AWS区域
WEATHER_API_TIMEOUT -请求超时（秒）（默认值：10）
FASTMCP_LOG_LEVEL -FastMCP日志记录级别（默认值：ERROR）

多模式部署配置

该应用程序支持不同用例的多种部署模式：

DEPLOYMENT_MODE -部署模式： local, mcp，或 bedrock_agent （默认值： local)
BEDROCK_AGENT_ID -AWS基岩代理ID（需要 bedrock_agent 模式）
BEDROCK_AGENT_ALIAS_ID -基岩代理别名ID（默认值： TSTALIASID)
BEDROCK_AGENT_SESSION_ID -用于会话连续性的基岩代理会话ID（可选）
BEDROCK_AGENT_ENABLE_TRACE -启用基岩代理跟踪（默认： true)
DEPLOYMENT_TIMEOUT -部署特定超时（秒）（默认值：30）
GUARDRAIL_ID -用于内容过滤的基岩护栏ID（可选）
GUARDRAIL_VERSION -护栏版本（默认： DRAFT)
GUARDRAIL_CONTENT_FILTERING -启用内容筛选（默认值： true)
GUARDRAIL_PII_DETECTION -启用PII检测（默认值： true)
GUARDRAIL_TOXICITY_DETECTION -启用毒性检测（默认值： true)

配置文件

该项目包括 config.toml 有合理的违约。要自定义而不修改跟踪的文件，请执行以下操作：

选项1：本地覆盖文件

# Create local overrides (not tracked in git)
cp config.toml config.local.toml
# Edit config.local.toml with your changes

选项2：环境变量 环境变量优先于所有配置文件。

配置优先级（从高到低）：

环境变量
config.local.toml （本地覆盖）
config.toml （项目默认值）

部署模式

该应用程序支持三种部署模式，以适应不同的用例：

📋 用于AWS CDK基础架构部署：参见 CDK部署说明有关部署Bedrock Agent基础设施的详细说明。

本地模式（默认）

用例：本地开发和测试
模型：直接调用API的Amazon Bedrock
工具：完整的MCP工具+自定义天气工具
配置：标准基岩模型配置

# Run in local mode (default)
DEPLOYMENT_MODE=local uv run location-weather

# Or simply (defaults to local mode)
uv run location-weather

MCP模式

用例：与MCP兼容客户端（如Amazon Q CLI）集成
模型：带有MCP服务器接口的Amazon Bedrock
工具：完整的MCP工具+自定义天气工具（共10个）
配置：与本地模式相同，但针对MCP客户端进行了优化

# Run in MCP mode
DEPLOYMENT_MODE=mcp uv run location-weather-mcp

# Or simply (MCP server mode)
uv run location-weather-mcp

卧室_智能模式

用例：AWS Bedrock Agent与预配置代理的集成
模型：带有代理运行时调用的AWS Bedrock代理
工具：基于Lambda的天气和位置工具（共3个）
配置：需要基岩代理ID、别名和可选会话ID
建筑：在基岩代理中配置为行动组的定位服务

# Run in Bedrock Agent mode (example with deployed agent)
DEPLOYMENT_MODE=bedrock_agent \
BEDROCK_AGENT_ID=YOUR_AGENT_ID \
uv run location-weather

# With optional configuration
DEPLOYMENT_MODE=bedrock_agent \
BEDROCK_AGENT_ID=YOUR_AGENT_ID \
BEDROCK_AGENT_ALIAS_ID=TSTALIASID \
BEDROCK_AGENT_SESSION_ID=unique-session-id \
uv run location-weather

基岩药剂设置要求：

具有位置服务操作组的预配置基岩代理
基岩代理调用的适当IAM权限
为Amazon位置服务API配置的操作组
用于内容过滤的可选护栏

有关Lambda函数部署的详细说明，请参阅基础架构/README.md.

模式特定配置

每种模式都可以通过编程进行配置：

from strands_location_service_weather import LocationWeatherClient, DeploymentMode

# Local mode (default)
client = LocationWeatherClient(deployment_mode=DeploymentMode.LOCAL)

# MCP mode
client = LocationWeatherClient(deployment_mode=DeploymentMode.MCP)

# Bedrock Agent mode with configuration
client = LocationWeatherClient(
    deployment_mode=DeploymentMode.BEDROCK_AGENT,
    config_override={
        "bedrock_agent_id": "your-agent-id",
        "aws_region": "us-east-1"
    }
)

# Get deployment information
info = client.get_deployment_info()
print(f"Mode: {info.mode}, Model: {info.model_type}, Tools: {info.tools_count}")

# Health check
health = client.health_check()
print(f"Healthy: {health.healthy}, Model OK: {health.model_healthy}")

OpenAPI模式生成

该应用程序包括为AWS Bedrock Agent动作组生成全面的OpenAPI 3.0模式。这允许从Python工具函数自动创建动作组定义。

特性

自动模式生成：将Python函数转换为OpenAPI 3.0模式
类型推断：支持所有Python类型，包括Optional、List、Dict、Union
基岩药剂合规性：验证AWS Bedrock Agent兼容性的模式
CLI工具：用于生成和验证的完整命令行界面
全面验证：25+验证规则，包含详细的错误报告

生成的模式

系统为两个动作组生成模式：

气象服务: get_weather, get_alerts, current_time 运营
定位服务: search_places, calculate_route 运营

CLI使用情况

# Generate all schemas and export to files
uv run python -m src.strands_location_service_weather.schema_cli generate --output-dir infrastructure/schemas

# Validate all generated schemas
uv run python -m src.strands_location_service_weather.schema_cli validate --verbose

# Show a specific schema
uv run python -m src.strands_location_service_weather.schema_cli show weather_services

# Generate validation report
uv run python -m src.strands_location_service_weather.schema_cli report --output validation_report.md

# List all available schemas
uv run python -m src.strands_location_service_weather.schema_cli list

# Validate a specific schema file
uv run python -m src.strands_location_service_weather.schema_cli validate-file ./schemas/weather_action_group.json

程序化使用

from src.strands_location_service_weather.openapi_schemas import (
    create_weather_action_group_schema,
    create_location_action_group_schema,
    get_all_action_group_schemas
)
from src.strands_location_service_weather.schema_validation import validate_all_schemas

# Generate schemas
weather_schema = create_weather_action_group_schema()
location_schema = create_location_action_group_schema()
all_schemas = get_all_action_group_schemas()

# Validate schemas
validation_results = validate_all_schemas()
for name, result in validation_results.items():
    print(f"{name}: {'VALID' if result.valid else 'INVALID'}")

架构文件

生成的模式保存到 infrastructure/schemas/:

weather_action_group.json -天气服务OpenAPI模式
location_action_group.json -位置服务OpenAPI模式
validation_report.md -综合验证报告

这些模式可以直接与AWS CDK或CloudFormation一起使用，以创建基岩代理操作组。

用法

交互式CLI

使用以下命令运行应用程序：

# Using the installed script
uv run location-weather

# Or directly
uv run src/strands_location_service_weather/main.py

对于具有详细日志记录和跟踪的开发模式：

DEVELOPMENT=true uv run location-weather

用于Q CLI的MCP服务器

要与Amazon Q CLI或其他MCP客户端一起使用：

# Run as MCP server
uv run location-weather-mcp

看 MCP设置指南有关详细的Q CLI配置说明。

文档

其他文件可在 docs/ 目录：

MCP设置指南 -详细的Q CLI配置和使用说明
错误处理实施 -全面的错误处理和回退机制
开放遥测和MCP校准 -最佳实践合规性和标准一致性
工具集成最佳实践 -工具开发和集成指南
护栏最佳实践 -安全和内容过滤指南

备注：此项目包括通过GitHub Actions实现自动化CI/CD。所有测试、格式化和linting检查都会在pull请求上自动运行。

部署

AWS Lambda部署（基岩代理模式）

对于AWS Bedrock Agent的生产使用，请将天气工具部署为Lambda函数：

# 1. Build Lambda layers (dependencies and shared code)
uv run python infrastructure/build_lambda_layers.py

# 2. Deploy infrastructure with CDK
cd infrastructure && cdk deploy

这将创建：

中的拉姆达函数：具有优化图层的天气和警报工具
基岩药剂：预先配置了作用组的基岩药剂
IAM角色：安全所需的最低权限
监控：CloudWatch日志和分布式跟踪

部署的Lambda函数会自动与您的Bedrock代理集成，并可以通过Bedrock agent运行时调用。

有关详细的部署说明，请参阅基础架构/README.md.

地方发展

对于开发和测试，请使用本地CLI模式：

# Interactive CLI
uv run location-weather

# MCP server for Q CLI integration
uv run location-weather-mcp

开发工作流程

测试

该项目包括一个全面的测试套件，代码覆盖率为65%：

# Run all tests
uv run pytest

# Run fast tests only (skip performance benchmarks)
uv run pytest -m "not slow"

# Run tests with coverage report
uv run pytest --cov=src --cov-report=term-missing

# Run specific test categories
uv run pytest tests/test_weather_tools.py      # Unit tests
uv run pytest tests/test_integration.py       # Integration tests
uv run pytest tests/test_performance.py       # Performance tests

测试类别

单元测试：使用模拟依赖关系进行单个功能测试
集成测试：端到端功能测试
性能测试：验证优化目标和基准
MCP服务器测试：FastMCP服务器功能和工具注册

覆盖目标

核心业务逻辑：86%的覆盖率（location_weather.py）
配置：93%的覆盖率（config.py）
总体项目：65%的覆盖率，重点关注关键路径

代码质量和CI/CD

该项目通过GitHub Actions使用自动质量检查：

本地开发工作流程

在开发过程中 （快速反馈回路）：

# Format code
uv run black .

# Check and fix linting issues
uv run ruff check --fix .

# Run fast tests (~30 seconds, skips slow benchmarks)
uv run pytest -m "not slow"

推之前 （综合验证）：

# Run all tests including performance benchmarks
uv run pytest

# Optional: Check coverage
uv run pytest --cov=src --cov-report=term-missing

为什么使用此工作流？

本地快速测试：开发过程中的即时反馈（30秒）
本地全面测试：推前捕捉问题（60秒）
CI验证：多环境测试和安全检查（3-5分钟）

这种方法提供了 快速本地反馈 同时确保 全面验证 通过CI。

GitHub操作工作流

拉取请求检查：对每个PR进行快速测试、格式化和过滤
完整CI管道：在主分支上跨Python 3.10-3.13完成测试套件
覆盖范围报告：自动覆盖报告和趋势跟踪
安全扫描：依赖性漏洞检查
性能验证：自动性能回归检测

分支保护

主分支受到保护，需要：

通过所有状态检查
代码审查批准
合并前的最新分支

推荐开发周期：

进行更改 → 快速本地验证:

   uv run black .
   uv run ruff check --fix .
   uv run pytest -m "not slow"    # Fast feedback (30s)

承诺前 → 完全本地验证:

   uv run pytest                  # All tests (60s)
   git add .
   git commit -m "your message"

推送和公关 → 自动化CI验证 （多Python、安全性、覆盖率）

贡献

开发设置

克隆存储库:

   git clone https://github.com/CarmenAPuccio/strands-location-service-weather.git
   cd strands-location-service-weather

安装依赖项:

   uv sync --extra dev

运行测试以验证设置:

   uv run pytest -m "not slow"

拉取请求流程

创建要素分支:

   git checkout -b feature/your-feature-name

进行更改 遵循编码标准

进行全面的质量检查:

   uv run black .
   uv run ruff check --fix .
   uv run pytest                  # Full test suite including slow tests

承诺并推动:

   git add .
   git commit -m "feat: describe your changes"
   git push origin feature/your-feature-name

创建拉取请求 在GitHub上

编码标准

代码格式化：黑色（88个字符行长）
掉毛：使用现代Python模式
类型提示：公共职能所需
测试：新功能需要覆盖率超过80%的测试
文档：更新公共API的README和docstring
演出：保持响应时间目标（简单查询为15-20秒）

性能指南

对外部API调用使用HTTP会话重用
保持系统提示简洁（\<100字）
设置适当的超时（天气API为10秒）
基准测试对测试性能的影响
遵循中的性能转向指南 .kiro/steering/performance.md

配置

黑色：按照PEP 8标准格式化代码（88个字符行长）
拉夫：捕捉样式问题、未使用的导入并应用现代Python模式的快速linter
目标Python：3.10+（由链代理依赖性要求）

Strands Location Service Weather

快速接入

详细介绍

Strands定位服务天气

特性

建筑

关键组件

部署模式

基岩药剂部署

地方发展

开放遥测可观测性

跟踪结构

捕获的指标

开发模式

例子

项目结构

安装和设置

AWS权限设置

所需自定义策略

1.亚马逊位置服务访问

2.亚马逊基岩调用访问

重要提示

配置

环境变量

多模式部署配置

配置文件

部署模式

本地模式（默认）

MCP模式

卧室_智能模式

模式特定配置

OpenAPI模式生成

特性

生成的模式

CLI使用情况

程序化使用

架构文件

用法

交互式CLI

用于Q CLI的MCP服务器

文档

部署

AWS Lambda部署（基岩代理模式）

地方发展

开发工作流程

测试

测试类别

覆盖目标

代码质量和CI/CD

本地开发工作流程

为什么使用此工作流？

GitHub操作工作流

分支保护

贡献

开发设置

拉取请求流程

编码标准

性能指南

配置

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP