Usda Soil

@pipeworx/usda-soil

SSURGO を通じて USDA-NRCS の土壌データにアクセスできます。SSURGO は、現地調査員が縮尺 1:12,000～1:63,360 で地図化し、毎年再公開している、米国の詳細な土壌調査データです。地点の土壌、地図単位に含まれる名称付き土壌系列とその特性および層位、そして調査データ全体のスキーマに対する任意の SQL を扱えます。

Pipeworx の一部です。AI エージェントを 1684 以上の稼働中データソースに接続する MCP ゲートウェイです。

ツール

• usda_soil_mapunit_at_point(lat, lon) — 地図単位キー、記号、正式名称、面積、農地分類、調査区域、およびその公開日を取得します。
• usda_soil_components(mukey, include_horizons?) — 地図単位内の土壌系列について、割合、分類体系、排水分類、傾斜範囲、水文グループ、土地利用能力分類、および水湿土壌評価を取得します。オプションで、砂・シルト・粘土、有機物、pH、有効水分容量、Ksat を含む深度別の層位も取得できます。
• usda_soil_query(sql) — SSURGO スキーマに対する読み取り専用の SELECT を実行します。

認証

認証キーは不要です。

soilgrids との違い

soilgrids は、ISRIC が機械学習で全球を 250 m 解像度で予測したデータです。こちらは、名称付き系列、公式分類体系、評価情報を含む、米国の実測値です。対象は米国とその領土に限られます。米国外では soilgrids を使用してください。また、地図化されたポリゴンではなく、モデル化された連続面が必要な場合にも適しています。

データソース

• https://sdmdataaccess.sc.egov.usda.gov/Tabular/post.rest — {"format":"JSON+COLUMNNAME","query":"<T-SQL>"} を POST します。

このパックで対処している注意点：

• SQL Server です。 LIMIT n ではなく TOP n を使用します。
• JSON+COLUMNNAME が返すのはオブジェクトではなく配列の配列です — Table[0] は列名の行です。runSql がこれらを結合してオブジェクトにします。
• エラーは OGC XML として 400 で返されます。 先頭 300 文字はすべて XML 名前空間の定型文なので、レスポンス本文をそのまま切り出すと、問題を示す一文が隠れてしまいます。@pipeworx/shared の summarizeErrorBody が <ServiceException> を取り出すため、不正な列名は次のように表示されます。 USDA Soil Data Access: 400 Invalid query: Invalid column name 'nosuchcolumn'. (from the upstream's XML error document)
• 有効な SELECT の結果が 0 件でも、エラーではなく空の Table が返されます — usda_soil_query は、空の結果を検索結果として示すのではなく、その旨を明示します。
• 列の場所は、推測したとおりではありません。 saverest（調査区域の公開日）は legend ではなく sacatalog にあります。farmlndcl は component ではなく mapunit にあります。component の土地利用能力に関する列は nirrcapcl／nirrcapscl です。
• 地点のジオメトリは、WKT point(lon lat) を使って SDA_Get_Mukey_from_intersection_with_WktWgs84 に渡します。経度が先です。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します。

{
  "mcpServers": {
    "usda-soil": {
      "url": "https://gateway.pipeworx.io/usda-soil/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/usda-soil/mcp の tools/list は、上の表にあるツールに加えて、共有 Pipeworx メタツール（ask_pipeworx、 discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール群）も返します。そのため、表示されるツール数はこの表より多くなります。単一パックのエンドポイントでは、現在、パック固有のツールに加えて共有ツールがおよそ 30 個一覧表示されます。接続の initialize 応答に正確な範囲が示されており、その日の状況を確認する際の正式な情報源になります。

これは意図的な設計であり、偶然の多重化ではありません。メタツールを使うことで、このパックが対象としていない質問にも対応できます。ask_pipeworx がカタログ全体を対象にルーティングするため、2 つ目の MCP サーバーを追加する必要はありません。現時点では、メタツールを含めずにパックのエンドポイントをマウントする方法はありません。追加のスキーマによるコンテキスト消費がルーティングの利点を上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度接続してください。

または、フル Pipeworx ゲートウェイに接続して、このパックのツールだけでなく、すべてのパックのツールを直接一覧表示できます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も同じゲートウェイと同じ 1684 以上のデータソースに接続します。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも ask_pipeworx を使えば、すべてのツールにアクセスできます。

MCP クライアントがない場合：HTTP で呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/usda_soil_mapunit_at_point \
  -H 'Content-Type: application/json' \
  -d '{"lat":41.6,"lon":-93.6}'

最初の呼び出しにアカウントは不要です。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/usda_soil_mapunit_at_point を使います。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を使います。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行でき、Pipeworx アカウントもゲートウェイとの往復通信も不要です。

{
  "mcpServers": {
    "usda-soil": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-usda-soil"]
    }
  }
}

または、起動を確認するために直接実行します。

npx -y @pipeworx/mcp-usda-soil

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx を使う

ツールを直接呼び出す代わりに、自然な英語で質問できます。この方法は、上記のパックエンドポイントとフルゲートウェイの両方で使えます。

ask_pipeworx({ question: "your question about Usda Soil data" })

ゲートウェイが適切なツールを選び、引数を自動的に設定します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT