# pointcloud-mcp

> **世界初の点群（LAS/LAZ）専用 MCP サーバー第1号**
>
> Claude Desktop / Claude Code に自然言語で「起工.las と 出来形.las から土量とヒートマップ出して」と頼むだけで、差分DEM・盛/切/純土量・ヒートマップPNG・PDFレポートまで一気通貫で生成する。

[English README](./README.en.md)

---

## なぜ作ったか

2026年5月時点で、Revit (★400+) / SketchUp (Trimble公式) / AutoCAD / IFC には Claude用の MCP サーバーが存在するが、**点群（LAS/LAZ）専用の MCP は世界に1つも無い**。一方、日本は i-Construction で点群人口世界一の国。作り手不在 × ユーザー世界一 という稀有な歪みを埋めるためのプロジェクト第1号。

設計思想：
- **TrendPoint の代替ではなく、CloudCompare の上の自動化レイヤー**として位置づけ
- 中小〜下請けの兼任 ICT 担当者が「CC で計算 → Claude で帳票化」できるツールを目指す
- 規格値判定や複雑な線形処理は最初は捨てる。**差分・土量・ヒートマップ・PDF** の4機能で MVP

---

## 提供ツール（v0.1.0）

| ツール | 用途 |
|---|---|
| `pointcloud_info` | LAS/LAZ のメタ情報（点数・XYZ範囲・色・CRS）を取得 |
| `pointcloud_diff` | 2つのLASを差分し、盛/切/純土量・ヒートマップ・PDFレポートまで生成 |
| `pointcloud_align_2d` | 4パラメータ2D Helmert で LAS を再投影（既知2点対応） |
| `pointcloud_synthetic_test` | 合成データで動作検証（理論土量との誤差を確認） |

---

## 動作環境

- Windows 10/11、macOS、Linux（Pythonが動けばOK）
- Python 3.10 以上
- 依存ライブラリ：laspy / lazrs / numpy / scipy / matplotlib / rasterio / reportlab / mcp

---

## インストール

```powershell
# クローン
git clone https://github.com/jyou-syo/pointcloud-mcp.git
cd pointcloud-mcp

# 依存導入
pip install -r requirements.txt
# もしくは
pip install -e .
```

`requirements.txt` または `pyproject.toml` の dependencies を参照。

---

## Claude Desktop への登録

`%APPDATA%\Claude\claude_desktop_config.json`（Windows）または
`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）に以下を追記：

```json
{
  "mcpServers": {
    "pointcloud": {
      "command": "python",
      "args": ["-m", "pointcloud_mcp.server"],
      "cwd": "E:\\path\\to\\pointcloud-mcp"
    }
  }
}
```

Claude Desktop を再起動すると、チャット入力欄の左下「🔧」アイコンに `pointcloud` が表示される。

---

## 使い方（自然言語）

Claude Desktop / Claude Code のチャットに、たとえば次のように話しかけるだけ：

> 「`E:\起工.las` と `E:\出来形.las` の差分を出して、`E:\out\` にPDFレポートまで作って」

Claude が自動的に `pointcloud_diff` を呼び、

- `diff_heatmap.png`（赤=盛土／青=切土の空間分布）
- `diff_histogram.png`（Δh分布）
- `diff_report.pdf`（数値・ヒートマップ統合レポート）

を生成する。

### より明示的に呼ぶ場合

> 「`pointcloud_diff` で、`before_path=...`, `after_path=...`, `out_dir=...`, `resolution_m=0.20`, `agg=min` で実行して」

---

## 合成データ自己検証

```python
from pointcloud_mcp.server import pointcloud_synthetic_test
result = pointcloud_synthetic_test("./out/synth_test")
print(result["summary"])
# 期待 750 m³ に対し計算 747.886 m³（誤差 0.28%）
```

理論盛土量との誤差 ±2% を合格基準としている。

---

## 実データ検証

実工事現場の LAS ペア（起工 vs 出来形）で動作確認済み：

| | 点数 | 容量 |
|---|---|---|
| 起工測量 | 16,109,029 | 418MB |
| 出来形完成 | 1,369,871 | 35MB |

- 重なり領域: 13.36m × 15.32m ≒ 205 m²
- 計算時間: **約3秒**（読込込み）
- 盛土 8.75 m³ / 切土 52.56 m³ / 純土量 -43.80 m³
- 分解能 0.05〜0.50m スイープでも純土量は ±5% 以内で安定

---

## 制限事項（v0.1.0）

- **experimental / under development** — 規格値判定や工事範囲ポリゴンマスクは未実装
- LandXML 読込は `tools/landxml.py` に実装済みだが MCP ツールとしては未公開（v0.2.0 で実装予定）
- 大規模 LAS（1億点超）でもメモリ次第で動作するが、点群そのものに穴がある場合は充填率が下がる
- CRS（座標系）情報は VLR の WKT のみ参照、EPSG コード経由の自動変換は未対応

---

## ロードマップ

| Ver | 内容 |
|---|---|
| v0.1.0 | MVP（差分・土量・ヒートマップ・Helmert・合成テスト） ← **今ここ** |
| v0.2.0 | LandXML 設計面との差分、工事範囲ポリゴンマスク |
| v0.3.0 | 規格値判定（土工 ±50mm, 法面 ±50mm 等）、PDFレポート拡張 |
| v1.0.0 | 実用レベル、Anthropic 公式 MCP ディレクトリ掲載 |

---

## ライセンス

MIT License — 商用・改変・再配布自由。詳細は [LICENSE](./LICENSE) を参照。

---

## 作者

**条谷 貴志**（(株)兵庫土木サポート 代表）
- 会社HP: https://doboku-support.co.jp/
- YouTube: https://www.youtube.com/@dobokusuppurt_johyo7
- X: https://x.com/johyo7

実装の半分以上は Claude Code（Anthropic）と共同で行いました。