MCP 통합을 갖춘 LLM 기반 분석 시스템

언어 모델에 테이블 형식 데이터 분석을 위한 도구 세트를 제공하는 MCP-서버: 로드, 정리, 그래프 작성, 보고서 조립. 자체 채팅 인터페이스는 개발하지 않음 — 기성 플랫폼의 웹 인터페이스를 사용함 (Claude를 기본 클라이언트로, ChatGPT를 대안으로).

동일한 도구 레지스트리가 두 프로토콜로 동시에 게시됩니다:

시스템이 할 수 있는 일

도구 12개, 스킬 5개. 전체 목록은 describe_system 호출 또는 ARCHITECTURE.md에서 확인할 수 있습니다.

추가 기능:

1. 분석 자동 추천 — suggest_analysis가 어떤 컬럼이 시간 축이고, 어떤 것이 지표이고, 어떤 것이 분석 기준인지 판단하여 각 단계의 근거와 함께 완성된 호출 계획을 반환합니다.

2. 멀티-포맷 및 멀티-소스 — CSV, TSV, Excel, JSON, Parquet; 카탈로그, 로컬 경로 또는 HTTP(S) 링크. 마지막 항목은 웹 시나리오에서 핵심적입니다: 브라우저 채팅에 업로드된 파일은 서버에서 접근할 수 없습니다.

3. 한 번의 명령으로 보고서 조립 — build_report가 누락된 그래프를 자체적으로 보완하고 세 가지 형식의 문서를 출력합니다.

Related MCP server: Claude Data Buddy

설치

Python 3.10 이상이 필요합니다.

git clone <адрес-репозитория>
cd llm-analytics-mcp

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

1단계. 테스트 데이터

저장소의 데이터는 Superstore 스키마를 기반으로 합성 생성되었습니다. 요구사항이 이를 명시적으로 허용합니다: «데이터를 직접 생성하거나 알려진 데이터셋을 사용할 수 있습니다».

python scripts/prepare_dataset.py --synthetic --rows 4000

완성된 파일은 이미 data/에 있습니다 — 명령이 필요한 경우는 데이터를 다시 생성하거나 볼륨을 변경하려는 때뿐입니다.

Kaggle이 아닌 합성 데이터를 사용하는 이유

생성기는 시스템이 정확히 무엇을 보여주는지 통제할 수 있게 합니다:

• 검증 가능한 패턴이 내장되어 있음 — 상승 추세, 연말 정점이 있는 연간 계절성, 그리고 «할인 30% 초과 → 마이너스 이익» 관계. 덕분에 분석 결론이 우연이 아니라 의미를 갖습니다.

• 결함이 의도적으로 주입됨. 실제 Superstore는 거의 완벽하게 깨끗합니다: 결측값과 중복값이 없으면 DataCleaningSkill은 «0행 삭제»라고 보고하게 되고, 정리를 시연할 수 없게 됩니다.

• 재현성. 고정된 seed=42 — 검증자는 예시와 정확히 동일한 데이터와 보고서의 동일한 수치를 받게 됩니다.

• 저장소가 자족적임. 프로젝트를 실행하기 위해 Kaggle 계정이 필요하지 않습니다.

실제 Superstore 로드도 지원됩니다 — 컬럼 구조가 일치합니다:

python scripts/prepare_dataset.py --input ~/Downloads/Sample-Superstore.csv

스크립트가 생성하는 것

컬럼: Date, Product, Region, Sales, Quantity, Profit (요구사항에서) 추가로 분석 기준 Category, Sub-Category, Segment, Discount, Ship Mode. 기간 — 2021–2024, 48개월.

결함 구성은 실행 시 출력되며 결정적입니다:

2단계. 서버 없이 검증

로드부터 PDF 보고서까지 전체 체인의 종단 간 실행:

PYTHONPATH=src python -m analytics_mcp.selfcheck

스크립트는 LLM이 대화에서 수행하는 작업을 반복하지만 결정적으로 수행합니다. 데모 전 smoke-테스트로 유용합니다: 통과한다면 문제는 거의 확실히 분석이 아닌 통합에 있는 것입니다.

3단계. 서버 실행

PYTHONPATH=src uvicorn analytics_mcp.app:app --host 127.0.0.1 --port 8000

확인:

curl http://127.0.0.1:8000/health

유용한 주소:

포트가 사용 중인 경우. 이전에 시작된 프로세스가 계속해서 이전 코드로 응답할 수 있습니다 — 증상이 기만적입니다: /health는 응답하지만 변경 사항이 적용되지 않습니다. 재시작 전에: pkill -f uvicorn.

4단계. ngrok을 통한 공개 주소

Claude는 외부에서 서버에 접근하므로 HTTPS 주소가 필요합니다.

# 1. Установка и регистрация: https://ngrok.com/download
ngrok config add-authtoken <ваш-токен>

# 2. В личном кабинете ngrok зарезервируйте бесплатный статический домен
#    (Domains -> Create Domain). Без него адрес меняется при каждом
#    перезапуске, и настройку коннектора придётся повторять.

# 3. Запуск туннеля
ngrok http 8000 --domain=ваш-домен.ngrok-free.app

그런 다음 주소를 환경에 등록하고 서버를 재시작합니다:

cp .env.example .env
# в .env укажите:
#   PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app

export PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app
export MCP_ALLOWED_HOSTS='127.0.0.1:*,localhost:*,*.ngrok-free.app'
PYTHONPATH=src uvicorn analytics_mcp.app:app --host 127.0.0.1 --port 8000

«연결되지 않음»의 가장 흔한 원인. MCP SDK는 기본적으로 DNS 리바인딩 보호를 활성화하며 localhost 형식의 Host 헤더만 수락합니다. 터널 뒤에서는 Host에 ngrok 도메인이 포함되며 요청은 커넥터 연결 단계에서 명확한 오류 없이 거부됩니다. MCP_ALLOWED_HOSTS 변수가 정확히 이 문제를 해결합니다.

5단계. Claude에 연결 (기본 시나리오)

1. Settings → Connectors → Add custom connector를 엽니다.

2. 주소를 지정합니다: https://your-domain.ngrok-free.app/mcp (/mcp 접미사에 주의).

3. 저장하고 커넥터가 연결됨 상태로 전환되었는지 확인합니다.

4. 새 대화에서 도구 메뉴를 통해 analytics_mcp 커넥터를 활성화합니다.

5. prompts/system_prompt.md의 내용을 프로젝트 설명(Project instructions)에 복사합니다 — 호출 순서를 지정합니다.

확인 요청: «사용 가능한 데이터셋은 무엇인가요?» — 모델은 list_datasets를 호출하고 카탈로그 내용을 표시해야 합니다.

6단계. ChatGPT에 연결 (대체 시나리오)

1. 공개 주소로 스펙을 내려받습니다:

   PUBLIC_BASE_URL=https://ваш-домен.ngrok-free.app \
     PYTHONPATH=src python scripts/export_openapi.py

2. Custom GPT를 생성합니다: Explore GPTs → Create → Configure.

3. Create new action → Schema — openapi.json 내용을 붙여넣습니다.

4. Authentication: None.

5. Instructions 필드에 prompts/system_prompt.md를 붙여넣습니다.

그래프 표시의 세부 사항 및 특징은 prompts/gpt_action_setup.md에 있습니다.

데모 시나리오

요청 순서는 스크린샷에서 하나의 요청이 아닌 호출 체인이 보이도록 선정되었습니다. 핵심 장면은 4단계입니다: 하드코드가 아니라 모델이 무엇을 계획하는지 보여줍니다.

결과 예시 — docs/report_example.md, 그래프 — docs/plots/.

작업 스크린샷

데모 자료는 docs/screenshots/에 있습니다:

스크린샷은 시스템의 핵심 속성을 보여줍니다: 호출 체인을 LLM이 제어합니다. 모델이 어떤 도구를 호출할지 스스로 결정하고, 도구 세트의 한계(예: 행 필터링 부재)를 발견하며, 결과를 왜곡하는 대신 이를 보고합니다.

통합 확인

# Полный цикл по обоим транспортам: initialize, tools/list, tools/call,
# возврат изображения, обработка ошибочных аргументов
python scripts/integration_test.py

저장소 구조

llm-analytics-mcp/
├── README.md                    инструкция (этот файл)
├── ARCHITECTURE.md              архитектура и роль MCP/скиллов
├── openapi.json                 спецификация для Custom GPT Action
├── requirements.txt
├── .env.example
├── data/                        тестовые данные
├── docs/
│   ├── report_example.md/html/pdf   пример сгенерированного отчёта
│   ├── plots/                       примеры графиков
│   └── screenshots/                 скриншоты диалога
├── prompts/
│   ├── system_prompt.md         инструкция для LLM
│   └── gpt_action_setup.md      настройка Custom GPT Action
├── scripts/
│   ├── prepare_dataset.py       подготовка данных
│   ├── export_openapi.py        выгрузка спецификации
│   └── integration_test.py      проверка обоих транспортов
└── src/analytics_mcp/
    ├── core/                    реестр инструментов, хранилище, модели
    ├── skills/                  бизнес-логика этапов анализа
    ├── tools/                   инструменты, публикуемые наружу
    ├── transports/              адаптеры MCP и REST
    ├── rendering/               оформление графиков, артефакты
    ├── app.py                   сборка ASGI-приложения
    └── selfcheck.py             сквозная самопроверка

나만의 도구 추가 방법

이때 핵심은 변경되지 않습니다. src/analytics_mcp/tools/my_tools.py 파일을 생성합니다:

from __future__ import annotations

from analytics_mcp.core.datasets import store
from analytics_mcp.core.registry import tool


@tool(tags=("stats",), skill="DataLoadingSkill", title="Топ значений")
def top_values(column: str, dataset_id: str | None = None, limit: int = 10) -> dict:
    """Возвращает самые частые значения колонки.

    Args:
        column: Имя колонки.
        dataset_id: Датасет. По умолчанию — последний использованный.
        limit: Сколько значений вернуть.
    """
    record = store.get(dataset_id)
    record.require_column(column)
    counts = record.df[column].value_counts().head(limit)
    return {str(k): int(v) for k, v in counts.items()}

서버를 재시작합니다. 도구는 두 프로토콜 모두에 즉시 나타납니다: MCP의 tools/list와 REST의 /openapi.json에. tools 패키지는 모듈을 자동으로 임포트하고, JSON 스키마는 시그니처에서, 설명은 독스트링에서 파생됩니다.

알려진 제한 사항

의도적으로 명시된 것들입니다 — 이는 프로토타입의 경계이지 미완성 작업이 아닙니다:

• 인메모리 데이터셋 저장소. 서버를 재시작하면 로드된 데이터는 손실된다. 프로토타입에는 허용 가능하지만, 프로덕션에서는 Redis 또는 디스크를 사용한다.

• 인증 없음. 데모 스탠드는 임시 터널 뒤에 있다. 프로덕션에서는 헤더의 API 키와 FastAPI 측 검증이 필요하다.

• 행 필터링 없음. 도구는 데이터셋 전체를 대상으로 동작한다. "2024년 West 지역만" 같은 슬라이스를 만들 수 없다. 이는 데모에서 분명히 드러나는데, 모델은 출력을 맞추는 대신 계산할 수 없는 것을 솔직하게 알려준다.

• 스킬은 다섯 개, 그 이상은 아님. 의식적인 선택이다. 형식적인 열 개보다 실제로 동작하는 다섯 개가 낫다.

• 유닛 테스트 없음 — 오직 selfcheck.py 종단 간 자가 점검과 두 전송 방식에 대한 통합 테스트만 있다.