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

# .env 파일 생성
cat > .env << EOF
# 임베딩 서버 설정
EMBEDDING_HOST=http://192.168.0.100:7997
EMBEDDING_MODEL=openai/clip-vit-large-patch14

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

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

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

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

mcp-api-server/
│
├── .git/                           # Git 저장소
├── .python-version                 # Python 3.13.3
├── .env.example                    # 환경변수 템플릿
├── .gitignore                      # Git 무시 목록
│
├── pyproject.toml                  # 프로젝트 메타데이터 및 의존성
├── uv.lock                         # 의존성 잠금 파일
│
├── README.md                       # 프로젝트 개요 (이 파일)
├── CLAUDE.md                       # 개발 규약 및 환경 가이드
│
├── src/
│   └── mcp_api_server/             # 메인 패키지
│       │
│       ├── __init__.py             # 패키지 초기화
│       ├── main.py                 # FastAPI 진입점 (HTTP/SSE/WebSocket)
│       ├── mcp_cli.py              # MCP StdIO CLI 진입점
│       ├── server.py               # MCP 서버 인스턴스
│       ├── config.py               # 환경변수 설정 (Pydantic)
│       ├── models.py               # Pydantic 데이터 모델
│       ├── logging_config.py       # 로깅 설정
│       │
│       ├── tools/                  # MCP Tool 구현
│       │   ├── __init__.py
│       │   └── image_analysis.py   # YOLOv8 + 임베딩 분석
│       │
│       ├── resources/              # MCP Resource 구현 (선택)
│       │   └── __init__.py
│       │
│       └── prompts/                # MCP Prompt 구현 (선택)
│           └── __init__.py
│
├── examples/                       # 클라이언트 예제
│   ├── http_client.py              # HTTP/JSON-RPC 클라이언트 예제
│   └── websocket_client.py         # WebSocket 클라이언트 예제
│
└── tests/                          # 테스트 스위트
    ├── __init__.py
    ├── conftest.py                 # pytest 공유 fixtures
    ├── test_server.py              # FastAPI 엔드포인트 테스트
    └── test_models.py              # Pydantic 모델 테스트

from src.mcp_api_server.tools.image_analysis import analyze_image_impl
import asyncio

# 이미지 파일 경로로 분석
result = await analyze_image_impl(
    image_path="/path/to/image.jpg",
    conf_threshold=0.5
)

print(result.model_dump_json(indent=2))

{
  "detections": [
    {
      "class_name": "person",
      "confidence": 0.91,
      "bbox": [100.0, 50.0, 200.0, 300.0],
      "embedding": [0.12, -0.34, 0.56, ...]
    },
    {
      "class_name": "cat",
      "confidence": 0.78,
      "bbox": [300.0, 100.0, 400.0, 250.0],
      "embedding": [0.11, 0.22, -0.33, ...]
    }
  ],
  "total_objects": 2
}

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

# 서버 정보
GET /info
응답: {
  "name": "mcp-api-server",
  "version": "0.1.0",
  "protocol": "MCP (Model Context Protocol)",
  "transport": "HTTP/SSE and WebSocket",
  "description": "YOLOv8-based image analysis with embedding integration"
}

import asyncio
import httpx

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

asyncio.run(call_mcp_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}")

asyncio.run(ws_client())

# StdIO 기반 MCP 서버 실행
uv run python -m mcp_api_server.mcp_cli

{
  "mcpServers": {
    "mcp-api-server": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_api_server.mcp_cli"],
      "cwd": "D:\works\ai-projects\mcp-api-server\"
    }
  }
}

# HTTP 클라이언트 예제 실행
uv run python examples/http_client.py

# WebSocket 클라이언트 예제 실행
uv run python examples/websocket_client.py

# 모든 테스트 실행
uv run pytest

# 상세 출력 (-v: verbose)
uv run pytest -v

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

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

# 린트 검사 (Ruff)
uv run ruff check .

# 자동 포맷팅
uv run ruff format .

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

# Pylance strict mode 검사를 위해 IDE 사용
# VS Code 설정: python.analysis.typeCheckingMode = "strict"

# 설치
pip install "infinity-emb[all]"

# GPU 지원 실행
infinity_emb v2 --model-id openai/clip-vit-large-patch14 --port 7997 --device cuda

# CPU 실행 (GPU 없을 경우)
infinity_emb v2 --model-id openai/clip-vit-large-patch14 --port 7997 --device cpu

docker run -p 8080:8080 \
  -v $(pwd)/models:/build/models \
  localai/localai:latest \
  clip_image_embeddings

EMBEDDING_HOST=http://192.168.0.100:8080

# 수동으로 모델 다운로드
YOLO_HOME=./models python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"

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

httpx.ConnectError: Could not connect to http://192.168.0.100:7997

# 임베딩 서버 접근 가능 확인
curl http://192.168.0.100:7997/health

# 방화벽 설정 확인
# Windows: Defender 방화벽에서 포트 7997 허용

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

# 1. 새 브랜치 생성
git checkout -b feature/새-기능-이름

# 2. 코드 작성 및 테스트
uv run pytest
uv run ruff check .

# 3. 커밋
git add .
git commit -m "feat: 기능 설명"

# 4. 푸시 및 PR 생성
git push -u origin feature/새-기능-이름

git checkout -b fix/버그-이름
# ... 수정 ...
git commit -m "fix: 버그 설명"