# 프로젝트 루트에서 실행
uv sync

# .env 파일 생성
cat > .env << EOF
# PostgreSQL 데이터베이스 설정
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mcp_db
DB_USER=postgres
DB_PASSWORD=your_password

# YOLOv8 모델 설정
YOLO_MODEL=yolov8n.pt
YOLO_HOME=./src/mcp_server/models
YOLO_CONF_THRESHOLD=0.5

# MCP 서버 설정
MCP_SERVER_NAME=mcp-api-server
LOG_LEVEL=INFO
EOF

# FastMCP 방식 (권장, 간단함)
uv run python -m mcp_server

# 또는 MCP SDK 방식 (더 많은 기능)
MCP_SERVER_TYPE=sdk uv run python -m mcp_server

# 개발 모드 (자동 리로드 활성화)
uv run uvicorn src.mcp_server.main:app --reload

# 프로덕션 모드 (4개 워커)
uv run uvicorn src.mcp_server.main:app --workers 4

mcp-api-server/
│
├── .git/                                    # Git 저장소
├── .python-version                          # Python 3.13.3
├── .env.example                             # 환경변수 템플릿
├── .gitignore
│
├── pyproject.toml                           # uv 프로젝트 설정
├── uv.lock                                  # 의존성 잠금 파일
│
├── README.md                                # 이 파일
├── CLAUDE.md                                # 개발 규약
├── NOTION_USAGE_GUIDE.md                    # Notion 작업 문서 규칙
├── ARCHITECTURE.md                          # 아키텍처 설명
│
├── src/
│   └── mcp_server/                          # 메인 패키지
│       ├── __main__.py                      # MCP StdIO 진입점
│       ├── main.py                          # FastAPI HTTP/WS 진입점
│       ├── fastmcp_server.py                # FastMCP 서버 구현
│       ├── server.py                        # MCP 서버 인스턴스 (SDK용)
│       │
│       ├── commons/                         # 공유 유틸리티 (infrastructure)
│       │   ├── config.py                    # Pydantic Settings (환경변수)
│       │   ├── database.py                  # SQLAlchemy AsyncEngine + asyncpg
│       │   ├── logging.py                   # 로깅 설정
│       │   └── exceptions.py                # 커스텀 예외
│       │
│       ├── core/                            # 도메인 모델 (domain layer)
│       │   ├── yolo_model.py                # YOLOv8 lazy loading (스레드 안전)
│       │   └── embedding_client.py          # 외부 API 클라이언트
│       │
│       ├── schemas/                         # 데이터 모델 (Pydantic)
│       │   ├── response.py                  # 응답 모델 (Detection, AnalysisResult, ImageRecordResponse)
│       │   └── img_model.py                 # DB ORM 모델 (ImageRecord)
│       │
│       ├── services/                        # 비즈니스 로직 (service layer)
│       │   ├── image_analyzer_service.py    # YOLOv8 분석 로직
│       │   ├── image_query_service.py       # DB 조회 로직
│       │   └── repository.py                # DB 저장 로직
│       │
│       ├── tools/                           # MCP Tool 구현 (presenter layer)
│       │   ├── __init__.py
│       │   └── image_analysis.py            # analyze_image tool
│       │
│       ├── resources/                       # MCP Resource (선택)
│       │   └── __init__.py
│       │
│       ├── prompts/                         # MCP Prompt (선택)
│       │   └── __init__.py
│       │
│       └── utils/                           # 공유 유틸리티
│           ├── suppress_output.py           # 출력 억제 데코레이터
│           └── image_utils.py               # 이미지 처리 헬퍼
│
├── tests/                                   # 테스트 스위트
│   ├── conftest.py                          # pytest fixtures
│   ├── test_models.py                       # Pydantic 모델 테스트
│   └── test_*.py                            # 기능별 테스트
│
└── examples/ (선택)                         # 클라이언트 예제
    ├── http_client.py                       # HTTP JSON-RPC 클라이언트
    └── websocket_client.py                  # WebSocket 클라이언트

┌──────────────────────────────────────────────────────────┐
│ Presenter Layer (MCP Tools)                              │
│  - tools/image_analysis.py                               │
│  - MCP Protocol 변환 (JSON-RPC 2.0)                      │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│ Service Layer (비즈니스 로직)                             │
│  - services/image_analyzer_service.py                    │
│  - services/image_query_service.py                       │
│  - @atransactional 데코레이터로 DB 트랜잭션 관리        │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│ Core Layer (도메인 모델)                                 │
│  - core/yolo_model.py (double-checked locking)          │
│  - core/embedding_client.py                             │
│  - schemas/img_model.py (SQLAlchemy ORM)                │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│ Utility Layer (공유 인프라)                              │
│  - commons/database.py (AsyncEngine + asyncpg)          │
│  - commons/config.py (환경변수)                         │
│  - utils/suppress_output.py (출력 억제)                 │
└──────────────────────────────────────────────────────────┘

{
  "image_path": "/path/to/image.jpg",
  "detections": [
    {
      "class_name": "person",
      "confidence": 0.91,
      "bbox": [100.0, 50.0, 200.0, 300.0]
    }
  ],
  "total_objects": 1
}

# PostgreSQL 설치 (Windows)
# https://www.postgresql.org/download/windows/

# 데이터베이스 생성
psql -U postgres -c "CREATE DATABASE mcp_db;"

CREATE TABLE image_records (
  id SERIAL PRIMARY KEY,
  path VARCHAR NOT NULL UNIQUE,
  category VARCHAR NOT NULL,
  confidence FLOAT NOT NULL,
  description TEXT,
  objects JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

from mcp_server.commons.database import atransactional, AsyncSession
from mcp_server.schemas.response import AnalysisResult

@atransactional
async def save_analysis(result: AnalysisResult, db: AsyncSession):
    """데이터베이스에 분석 결과 저장"""
    from mcp_server.schemas.img_model import ImageRecord
    
    record = ImageRecord(
        path=result.image_path,
        category="detected_object",
        confidence=result.detections[0].confidence if result.detections else 0.0,
    )
    db.add(record)
    # 트랜잭션 자동 커밋 (예외 발생 시 자동 롤백)

# 헬스 체크
GET /health
→ {"status": "ok"}

# 서버 정보
GET /info

import httpx
import asyncio

async def call_tool():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/mcp/messages",
            json={
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                    "name": "analyze_image",
                    "arguments": {
                        "image_path": "/absolute/path/to/image.jpg",
                        "conf_threshold": 0.5
                    }
                }
            }
        )
        print(response.json())

asyncio.run(call_tool())

import asyncio
import json
import websockets

async def ws_client():
    async with websockets.connect("ws://localhost:8000/mcp/ws") as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "initialize",
            "params": {}
        }))
        response = await ws.recv()
        print(f"Response: {response}")

asyncio.run(ws_client())

{
  "mcpServers": {
    "mcp-api-server": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server"],
      "cwd": "/absolute/path/to/mcp-api-server"
    }
  }
}

# 모든 테스트 실행
uv run pytest

# 상세 출력
uv run pytest -v

# 특정 테스트 실행
uv run pytest tests/test_models.py -v

# 커버리지 리포트
uv run pytest --cov=src

# 린트 검사
uv run ruff check .

# 자동 포맷팅
uv run ruff format .

# 린트 + 포맷 함께
uv run ruff check . && uv run ruff format .

# VS Code Pylance strict mode 사용 (IDE에서 설정)
# .vscode/settings.json:
{
  "python.analysis.typeCheckingMode": "strict"
}

# 수동 다운로드
uv run python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"

# 또는 서버 실행 (자동 다운로드)
uv run uvicorn src.mcp_server.main:app

# DB 접속 가능 확인
psql -h localhost -U postgres -d mcp_db -c "SELECT 1;"

# 방화벽 설정 확인 (Windows)
# → Defender 방화벽에서 PostgreSQL 포트 5432 허용

# 더 작은 모델 사용
echo "YOLO_MODEL=yolov8n.pt" >> .env

# 또는 명령어로 실행
YOLO_MODEL=yolov8s.pt uv run uvicorn src.mcp_server.main:app

git checkout -b feature/기능-이름
# ... 작업 ...
git add .
git commit -m "feat(scope): 기능 설명"
git push -u origin feature/기능-이름

git checkout -b fix/버그-이름
# ... 수정 ...
git commit -m "fix(scope): 버그 설명"
git push -u origin fix/버그-이름

from mcp_server.services.image_analyzer_service import ImageAnalyzerService

service = ImageAnalyzerService()

# 여러 이미지를 동시에 분석
results = await service.analyze_images_abatch([
    "/path/to/image1.jpg",
    "/path/to/image2.jpg",
    "/path/to/image3.jpg",
])