# Hello, Plugins! — Python OpenAI Plugin

`hello_plugins` 도구를 호출하면 정확히 `Hello, Plugins!`를 반환하는 최소 OpenAI Plugin 예제입니다.

OpenAI Plugin은 Skill, MCP 서버 또는 둘 다로 구성할 수 있습니다. 이 프로젝트는 실행 코드가 필요한 가장 작은 형태이므로 Python MCP 서버 하나만 사용합니다. OpenAI API를 직접 호출하지 않으므로 `OPENAI_API_KEY`도 필요하지 않습니다.

## 프로젝트 구조

```text
hello-plugins-python/
├── server.py          # MCP 서버와 hello_plugins 도구
├── test_server.py     # 반환 문자열 테스트
├── requirements.txt  # 고정된 Python 의존성
├── pyproject.toml
├── Dockerfile
└── README.md
```

## Windows 11 / PowerShell에서 실행

Python 3.10 이상이 필요합니다.

```powershell
cd hello-plugins-python
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python server.py
```

실행 후 MCP Streamable HTTP 주소는 다음과 같습니다.

```text
http://localhost:8000/mcp
```

PowerShell 실행 정책 때문에 가상환경 활성화가 막히면 현재 터미널에서만 다음 명령을 먼저 실행합니다.

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

## macOS / Linux에서 실행

```bash
cd hello-plugins-python
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python server.py
```

## 테스트

```bash
python -m pytest -q
python verify_mcp.py
```

예상 결과:

```text
1 passed
MCP verification passed: Hello, Plugins!
```

## MCP Inspector로 확인

Node.js가 설치되어 있다면 다음을 실행합니다.

```bash
npx @modelcontextprotocol/inspector
```

Inspector에서 Transport를 `Streamable HTTP`로 선택하고 URL에 `http://localhost:8000/mcp`를 입력합니다. 연결 후 `hello_plugins` 도구를 호출하면 다음 문자열이 반환됩니다.

```text
Hello, Plugins!
```

## ChatGPT Work에 개인 Plugin으로 연결

ChatGPT가 로컬 PC의 `localhost`에 직접 접근할 수 없으므로, 테스트하려면 `/mcp` 엔드포인트를 공개 HTTPS 주소로 배포하거나 OpenAI Secure MCP Tunnel을 사용해야 합니다.

1. 서버를 공개 HTTPS 환경에 배포합니다.
2. ChatGPT에서 **Settings → Security and login → Developer mode**를 켭니다.
3. Plugins 화면에서 `+`를 누르고 `https://YOUR-DOMAIN/mcp`를 입력합니다.
4. 생성된 개인 Plugin을 설치합니다.
5. Work 채팅에서 `@Hello Plugins`를 선택하고 “플러그인 인사말을 출력해줘”라고 요청합니다.

## Docker 실행

```bash
docker build -t hello-plugins .
docker run --rm -p 8000:8000 hello-plugins
```

## 핵심 코드

```python
@mcp.tool(
    name="hello_plugins",
    description="Return the exact greeting 'Hello, Plugins!'. This tool is read-only.",
)
def hello_plugins() -> str:
    return "Hello, Plugins!"
```

## 참고

- 공식 OpenAI Plugin 문서: https://developers.openai.com/plugins
- Plugin Quickstart: https://developers.openai.com/plugins/quickstart
- MCP 서버 개발: https://developers.openai.com/plugins/build/mcp-server