# VS Auto Trend — MCP Server (연동 담당자용)

사내 LLM이 **VS Auto Trend**의 트렌드 데이터와 컨셉 브리프 생성 기능을
**MCP tool**로 바로 사용하게 해주는 얇은 래퍼입니다. 기존 앱은 수정하지 않습니다.

- 읽기 tool → `GET /api/v1/*` (X-API-Key 헤더)
- 브리프 생성 tool → `POST /api/brief/generate?k=<비밀번호>`

## 제공 Tools

| tool | 설명 | 인증 |
|------|------|------|
| `get_weekly_trends` | 주간 TOP N 트렌드 | X-API-Key |
| `get_trend_detail(trend_id)` | 트렌드 + 관련 기사 | X-API-Key |
| `get_articles(section?, category?, min_impact?, limit?)` | 큐레이션 기사 | X-API-Key |
| `get_categories()` | 제품 카테고리 유니버스 | X-API-Key |
| `get_sources()` | 수집 소스 유니버스 | X-API-Key |
| `generate_concept_brief(...)` | 구조화 파라미터 → 7-필드 브리프 | 비밀번호(?k=) |
| `upload_reference_doc(...)` | **[예정]** 참고문서 RAG (서버측 엔드포인트 구현 후 활성화) | — |

---

## 1. 설치

```bash
cd mcp_server
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 2. 환경변수 설정

`.env.example` 을 참고해 값을 채웁니다(프로세스 env로 주입해도 됨).

```bash
export VS_AUTO_TREND_BASE_URL=http://127.0.0.1:8077   # 내부 인스턴스 주소
export VS_AUTO_TREND_API_TOKEN=<발급받은 토큰>
export VS_AUTO_TREND_PASSWORD=<대시보드 비밀번호>
```

- 토큰이 없으면 담당에 요청하세요. 앱을 직접 돌리는 경우 `~/.config/vs-auto-trend/vs_auto_trend_api_token` 파일에서 자동 로드됩니다.

## 3. 실행

```bash
python server.py                     # stdio (LLM 앱이 같은 서버에서 프로세스로 붙일 때)
MCP_TRANSPORT=sse python server.py   # HTTP(SSE) (원격/별도 프로세스로 붙을 때, 기본 127.0.0.1:8770)
```

---

## 4. 사내 LLM 앱에 붙이는 법

### (A) MCP 클라이언트 설정 파일에 등록 — Claude Desktop · Cursor · 호환 클라이언트

```jsonc
{
  "mcpServers": {
    "vs-auto-trend": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server/server.py"],
      "env": {
        "VS_AUTO_TREND_BASE_URL": "http://127.0.0.1:8077",
        "VS_AUTO_TREND_API_TOKEN": "<토큰>",
        "VS_AUTO_TREND_PASSWORD": "<비밀번호>"
      }
    }
  }
}
```

### (B) 직접 만든 LLM 앱에서 MCP Python SDK로 연결 (stdio)

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="python",
    args=["/absolute/path/to/mcp_server/server.py"],
    env={
        "VS_AUTO_TREND_BASE_URL": "http://127.0.0.1:8077",
        "VS_AUTO_TREND_API_TOKEN": "<토큰>",
        "VS_AUTO_TREND_PASSWORD": "<비밀번호>",
    },
)

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()          # tool 스키마 자동 수신 → LLM tool-calling에 연결
        trends = await session.call_tool("get_weekly_trends", {})
        brief = await session.call_tool("generate_concept_brief", {
            "trend_id": "t1", "persona": "linkedin",
            "content_type": "product", "language": "both",
        })
```

### (C) 원격(SSE)으로 붙일 때

서버를 `MCP_TRANSPORT=sse` 로 띄운 뒤, 클라이언트에서 SSE URL(`http://<host>:8770/sse`)로 연결합니다.
사내 모델(Nova) tool-calling 루프에서 `list_tools`로 받은 스키마를 그대로 tool 정의로 넘기고,
tool 호출이 오면 `call_tool(name, args)` 로 프록시하면 됩니다.

---

## 인증·보안 메모

- 토큰/비밀번호는 **환경변수로만** 주입하고 대화창·로그·소스에 넣지 마세요.
- 내부 기술자료 RAG(`upload_reference_doc`)를 붙일 계획이면, 문서 원문·임베딩이
  **내부망 밖으로 나가지 않도록** MCP 서버·벡터스토어를 VPC 내부에 두세요.
- 상세 tool 입력/응답 스키마는 리포지토리 밖 `VS_MCP_Tool_Spec.md` 참조.

---

## 프론트엔드 (선택) — 컨셉 브리프 생성 화면

의존성 없는 **단일 HTML**입니다. 앱과 **같은 오리진**에서 서빙해야 인증(`?k=`)·POST가 됩니다.

1. `frontend/brief_studio.html` 를 앱의 `static/` 폴더에 복사
2. `http://<서버>:PORT/static/brief_studio.html` 접속
3. 상단에 접속 비밀번호 입력 → 트렌드 불러오기 → 구조화 입력 → 브리프 생성

`file://`로 직접 열면 브라우저 CORS로 API에 붙지 않습니다(같은 오리진 서빙 필수).

### 참고문서 인사이트 (브리프에 통합)
`brief_studio.html`은 참고문서를 업로드하면 AI 인사이트를 도출해 **컨셉 브리프 생성의 근거로 반영**합니다(별도 탭 아님).
필요 엔드포인트: `POST /api/reference/insight`(문서→인사이트) + `POST /api/brief/generate`의 `reference_context` 처리.
백엔드 코드는 `backend/reference_insight.py` 참고. 의존성: `pypdf`, `python-docx`.