Usgs Pub Wh MCP

USGS出版物仓库MCP服务器

一个安全强化的MCP服务器，它公开了 美国地质勘探局出版物仓库API 具有输入验证、速率限制、审计日志记录和安全的HTTP客户端控制。

此回购包括什么

• 单MCP工具： search_publications --带分页的全文、标题和index_id搜索
• 三种运输方式： stdio （克劳德桌面/光标）， sse, streamable-http （Docker/k8s）
• 安全模块(security/)--验证、速率限制、审计日志记录、OTel跟踪
• Docker镜像+Helm chart用于AWS EKS上的生产部署
• 代理评估集成(examples/)--基准线束+黄金评估集

快速开始

# Install dependencies
uv sync

# Run locally (stdio — for Claude Desktop / Cursor)
uv run python main.py --transport stdio

# Run locally (HTTP — for testing with curl or the agent harness)
uv run python main.py --transport streamable-http --host 127.0.0.1 --port 8000

# Health check
curl http://localhost:8000/health

复制 .env.example 到 .env 在运行之前配置速率限制、超时和OTel导出。

MCP端点（HTTP传输）

通过HTTP初始化：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"local-test","version":"1.0"}}}'

工具

search_publications(query, title, index_id, page_size, page_number)

• query --全文关键字搜索（删除停用词，组合复数）
• title --出版物标题中的精确子字符串匹配
• index_id --通过USGS索引ID检索特定出版物（仅限查询/标题）
• page_size --1–100，默认值10
• page_number --基于1，默认为1

测试

uv run pytest                        # unit tests + 100% coverage on security.tool_registry
uv run pytest tests/test_api_integration.py  # real USGS API calls (requires internet)

代理评估集成

从OTel跟踪中评估代理行为——无需重新执行。

# Terminal 1 — MCP server
uv run python main.py --transport streamable-http --host 127.0.0.1 --port 8000

# Terminal 2 — agentevals live UI (optional)
agentevals serve --dev

# Terminal 3 — run 10 benchmark tasks and save traces
export OPENAI_API_KEY=sk-...
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
uv run python examples/agent_harness.py

# Evaluate offline
agentevals run examples/traces/*.json \
  --eval-set examples/eval_set_usgs.json \
  -m tool_trajectory_avg_score \
  -m response_match_score

看 examples/README.md 了解完整的工作流程、Kubernetes设置和故障排除。

码头工人

# Build local image (amd64)
make build-image

# Push multi-arch image (amd64 + arm64) to ECR
make push-image

# Run the published image
docker run --rm -p 8000:8000 \
  607399646027.dkr.ecr.us-east-1.amazonaws.com/navteca/images/usgs-mcp:latest

关键Makefile变量： IMAGE_URI, IMAGE_PLATFORMS, AWS_PROFILE （默认值 navteca), AWS_REGION （默认值 us-east-1).

Kubernetes

make image IMAGE_URI=...607.../usgs-mcp:0.2.0

kubectl apply -k k8s

kubectl set image deployment/usgs-publications-mcp \
  mcp-server=...607.../usgs-mcp:0.2.0 -n mcp-servers

kubectl rollout status deployment/usgs-publications-mcp -n mcp-servers

kubectl port-forward svc/usgs-publications-mcp 8000:80 -n mcp-servers

Helm图表：

make chart-package          # → dist/usgs-pub-wh-mcp-.tgz
make chart-release          # push to ECR OCI registry
helm install usgs-mcp ./chart

参考

• 美国地质勘探局API文件：
• 安全控制： 安全.md
• 部署选项： 部署.md
• 开发者指南： 代理商.md