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. 설치

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

2. 환경변수 설정

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

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. 실행

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 · 호환 클라이언트

{
  "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)

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.