Peec AI MCP 컴패니언 스킬
Peec AI MCP 서버와 함께 작업하는 AI 에이전트를 위한 오픈소스 가이드입니다. 에이전트에 구애받지 않고, 프로젝트에 구애받지 않으며, CC BY 4.0 라이선스를 따릅니다. 자유롭게 재공유 및 수정하되, 저작자 표시 줄을 유지해 주세요.
살아있는 문서입니다. 이 파일과 모순되는 동작을 발견하거나, 이 문서에서 다루지 않는 새로운 Peec 기능을 발견하면 github.com/rebelytics/peec-ai-mcp에서 이슈 또는 PR을 열어주세요. 워크플로우는
CONTRIBUTING.md를 참조하세요.여기에 있는 동작 관찰은 2026년 4월 기준 최신 정보입니다. Peec는 계속 발전하므로 상황이 바뀔 수 있습니다.
1. Peec AI MCP란 (에이전트를 위한 설명)
Peec AI (peec.ai)는 추적된 프롬프트를 매일 실행하고 응답을 분석하여 AI 검색 엔진(ChatGPT, AI Overviews, Perplexity, Gemini, Grok, Copilot, Claude 등) 전반에서 브랜드가 어떻게 나타나는지 모니터링합니다. MCP 서버는 해당 데이터와 기본 구성을 변경할 수 있는 기능을 모든 MCP 호환 에이전트에 노출합니다.
서버 URL: https://api.peec.ai/mcp
전송 방식: Streamable HTTP
인증: OAuth 2.0 (브라우저 동의, 토큰 유지)
표면 영역은 공식 문서가 제안하는 것보다 더 넓습니다: 27개의 도구(읽기 전용 15개, 쓰기 8개, 파괴적 4개)와 사전 준비된 분석을 묶은 7개의 슬래시 명령 "프롬프트" 가 있습니다. 공식 /mcp/tools 문서 페이지는 13개의 읽기 도구만 나열하고 쓰기/파괴적 표면 영역은 완전히 생략합니다(§7.11 및 §7.25 참조).
핵심 용어 설명
이 스킬 전체에서 사용되는 용어입니다. 각 용어는 Peec의 데이터 모델에서 구체적이고 명확하지 않은 의미를 갖습니다.
- 가시성(Visibility) — AI 응답에 브랜드가 나타나는 빈도입니다.
멘션 수 ÷ 전체 추적된 채팅 수로 계산되며 0–1 비율로 반환됩니다(UI는 0–100으로 표시). §7.3 / §7.37 참조. - 셰어 오브 보이스(SoV) — 추적된 브랜드 목록 내 전체 멘션에서 특정 브랜드의 멘션이 차지하는 비율입니다. 0–1 비율(UI는 0–100으로 표시). "추적된"이 중요합니다. 포지션을 참조하세요.
- 감성(Sentiment) — 0–100 점수로, 중립은 50입니다. 공식:
50 + (sentiment_sum / sentiment_count) × 50. §7.3 참조. - 포지션(Position) — 전체가 아닌 추적된 브랜드 내 평균 순위입니다. 낮을수록 좋습니다. §7.4 참조.
- 자사 브랜드(Own brand) —
list_brands의is_own=true행입니다. 다른 모든 행은 추적된 경쟁사입니다. - 멘션(Mention) — 웹 가져오기(fetch) 유무와 관계없이 브랜드 이름이 AI 응답 텍스트에 나타나는 것입니다.
- 검색(Retrieval) — AI 엔진이 응답하는 동안 하나 이상의 URL을 가져온 것입니다.
get_domain_report및get_url_report에서 집계됩니다. - 인용(Citation) — 모델이 응답에서 명시적으로 참조한 검색된 URL입니다. 모든 인용은 검색이지만, 모든 검색이 인용이 되는 것은 아닙니다.
- 파라메트릭 메모리(Parametric memory) — 모델이 웹 소스를 가져오지 않고 훈련 데이터에서 응답한 것입니다. 채팅 페이로드의
sources: []가 이를 나타냅니다. - 팬아웃(Fanout) — AI 엔진이 검색 전에 사용자 프롬프트를 하위 쿼리로 다시 작성하는 것입니다.
list_search_queries(chat_id=...)를 통해 노출됩니다. - 스크레이퍼 변형(Scraper variant) —
-scraper접미사가 붙은 모델 ID입니다(예:chatgpt-scraper). 실제 소비자 앱을 통해 프롬프트를 재생하여 사용자가 보는 것을 캡처하고, 원시 API 출력을 캡처하지 않습니다. 가시성 모니터링에 선호됩니다. §7.2 참조. - UGC — 사용자 생성 콘텐츠입니다. Reddit, YouTube, 포럼 등을 포함하는
domain_report.classification의 8가지 값 중 하나입니다. §7.30 참조. - 멱등성(Idempotent) — 두 번 실행해도 안전합니다. Peec의 소프트 삭제는 멱등적이지 않습니다. 두 번째 호출은 "찾을 수 없음"을 반환합니다. §7.34 참조.
- 소프트 삭제(Soft-delete) —
list_*에서 엔터티를 제거하고 필터링하지만 서버 측에서는 보존합니다. Peec가 노출하는 유일한 형태입니다. §7.34 참조. - ID 접두사 —
or_(프로젝트),kw_(브랜드 — Peec의 키워드 추적 기원에서 온 레거시 이름),pr_(프롬프트),tp_(주제),tg_(태그),ch_(채팅). 불투명한 네임스페이스 마커이지, 의미적 유형이 아닙니다(kw_는 브랜드이지 키워드가 아닙니다).
1.1 데이터 모델 — 브랜드, 프롬프트, 주제, 태그는 직교적입니다
Peec의 표면 영역 중 가장 오해하기 쉬운 부분입니다. 프롬프트는 브랜드에 "속하지" 않습니다. brand_id 외래 키가 존재하지 않으며, update_prompt는 프롬프트를 브랜드 간에 이동시킬 수 없습니다.
엔터티:
- 프로젝트(Project) (
or_…) — 최상위 컨테이너입니다. 다른 모든 것은 프로젝트에 속합니다. - 브랜드(Brand) (
kw_…) — AI 응답 텍스트에 적용되는 감지 패턴입니다. 필드:name,aliases,regex,domains,is_own. 프롬프트, 주제 또는 태그와의 연결은 없습니다. - 주제(Topic) (
tp_…) — 프롬프트를 그룹화하는 폴더와 같은 것입니다. 프롬프트는 0개 또는 1개의 주제를 가집니다. - 태그(Tag) (
tg_…) — 프롬프트에 첨부된 레이블입니다. 프롬프트는 0개 이상의 태그를 가집니다. - 프롬프트(Prompt) (
pr_…) — 매일 추적되는 질문입니다. 필드:text,country_code,topic_id,tag_ids.brand_id필드가 없습니다. - 채팅(Chat) (
ch_…) — 특정 날짜의 특정 프롬프트에 대한 하나의 AI 엔진 응답입니다. 채팅 텍스트는 모든 브랜드의 감지 패턴에 대해 스캔되어 멘션 수와 브랜드 보고서를 생성합니다.
브랜드 ↔ 프롬프트 관계는 읽기 전용이며 간접적입니다. 프롬프트는 채팅을 생성하고, 채팅은 응답 텍스트를 포함하며, 브랜드 감지는 수집 시 해당 텍스트에 대해 실행됩니다. 프롬프트를 브랜드에 연결하는 쓰기 경로는 없습니다. 브랜드 간에 프롬프트를 "할당"하거나 "이동"하는 것은 범주 오류입니다. 브랜드는 컨테이너가 아니라 감지 패턴입니다.
실제적 의미:
update_prompt는topic_id와tag_ids만 변경합니다.text나 가상의brand_id는 변경하지 않습니다. §7.13 참조.update_brand는 감지 패턴(name,aliases,regex,domains)을 변경합니다. 프롬프트를 참조하는 것은 없습니다.- "어떤 프롬프트가 브랜드 X를 언급했는지"를 알려면
list_chats(brand_id=…)를 실행하고prompt_id열을 검사합니다. create_brand는 기본적으로is_own=false입니다. 항상 경쟁사를 생성합니다. 자사 브랜드 선택은 MCP를 통해 노출되지 않습니다.- 자사 브랜드의 TLD 목록은 분류에 중요합니다.
domains=["example.de"]이지만 회사가example.com도 운영하는 경우, 도메인 보고서는example.com을OWN이 아닌CORPORATE로 분류합니다. §7.10 참조.
빠른 시작 — 3분 안에 첫 번째 보고서
Peec AI 계정(peec.ai)에 최소 하나의 프로젝트가 있고, MCP 호환 클라이언트(아래 예시에서는 Claude Desktop 사용)가 있다고 가정합니다. Peec는 docs.peec.ai/mcp/introduction에서 공식 클라이언트별 설정 지침을 게시합니다. 해당 지침을 따르고 커넥터가 활성화되면 여기로 돌아오세요.
- 연결. 설정 → 커넥터 → 사용자 지정 커넥터 추가 → URL
https://api.peec.ai/mcp→ 저장 → 커넥터 카드에서 "연결" 클릭 → 브라우저에서 인증. 저장 후 "연결"을 클릭하는 단계를 놓치기 쉽습니다. - 확인. 에이전트에게 물어보세요: "내 Peec AI 프로젝트를 나열해 줘." 열 형식 JSON 테이블(§4)에 최소 하나 이상의
or_…프로젝트 ID가 표시되어야 합니다. - 첫 번째 브랜드 보고서 가져오기. 물어보세요: "프로젝트
<id>에 대해 지난 30일간 내 자사 브랜드의 가시성, 멘션, SoV, 감성 및 포지션을 AI 모델별로 세분화하여 보여줘." 에이전트는list_brands(자사 브랜드 찾기is_own=true) →get_brand_report(해당brand_id로 필터링, 차원model_id, 기본 30일 기간)를 체인으로 실행합니다. - 숫자를 보고하기 전에 알아야 할 세 가지 해석 규칙:
- 같은 행에 스케일이 혼합되어 있습니다.
visibility와share_of_voice는 0–1 비율로 반환됩니다(백분율로 변환하려면 100을 곱함).sentiment는 이미 0–100입니다(중립 = 50).position은 1부터 시작하며 낮을수록 좋습니다. 네 가지를 모두 하나의 스케일로 취급하지 마세요. 자세한 내용은 §7.37을 참조하세요. - 포지션은 전체가 아닌 추적된 브랜드 내 순위입니다. 포지션 1.6은 "구성한 경쟁사 목록 내에서 1.6위"를 의미하며, "ChatGPT 전체 응답에서 2위"를 의미하지 않습니다. §7.4.
- 멘션에는 파라메트릭 답변이 포함됩니다. 가시성은 브랜드 이름이 텍스트에 나타나는 모든 응답을 집계하며, 엔진이 단일 URL도 가져오지 않은 답변을 포함합니다. 검색 및 인용은 실제 웹 가져오기만 집계합니다. §7.5.
- 같은 행에 스케일이 혼합되어 있습니다.
- 데이터가 비어 있다고 해서 도구가 고장난 것은 아닙니다. 0을 반환하는 엔진은 일반적으로 요금제에서 비활성화된 것입니다(§7.1). 빈 결과의 다섯 가지 원인이 §7.8에 정리되어 있습니다. "도구가 고장 났다"고 결론 내리기 전에 해당 목록을 확인하세요.
이것이 최소한의 유용한 루프입니다. 전체 기능 맵을 보려면 계속 읽으십시오. §8은 Peec가 공개한 주요 사용 사례를 다루는 일곱 가지 레시피를 모아 놓았습니다.
사전 점검 목록 — 숫자를 보고하기 전에
Peec 수치를 사람에게 제시하기 전에 다음 여덟 가지 항목을 확인하십시오.
- 모든 열에 대해 메트릭 유형이 식별되었습니다. 각 숫자 열을 비율(0–1, 100 곱하기), 점수(0–100, 감성 중립 50), 순위(1+, 낮을수록 좋음), 비율(1.0 초과 가능), 또는 개수(정수)로 분류하십시오. §7.37을 참조하세요. 유형을 지정할 수 없으면 숫자를 표시하지 마십시오.
- 사용자가 기대하는 대로 스케일이 정규화되었습니다. 비율은 백분율로 렌더링합니다(
0.33→33%,0.33%가 아님). 감성은 0–100 그대로 두고 "50 = 중립"을 명시합니다. 포지션은 순위 그대로 두고 "낮을수록 좋음"을 명시합니다. 비율은 그대로 두되, 이상값(retrieval_rate=1.8)은 재작성보다는 설명합니다. §7.3 / §7.37을 참조하세요. - 포지션은 전체 순위가 아니라 추적된 브랜드 내 순위로 읽습니다. 모든 포지션 수치에는 "추적된 경쟁사 중"이라는 한정어가 붙습니다. §7.4를 참조하세요.
- 차원과 필터는 추측이 아닌 도구 스키마에 대해 검증되었습니다.
get_brand_report의 유효한 차원:prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id.brand_id는 필터 전용이며, 절대 차원이 아닙니다. §7.15 / §8.1을 참조하세요. - 열 이름은 실제 응답 페이로드와 일치하는지 확인했습니다. 레시피가 특정 열로 정렬하라고 한다고 해서 해당 열이 존재한다고 가정하지 마십시오. 차원이 지정되지 않은 기본
get_domain_report는retrieved_percentage,retrieval_rate,citation_rate를 반환합니다.retrieval_count를 반환하지 않습니다. §7.39 / §8.10을 참조하세요. - 비활성 엔진은 가시성 0으로 보고하지 않고 플래그를 지정합니다. 브랜드가 Perplexity/Claude/Gemini에서 보이지 않는다고 주장하기 전에
list_models(is_active=true)를 확인하십시오. §7.1 / §7.8을 참조하세요. - 빈 결과는 아무것도 고장 났다고 결론 내리기 전에 §7.8의 다섯 가지 원인 목록에 대해 진단합니다. 소프트 삭제된 브랜드, 비활성 엔진, 파라메트릭 답변, 요금제 제한, 필터 불일치 모두 표면적으로는 동일하게 보입니다.
- 확인되지 않은
kw_…ID는 버그가 아닌 소프트 삭제된 것으로 플래그를 지정합니다. §7.38을 참조하세요.
어느 항목이라도 실패하면 멈추고 보고하기 전에 수정하십시오. 부분적인 통과는 부분적인 신뢰를 낳습니다.
2. 설정
연결 매개변수 (모든 클라이언트 동일):
- URL:
https://api.peec.ai/mcp - 전송 방식: Streamable HTTP
- 인증: OAuth 2.0 (브라우저 동의, 토큰 유지)
- 범위: 읽기 + 쓰기 (공식 문서가 읽기 전용이라고 주장하지만 — §7.11 참조)
클라이언트별 설치 지침은 Peec의 공식 설정 문서인 docs.peec.ai/mcp/introduction를 따르십시오. Peec는 지원되는 클라이언트와 단계별 연결 흐름의 최신 목록을 유지 관리합니다. 이 스킬은 해당 내용이 환경에 따라 다르고 빠르게 구식이 되기 때문에 의도적으로 중복하지 않습니다.
네트워크 샌드박싱: 샌드박스 처리된 에이전트 환경(Cowork, 특정 클라우드 IDE, 기업 프록시)에서 실행 중인 경우 api.peec.ai가 아웃바운드 허용 목록에 있는지 확인하십시오. 차단된 요청은 Peec 버그가 아닌 네트워크 계층 문제임을 알리는 스킬 내 신호 없이 일반 연결 / 403 오류로 표시됩니다.
설정 확인 다음 명령으로 확인하십시오: "내 Peec AI 프로젝트를 나열한 다음, 첫 번째 프로젝트의 추적된 브랜드와 주제를 보여줘." 예상 결과: 두 개의 순차적 도구 호출(list_projects → list_brands + list_topics), 둘 다 각각 최소 하나의 행이 있는 열 형식 JSON을 반환합니다. 에이전트가 Peec 통합이 없다고 말하면 커넥터가 연결되지 않은 것입니다. Peec의 공식 문서를 다시 방문하여 OAuth 동의가 완료되었는지 확인하십시오.
연결하기 전에 사용자가 peec.ai에 Peec AI 계정이 있고 최소한 하나의 프로젝트가 있으며 OAuth에 사용할 동일한 브라우저에 로그인되어 있는지 확인하십시오. 브라우저 세션이 이미 인증된 경우 OAuth는 "조용히 완료"됩니다. 따라서 동의 화면이 표시되지 않는다고 해서 커넥터가 고장난 것은 아닙니다.
3. 27개 도구 한눈에 보기
읽기 전용 (15)
| 도구 | 목적 |
|---|---|
list_projects | 인증된 사용자가 액세스할 수 있는 모든 프로젝트 |
list_brands | 프로젝트의 추적된 브랜드 (자사 + 경쟁사) |
list_topics | 주제 (프롬프트의 폴더 같은 그룹) |
list_prompts | 주제 ID 또는 태그 ID로 필터링 가능한 프롬프트 |
list_tags | 프롬프트에 적용된 교차 레이블 |
list_models | AI 엔진 카탈로그 (§7 참조: is_active 필터는 중요합니다) |
list_chats | 개별 AI 응답, 브랜드/프롬프트/모델로 필터링 가능 |
get_chat | 전체 채팅 페이로드 (메시지, 소스, 제품, 언급된 브랜드) |
list_search_queries | AI 엔진이 팬아웃한 하위 쿼리 |
list_shopping_queries | 쇼핑 모드 쿼리 + 제품 목록 |
get_brand_report | 가시성, SoV, 감성, 포지션 집계 |
get_domain_report | 소스 도메인 검색 + 인용 비율 |
get_url_report | 소스 URL 검색 + 인용 비율 + 페이지 분류 |
get_url_content | 인덱싱된 모든 소스 URL의 스크래핑된 마크다운 |
get_actions | 기회 점수가 매겨진 추천 (2026년 4월 기준 고장 — §7.12 참조) |
쓰기 / 변경 (8)
| 도구 | 목적 |
|---|---|
create_brand | 새 경쟁사 추적 (domains, aliases, regex 허용) |
update_brand | 브랜드 이름 변경 / 조정 (백그라운드 재계산 트리거 — §7.19 참조) |
create_topic | 주제 추가 (선택적 country_code, name.maxLength=64) |
update_topic | 주제 이름 변경 |
create_prompt | 추적된 프롬프트 추가 (country_code 필수, text.maxLength=200) |
update_prompt | topic_id / tag_ids 변경 (text는 변경 불가능 — §7.13 참조) |
create_tag | 22가지 색상 중 하나로 태그 추가 (아래 참조) |
update_tag | 태그 이름 변경 또는 색상 변경 |
태그 색상 열거형 (22개 값): gray, red, orange, yellow, lime, green, cyan, blue, purple, fuchsia, pink, emerald, amber, violet, indigo, teal, sky, rose, slate, zinc, neutral, stone. 도구의 JSON 스키마가 Peec가 나중에 색상을 추가할 경우 권위 있는 소스입니다. 이 목록은 2026년 4월 기준 스키마와 일치합니다.
파괴적 (4)
| 도구 | 목적 |
|---|---|
delete_brand | 브랜드 소프트 삭제 |
delete_topic | 주제 소프트 삭제 (프롬프트 분리, 계단식 삭제 안 함) |
delete_prompt | 프롬프트 소프트 삭제 (채팅으로 계단식 삭제) |
delete_tag | 태그 소프트 삭제 (프롬프트에서 태그 분리, 계단식 삭제 안 함) |
4. 상호작용 규칙
4.1 프롬프트 동작 — 기본값, 유추, 수정
에이전트는 사용자가 명시적으로 요청하지 않는 한 도구를 호출하기 전에 추측해서는 안 됩니다. 사용자가 "브랜드 보여줘"라고 말하는 것은 list_brands 호출을 의미하지만, "데이터 가져와"는 너무 모호합니다. 명확한 질문을 하거나 사용자에게 명확한 지침을 요청하십시오.
기본 동작:
- 기간:
get_*_report에 대해 특정 기간이 제공되지 않으면 지난 30일을 가정하고 이를 사용자에게 명시하십시오. "지난 주"는date_from/date_to를 설정합니다. - 차원: 요청하지 않는 한 보고서를 단일 차원(집계)으로 유지하십시오. "모델별로 세분화"는
dimension=model_id를 의미합니다. - 필터: 사용자가 "브랜드 X"를 언급하면
list_brands에서brand_id를 조회하고 보고서에 필터로 적용하십시오. - 자사 브랜드: 사용자가 "내 브랜드" 또는 "자사"를 언급하면
is_own=true로 필터링하십시오. - 새 엔터티: 사용자가 "추적해" 또는 "감시해"를 말하면
create_prompt또는create_brand가 필요함을 의미합니다. 먼저 컨텍스트를 확인하십시오.
출력 형식 기본 설정:
- 열 형식 JSON을 사용하십시오. 행 수가 10개를 초과하면 헤더 + 처음 5개 행 + "...하고 N개 더 있음"을 표시하십시오. 에이전트가 명시적으로 요청하지 않는 한 행 번호는 생략하십시오.
- 모든 ID는 축약된 형태(예:
or_…)로 표시하십시오.전체 36자 UUID 문자열을 표시하지 마십시오. 사용자는 전체 ID가 필요하다고 말할 때까지 전체 ID가 필요하지 않습니다. - 표 형식 데이터를 나열할 때는 설명 텍스트가 포함된 불릿 포인트 대신 단일 JSON 블록을 사용하십시오. 에이전트가 하나의
list_*호출을 수행한 경우, 모든 결과 행을 단일 코드 블록으로 표시하십시오. - 표시할 관련 데이터가 없으면 "해당 기준과 일치하는 데이터가 없습니다"라는 간단한 메시지를 반환하고, 이유를 추측하려고 시도하기보다는 §7의 디버깅 팁을 참조하도록 하십시오.
테이블에 관한 특별 참고:
아니요, 정말로요 — 열 형식 JSON을 사용하십시오. 마크다운 테이블은 필드가 추가됨에 따라 빠르게 깨지며, 열 너비가 일치하지 않으면 읽을 수 없게 됩니다. list_brands의 11개 필드는 마크다운 테이블에 적합하지 않습니다. 열 형식 JSON은 너비에 관계없이 가독성을 유지합니다.
에이전트는 사용자가 복사하도록 요청하지 않는 한 ID를 복사 가능한 형식으로 절대 제공해서는 안 됩니다.
4.2 여러 도구 호출 — 순서 및 동시성
에이전트는 Peec에 대한 읽기 호출을 자유롭게 병렬화할 수 있습니다. MCP 서버는 동시성을 처리합니다. 쓰기 호출은 가능한 경우 순차적으로 실행해야 합니다(동시 생성이 데이터 모델에 미치는 영향은 아직 문서화되지 않음).
일반적인 체인:
list_projects→ 사용자가 대상 선택list_brands+list_topics(병렬) → 컨텍스트 확인get_brand_report(선택한 브랜드, 차원, 날짜 범위)get_domain_report또는get_url_report(선택한 브랜드, 심층 분석 필요 시)get_chat또는list_chats(개별 응답 검사 필요 시)
필요한 경우에만 최상위 3에서 이동하십시오. 모든 상호작용이 깊은 드릴다운을 필요로 하는 것은 아닙니다.
4.3 오류 처리
에이전트는 Peec MCP 서버 오류를 사용자에게 있는 그대로 노출해서는 안 됩니다. 대신:
- 알 수 없는 ID ("brand not found"):
list_brands를 확인하십시오. 소프트 삭제된 브랜드는list_brands에 나타나지 않습니다. §7.38을 참조하십시오. - 알 수 없는 프로젝트 ID:
list_projects를 확인하십시오. 사용자는 ID를 잘못 입력했을 수 있습니다. - 도구 호출 시간 초과: Peec 보고서 생성은 특히 여러 엔진에서 데이터를 집계할 때 최대 10초가 소요될 수 있습니다. 시간 초과는 일반적으로 일시적입니다. 한 번 다시 시도하십시오.
- 인증 오류: "OAuth 세션이 만료되었습니다. Peec AI 설정에서 커넥터를 다시 연결하십시오."라고 말하십시오. 기술적 세부 사항을 제공하지 마십시오.
- 네트워크 오류:
api.peec.ai가 새 환경의 아웃바운드 허용 목록에 있는지 확인하십시오. 에이전트가 기술적 세부 사항을 요청하지 않는 한 "Peec에 연결할 수 없습니다" 외에는 진단하지 마십시오.
절대 에이전트는 사용자에게 MCP 오류 코드, HTTP 상태 또는 내부 Peec 오류 메시지를 표시해서는 안 됩니다. "문제가 발생했습니다"라고 말하고 인간이 읽을 수 있는 다음 단계를 제공하십시오.
5. 오해의 소지가 있는 것들
5.1 모든 것이 "keyword"는 아닙니다
kw_ 접두사는 Peec가 키워드 추적 도구로 시작했기 때문에 브랜드 ID에 사용됩니다. kw_ ID는 브랜지이지 키워드가 아닙니다. create_brand는 name, aliases, regex, domains를 허용하며, AI 응답 텍스트에서 감지하는 패턴입니다. 에이전트는 kw_가 "keyword"라고 가정하는 것을 피하고 대신 브랜드 컨텍스트를 사용해야 합니다.
5.2 프롬프트는 브랜드에 속하지 않습니다
Peec의 데이터 모델에서 가장 오해하기 쉬운 측면입니다. 프롬프트는 브랜드 ID와 함께 저장되지 않습니다. create_prompt는 brand_id를 허용하지 않습니다. 브랜드와 프롬프트 간의 관계는 전적으로 프롬프트 → 채팅 → 브랜드 감지 연결을 통해 간접적입니다. 에이전트는 사용자가 "X 브랜드에 프롬프트 추가"를 요청할 때 추측해서는 안 됩니다. 대신 먼저 list_prompts를 확인하고, 사용자에게 브랜드가 아닌 주제 및 태그 컨텍스트를 제공하도록 요청하십시오.
5.3 update_prompt는 텍스트를 변경할 수 없습니다
update_prompt는 topic_id 및 tag_ids만 허용합니다. 프롬프트 텍스트는 업데이트할 수 없습니다. 프롬프트 텍스트를 변경하려면 삭제하고 다시 만드십시오.
5.4 가시성 ≠ 인용
에이전트는 특히 경영진 보고 맥락에서 이러한 두 가지를 혼동하는 경우가 많습니다. 가시성은 AI 응답 텍스트에 브랜드가 나타나는 것을 측정합니다. 인용은 모델이 명시적으로 URL에 연결하는 것을 측정합니다. 가시성은 브랜드 존재(파라메트릭 포함)를 측정하는 반면, 인용은 참조 소스를 측정합니다. 둘 다 유효한 메트릭이지만 동일하지는 않습니다.
5.5 get_actions는 고장 났습니다
2026년 4월 기준으로 get_actions는 Error: Internal server error를 반환합니다. 이에 대한 지원 티켓이 있습니다. 에이전트는 이 도구를 호출하지 말아야 합니다. 사용자가 물으면 사용할 수 없다고 말하십시오.
6. 프롬프트
에이전트 프롬프트/슬래시 명령은 에이전트가 관련 도구를 선택하고 체이닝하도록 안내하는 MCP "프롬프트" 리소스를 통해 사용 가능합니다.
사용 가능한 프롬프트 (7)
| 프롬프트 이름 | 목적 | 필수 인수 |
|---|---|---|
brand_health_assessment | 선택적 차원으로 브랜드에 대한 포괄적인 성과 검토를 실행합니다. | project_id, brand_id |
competitive_landscape | 브랜드 간 비교 in a project | project_id |
sentiment_analysis | 심층 감성 브레이크다운 | project_id, brand_id |
domain_performance | 도메인 수준에서 검색 및 인용 분석 | project_id, brand_id |
share_of_voice_trend | 시간 경과에 따른 SoV 트렌드 | project_id, brand_id |
emerging_threats | 새롭게 등장하는 경쟁사 또는 주제 식별 | project_id |
weekly_briefing | 모든 프로젝트 데이터에 대한 상위 수준 요약 | project_id |
사용법: 이러한 프롬프트는 사용자 입력을 구성하는 방법에 대한 권장 사항을 제공합니다. 에이전트가 단일 한정 질문보다는 여러 도구 호출이 필요한 체인을 실행하도록 안내할 때 가장 유용합니다.
커스텀 프롬프트: 이러한 프롬프트는 Peec에 의해 유지 관리됩니다. 에이전트는 프롬프트에 추가 매개변수를 자유롭게 추가할 수 있지만, 필수 인수를 제거해서는 안 됩니다.
7. 상세 참조
7.1 list_models 및 is_active
is_active 플래그는 중요합니다. 비활성 엔진은 데이터를 반환하지 않습니다. 에이전트는 다음을 수행해야 합니다:
is_active=true로 만list_models를 호출하거나, 전체 목록을 가져오고 활성 상태로 필터링하십시오.- 브랜드가 특정 엔진에서 0 가시성을 보이면
this engine is inactive in your plan → no data라고 말하십시오. model_id가 활성 상태가 아닐 때 음수 가시성 또는 경고를 추측하지 마십시오.
list_models는 계정의 표시 이름, 모델 ID 접미사(-scraper 등), 상태를 반환합니다.
7.2 스크레이퍼 모델
-scraper가 포함된 모델 ID(예: chatgpt-scraper)는 실제 소비자 인터페이스를 통해 프롬프트를 재생합니다. 이는 가시성 추적을 위한 선호되는 데이터 소스입니다. 스크레이퍼가 아닌 변형(있는 경우)은 API 출력을 반영하며, 이는 사용자 경험과 크게 다를 수 있습니다.
7.3 get_brand_report — 필드 설명
| 필드 | 유형 | 범위 | 참고 |
|---|---|---|---|
visibility | 비율 | 0–1 | UI 표시: 0–100%. 100 곱하기 |
share_of_voice | 비율 | 0–1 | UI 표시: 0–100%. 100 곱하기 |
sentiment | 점수 | 0–100 | 중립 = 50. 공식: 50 + (합계 / 개수) × 50 |
position | 순위 | 1+ | 낮을수록 좋음. 전체가 아닌 추적된 브랜드 내 순위 |
mention_count | 개수 | 0+ | 원시 횟수. 가시성을 계산하는 데 사용됨 |
retrieval_count | 개수 | 0+ | URL 가져오기 횟수. 가시성과 다름 |
citation_count | 개수 | 0+ | 명시적 인용 횟수. 검색의 하위 집합 |
total_mentions | 개수 | 0+ | 모든 브랜드의 총 멘션. SoV 계산에 사용됨 |
브랜드 보고서의 차원은 prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id입니다.
7.4 포지션은 "추적된 브랜드 내"를 의미합니다
이것은 가장 오해하기 쉬운 필드입니다. position: 1.6은 "AI 검색 엔진에서 1.6위"를 의미하지 않습니다. "추적된 브랜드 목록에서 평균 1.6위"를 의미합니다. 경쟁사가 3개만 있는 경우 포지션 범위는 1–3입니다. 에이전트는 이 한정어 없이 포지션을 보고해서는 안 됩니다.
7.5 멘션은 검색과 다릅니다
멘션은 AI 응답 텍스트에 브랜드 이름이 나타나는 것입니다. 검색은 AI 엔진이 하나 이상의 URL을 가져온 것입니다. 브랜드 이름은 URL을 가져오지 않고 나타날 수 있습니다(파라메트릭 메모리). 피보고서가 파라메트릭 응답을 제외해야 하는 경우 sources: []가 있는 채팅을 필터링하십시오.
7.6 인용
인용은 모델이 응답에서 명시적으로 참조하는 검색된 URL입니다. 모든 인용은 검색이지만, 모든 검색이 인용되는 것은 아닙니다. get_domain_report 및 get_url_report는 인용과 비인용 검색을 별도로 집계합니다.
7.7 get_url_content
get_url_content(url=…)는 Peec가 인덱싱한 모든 URL의 전체 텍스트를 마크다운으로 반환합니다. URL이 인덱싱되지 않은 경우 오류 메시지가 반환됩니다. 각 list_urls 응답은 지원되는 URL 목록을 반환하지 않습니다. 이 도구는 get_url_report의 URL과 함께 사용됩니다.
7.8 빈 결과 — 다섯 가지 원인
| 원인 | 진단 | 해결 방법 |
|---|---|---|
| 소프트 삭제된 브랜드 | list_brands에 ID가 없음 | 브랜드가 삭제되지 않았는지 확인 |
| 비활성 엔진 | list_models에서 is_active=false | 활성 엔진으로 필터링 |
| 파라메트릭만 | 모든 채팅에 sources: [] 있음 | 검색 가능한 데이터 없음, 정상 |
| 요금제 제한 | 특정 엔진이 전혀 데이터 없음 | Peec 지원에 문의 |
| 필터 불일치 | date_from이 date_to보다 나중 | 날짜 수정 |
에이전트는 "데이터가 없을 수 있습니다. 원인을 확인하겠습니다"로 시작한 다음 이 표를 확인해야 합니다.
7.9 태그 색상
create_tag 및 update_tag의 color 필드는 22개의 문자열 값으로 제한됩니다. 전체 목록은 §3의 태그 생성 표를 참조하십시오. 잘못된 색상 값은 도구에서 오류를 반환합니다.
7.10 도메인 분류 — OWN 대 CORPORATE
get_domain_report 및 get_url_report는 도메인을 분류합니다. OWN은 자사 브랜드의 domains 필드에 나열된 도메인에만 적용됩니다. 자사 브랜드가 예를 들어 example.com을 나열하지만 회사도 example.de를 소유하는 경우 후자는 CORPORATE(또는 다른)로 분류되지만 OWN은 아닙니다.
7.11 공식 문서는 쓰기 표면 영역을 생략합니다
Peec의 /mcp/tools 페이지는 읽기 전용 도구만 나열합니다. 쓰기 도구 및 파괴적 도구는 이 스킬에만 문서화되어 있습니다. 에이전트는 공식 문서가 제안하는 것보다 더 넓은 표면 영역을 인식해야 합니다.
7.12 get_actions — 고장남
get_actions는 내부 서버 오류를 반환합니다. 호출하지 마십시오. 사용자가 물으면 "일시적으로 사용할 수 없음"이라고 말하십시오.
7.13 update_prompt — 텍스트를 변경할 수 없습니다
update_prompt는 topic_id 및 tag_ids만 허용합니다. 텍스트를 변경해야 하는 경우 프롬프트를 삭제하고 다시 만드십시오.
7.14 create_prompt — text.maxLength=200 및 country_code 필수
프롬프트 텍스트는 최대 200자입니다. 그 이상은 오류를 반환합니다. country_code(ISO 3166-1 alpha-2)는 필수입니다.
7.15 get_brand_report — 차원은 model_id, prompt_id 등입니다.
brand_id는 브랜드 보고서의 차원이 아닙니다. 보고서를 브랜드별로 세분화할 수 없습니다(항상 단일 브랜드에 대해 수행됩니다). 유효한 차원은 §7.3을 참조하십시오.
7.16 list_search_queries — 팬아웃 이해
AI 엔진은 단일 프롬프트를 여러 검색 쿼리로 변환하는 경우가 많습니다. list_search_queries(chat_id=…)는 이러한 팬아웃을 노출합니다. 예를 들어, "스마트폰 추천" 프롬프트는 "최고의 스마트폰 2025", "iPhone 17 리뷰", "Galaxy S26 배터리" 등으로 팬아웃될 수 있습니다. 각 팬아웃은 고유한 검색 결과를 가질 수 있습니다.
7.17 list_shopping_queries — 제품 목록
list_shopping_queries(chat_id=…)는 엔진이 구매 의도가 있는 것으로 분류한 프롬프트에 대한 제품 목록을 반환합니다. 여기에는 제품 이름, 가격 및 URL이 포함됩니다.
7.18 create_brand — is_own=false 기본값
create_brand는 항상 추적된 경쟁사를 생성합니다. 자사 브랜드 선택은 MCP를 통해 노출되지 않습니다. 사용자가 "내 브랜드 추가"를 요청하는 경우, 아마도 경쟁사가 아닌 자사 브랜드를 추가하려는 것일 수 있습니다. create_brand가 효과가 없는 이유를 설명하고 Peec UI에서 자사 브랜드를 설정하도록 안내하십시오.
7.19 update_brand — 백그라운드 재계산
브랜드의 감지 패턴(name, aliases, regex, domains)을 수정하면 Peec가 과거 채팅을 다시 스캔하여 새로운 패턴과 일치시킵니다. 재계산은 비동기식이며 완료하는 데 시간이 걸립니다. 재계산이 완료되기 전에 get_brand_report를 호출하면 부분적인 데이터를 반환할 수 있습니다. "1~5분 후에 다시 확인하십시오"라고 말하십시오.
7.20 태그는 여러 프롬프트에 적용될 수 있습니다
태그는 프롬프트에 대한 교차 레이블입니다. 여러 태그를 단일 프롬프트에 적용할 수 있으며, 단일 태그를 여러 프롬프트에 적용할 수 있습니다.
7.21 주제에는 선택적 country_code가 있습니다
주제를 생성할 때 country_code를 지정할 수 있습니다(ISO 3166-1 alpha-2). 주제별로 그룹화된 프롬프트의 기본 국가를 설정합니다.
7.22 delete_brand — 소프트 삭제, 멱등적이지 않음
delete_brand는 소프트 삭제입니다. list_brands에서 브랜드를 제거하지만 서버 측에서는 보존합니다. 두 번 호출하면 "찾을 수 없음" 오류가 발생합니다.
7.23 delete_topic — 계단식 삭제 없음
주제를 삭제해도 해당 프롬프트는 삭제되지 않습니다. 프롬프트는 주제가 없는 상태로 유지됩니다.
7.24 delete_prompt — 계단식 삭제
프롬프트를 삭제하면 해당 채팅도 삭제됩니다. 이는 소프트 삭제입니다.
7.25 delete_tag — 계단식 삭제 없음
태그를 삭제해도 프롬프트에서 태그가 제거되지만 프롬프트는 삭제되지 않습니다.
7.26 ID 접두사
| 접두사 | 엔터티 유형 | 예시 |
|---|---|---|
or_ | 프로젝트 | or_abc123 |
kw_ | 브랜드 | kw_def456 |
pr_ | 프롬프트 | pr_ghi789 |
tp_ | 주제 | tp_jkl012 |
tg_ | 태그 | tg_mno345 |
ch_ | 채팅 | ch_pqr678 |
7.27 list_chats — 필터
list_chats는 brand_id, prompt_id, model_id, date_from, date_to로 필터링할 수 있습니다. brand_id로 필터링하면 해당 브랜드가 언급된 채팅만 반환합니다.
7.28 get_chat — 전체 페이로드
get_chat(chat_id=…)는 전체 채팅 페이로드를 반환합니다: 메시지, 소스, 제품, 언급된 브랜드. 프롬프트에 대한 응답을 검사할 때 유용합니다.
7.29 list_urls — 사용 가능한 매개변수 없음
이 도구는 현재 매개변수를 허용하지 않습니다. 인덱싱된 모든 URL을 반환합니다(일반적으로 0개). get_url_report에서 URL을 가져오는 데 유용합니다.
7.30 도메인 분류
get_domain_report 및 get_url_report classification 필드는 다음 값 중 하나일 수 있습니다:
OWN— 자사 브랜드의 도메인CORPORATE— 회사 소유이지만OWN으로 등록되지 않은 도메인NEWS— 뉴스 사이트SOCIAL— 소셜 미디어 플랫폼UGC— 사용자 생성 콘텐츠(Reddit, YouTube, 포럼)REVIEW— 리뷰 사이트SHOPPING— 전자상거래 사이트OTHER— 기타
7.31 get_url_report — 페이지 분류
get_url_report는 domain_classification 및 개별 page_classification을 반환합니다. 페이지 분류는 도메인 분류와 다를 수 있습니다.
7.32 비율 필드 — retrieval_rate, citation_rate
get_domain_report 및 get_url_report는 검색률 및 인용률 필드를 반환합니다. 이는 비율(단위 없음)입니다. 검색률 1.8은 "응답당 평균 1.8개 URL 가져옴"을 의미합니다. 백분율이 아닙니다.
7.33 retrieved_percentage — 백분율
retrieved_percentage는 실제 백분율(0–100)입니다. 검색된 응답의 백분율을 나타냅니다. 100 곱할 필요가 없습니다.
7.34 소프트 삭제는 멱등적이지 않습니다
Peec의 소프트 삭제(delete_*)는 멱등적이지 않습니다. 엔터티가 이미 삭제된 경우 두 번째 호출은 오류를 반환합니다. 에이전트는 소프트 삭제 후 동일한 delete_*를 다시 호출해서는 안 됩니다.
7.35 update_brand — 재계산 트리거
update_brand 호출은 브랜드의 감지 패턴을 업데이트합니다. Peec는 과거 채팅을 새로운 패턴과 일치시키기 위해 백그라운드 재계산을 트리거합니다. 재계산은 비동기식입니다.
7.36 get_actions — 알려진 문제
get_actions는 내부 서버 오류를 반환합니다. 이에 대한 지원 티켓이 있습니다. 에이전트는 이 도구를 호출하지 말아야 합니다.
7.37 스케일 요약
| 메트릭 | 유형 | 범위 | 표시 |
|---|---|---|---|
| 가시성 | 비율 | 0–1 | 백분율로 변환 |
| 셰어 오브 보이스 | 비율 | 0–1 | 백분율로 변환 |
| 감성 | 점수 | 0–100 | 그대로 유지, 중립 = 50 명시 |
| 포지션 | 순위 | 1+ | 그대로 유지, "낮을수록 좋음" 명시 |
| 멘션 수 | 개수 | 0+ | 정수 |
| 검색 수 | 개수 | 0+ | 정수 |
| 인용 수 | 개수 | 0+ | 정수 |
| 검색률 | 비율 | 0+ | 그대로 유지, 이상값 설명 |
| 인용률 | 비율 | 0+ | 그대로 유지, 이상값 설명 |
| 검색된 비율 | 백분율 | 0–100 | 그대로 유지, 이미 % |
7.38 확인되지 않은 kw_… ID
에이전트가 브랜드 ID를 조회할 수 없으면(예: list_brands에 없음) 소프트 삭제되었거나 존재하지 않는 것입니다. "브랜드가 더 이상 추적되지 않습니다(소프트 삭제됨)"라고 말하십시오. 도구 오류로 보고하지 마십시오.
7.39 차원이 지정되지 않은 보고서 — get_domain_report
차원 없이 get_domain_report를 호출하면 행당 집계된 메트릭이 반환됩니다. 차원을 추가하면(예: dimension=model_id) 행이 차원당 하나씩 반환됩니다. 열 이름은 차원에 따라 변경될 수 있습니다.
8. 레시피
이 섹션은 에이전트가 Peec AI의 주요 사용 사례를 다루기 위해 도구를 체이닝하는 방법을 설명합니다. 이는 엄격한 스크립트가 아닌 패턴입니다. 에이전트는 사용자 의도에 적응해야 합니다.
8.1 브랜드 상태 평가
목적: 단일 브랜드의 성과를 모든 차원에서 이해합니다.
# 의사 코드 — 정확한 도구 호출이 아닌 패턴을 보여줍니다
# 단계 1: 프로젝트 확인
project = list_projects()[0]["id"] # 또는 사용자 선택
# 단계 2: 브랜드 확인
brands = list_brands(project_id=project)
own_brand = [b for b in brands if b["is_own"]][0]
# 단계 3: 집계 보고서 가져오기 (모델별 차원화)
report = get_brand_report(
project_id=project,
brand_id=own_brand["id"],
dimension="model_id",
date_from="2026-03-01",
date_to="2026-03-31"
)
# 단계 4: 도메인 보고서 추가 (심층 분석)
domain_report = get_domain_report(
project_id=project,
brand_id=own_brand["id"],
date_from="2026-03-01",
date_to="2026-03-31"
)
# 단계 5: 결과 표시
출력 형식: 가시성, SoV, 감성, 포지션을 포함한 표. 각 엔진에 대한 행. 각 메트릭 유형을 설명하는 각주.
8.2 경쟁 환경
목적: 프로젝트 내 모든 브랜드 비교.
# 단계 1: 모든 브랜드 가져오기
brands = list_brands(project_id=project)
# 단계 2: 각 브랜드에 대한 집계 보고서
reports = []
for brand in brands:
report = get_brand_report(project_id=project, brand_id=brand["id"])
reports.append(report)
# 단계 3: SoV로 정렬하고 표시
참고: 이는 비용이 많이 드는 작업일 수 있습니다(브랜드당 하나의 API 호출). 브랜드가 10개를 초과하면 사용자에게 확인하십시오.
8.3 심층 감성 분석
# 단계 1: 브랜드에 대한 채팅 가져오기
chats = list_chats(project_id=project, brand_id=brand_id, date_from=..., date_to=...)
# 단계 2: 각 채팅에 대한 감성 분석
for chat in chats:
full = get_chat(chat_id=chat["id"])
# 감성 점수는 get_brand_report에 있습니다 — 여기서는 원시 텍스트 사용 가능
# 단계 3: 트렌드 제시
이 레시피는 원시 응답 텍스트가 필요한 경우에 적합합니다. 대부분의 경우 get_brand_report의 집계 감성으로 충분합니다.
8.4 도메인 성과
# 단계 1: 브랜드에 대한 도메인 보고서
domain_report = get_domain_report(project_id=project, brand_id=brand_id)
# 단계 2: 도메인 분류로 그룹화
classifications = {}
for row in domain_report:
c = row["classification"]
if c not in classifications:
classifications[c] = []
classifications[c].append(row)
# 단계 3: 분류별로 표시
8.5 SoV 트렌드
# 단계 1: 일별 SoV 가져오기
report = get_brand_report(
project_id=project,
brand_id=brand_id,
dimension="date",
date_from=...,
date_to=...
)
# 단계 2: 시간 경과에 따른 SoV 표시
8.6 신규 위협 식별
# 단계 1: 모든 브랜드의 현재 SoV 가져오기
brands = list_brands(project_id=project)
current_sov = {}
for brand in brands:
report = get_brand_report(project_id=project, brand_id=brand["id"])
current_sov[brand["name"]] = report[0]["share_of_voice"]
# 단계 2: 이전 기간과 비교 (date_from/date_to 조정)
# 단계 3: 가장 큰 증가분을 보이는 브랜드 식별
8.7 주간 브리핑
# 단계 1: 모든 활성 프로젝트 가져오기
projects = list_projects()
# 단계 2: 각 프로젝트에 대해 모든 브랜드 가져오기
for project in projects:
brands = list_brands(project_id=project["id"])
# 단계 3: 각 브랜드에 대한 집계 보고서
for brand in brands:
report = get_brand_report(project_id=project["id"], brand_id=brand["id"])
# 단계 4: 상위 수준 요약 표시
9. 라이선스
CC BY 4.0 — 자유롭게 공유 및 수정하되, 저작자 표시를 유지하고 원본 저장소를 연결하십시오. 기여는 동일한 라이선스에 따라 이루어집니다. 행복한 브랜드 추적 되세요!