# PointCloud MCP

> 3D Point Cloud(`.ply`/`.pcd`)를 **자연어로 질의**하는 MCP 서버.
> "3D 데이터를 LLM이 다루게 한다"는 아이디어를 open3d로 구현한 포트폴리오 데모.
> 3D Computer Vision(MVSNet·ICP·Point Cloud) 경험과 LLM/MCP 툴링을 결합한 차별화 프로젝트.

## 실행 증거

아래 이미지는 2026-07-14에 클린 Python 3.12 가상환경에서 MCP stdio 연결 후
`tools/list`와 `describe_pointcloud`를 실제 호출한 결과입니다.

![PointCloud MCP smoke test](assets/mcp-smoke-test.png)

| 검증 | 결과 |
|---|---|
| `pip install -e ".[dev]"` | 통과 (Python 3.12.11) |
| `python -m pytest -q` | 1 passed |
| MCP initialize · tools/list | 통과 — 3 tools |
| `describe_pointcloud` 호출 | 통과 — 합성 PLY 1,000 points |

현재 Open3D macOS wheel 호환성을 기준으로 Python 3.10–3.12를 지원합니다.

## 왜 만들었나
3D 재구성·정렬을 실무에서 다뤄온 엔지니어가, 그 도메인을 LLM 도구 생태계(MCP)에 노출하면
어떤 일이 가능한지 보여주기 위한 데모입니다. LLM 클라이언트가 3D 파일의 기하 속성을 이해하고,
평면을 검출하고, 두 스캔을 정렬(ICP)하도록 합니다.

## 노출 도구 (MCP tools)
| 도구 | 설명 |
|---|---|
| `describe_pointcloud(path)` | 점 개수·bounding box·centroid 등 요약 |
| `detect_plane(path)` | RANSAC으로 지배적 평면(바닥/벽) 검출 |
| `align(path_a, path_b)` | 두 Point Cloud를 ICP로 정렬, fitness/RMSE 반환 |

## 빠른 시작
```bash
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"             # open3d, numpy, mcp, pytest

# 샘플 Point Cloud 생성 (바닥 평면 + 벽, ICP용 이동본)
python data/make_sample.py

# MCP 없이 바로 테스트
python -m src.cli describe data/scan_a.ply
python -m src.cli plane    data/scan_a.ply
python -m src.cli align    data/scan_a.ply data/scan_b.ply

# 단위 테스트
python -m pytest -q
```

## MCP 클라이언트 연결 (Claude Desktop)
```json
{
  "mcpServers": {
    "pointcloud": {
      "command": "python",
      "args": ["/absolute/path/to/pointcloud-mcp/server.py"]
    }
  }
}
```
예: *"scan_a.ply의 점이 몇 개고 바닥 평면은 어디야?"* → `describe_pointcloud` + `detect_plane` 호출

## 기술 스택
`Python` · `open3d` · `NumPy` · `MCP`

## 데이터
`data/make_sample.py`가 생성하는 합성 Point Cloud. 외부/회사 데이터 없음.
실제 데이터로 쓰려면 Stanford Bunny, ScanNet 샘플 등 공개 데이터셋을 넣으면 됩니다.

## 관련 글

- [디지털 트윈에게 말을 걸다 — MCP 서버를 0→1로](https://feelgom.github.io/blog/blog/mcp-server-from-zero-to-one/)
- [Feelgom 기술 블로그](https://feelgom.github.io/blog/)

## 라이선스
MIT