AdsAgent Tri-Channel 플러그인

AdsAgent tri-channel 호스티드 MCP(Meta, Google Ads, TikTok)를 위한 공개 Claude 플러그인 + 스킬 팩입니다.

배포 분할 (중요):

공식 GitHub 저장소: github.com/adsagents/adsagent-ai-skills

웹사이트: adsagent.md 공식 링크 허브: adsagent.md/connect 스킬 팩 랜딩 페이지: adsagent.md/skills 지원: support@adsagent.md

현재 계약 버전: 0.7.64. 플러그인 슬러그는 adsagent입니다 (마켓플레이스 키 adsagent). 새로운 Meta 연결은 기본적으로 v2 제품 프로필을 사용합니다. 세 개의 호스티드 엔드포인트는 지원되는 레거시 initialize 클라이언트를 유지하면서 최신 MCP 2026-07-28 상태 비저장 검색을 협상합니다.

버전 기록은 CHANGELOG.md에 있습니다.

로컬 헬퍼 scripts/update_reminder.py는 엄격한 시맨틱 버전을 비교하고 $XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json (또는 ~/.cache/...)에 제한된 버전/타임스탬프 상태만 저장합니다. 캐시 실패는 MCP 작업을 차단하지 않습니다.

이것의 용도

• 공개 Claude 플러그인 마켓플레이스 패키지: 행동 스킬 + .mcp.json을 통한 호스티드 MCP URL.

• Claude Code, Cursor, Codex 및 기타 MCP 인식 클라이언트를 위한 행동 가이드.

• 에이전트에게 재시도, 대기, 중지 시점을 알려주는 안정성 및 안전 계층.

• AdsAgent 사용자 온보딩 및 에이전트 행동 안내를 위한 버전 관리된 GitHub 배포.

• AdsAgent를 원시 데이터베이스처럼 스캔해서는 안 되는 AI 에이전트를 위한 데이터 최소화 계약.

Related MCP server: Meta Marketing API MCP Server

이것이 아닌 것

• Anthropic Connectors Directory MCP 목록이 아닙니다 (호스티드 서버에 별도 등록됨).

• 완전한 MCP 도구 참조가 아닙니다.

• SDK가 아닙니다.

• 로컬 전송 릴레이가 아닙니다.

• AdsAgent 백엔드 경로, 스키마, 데이터베이스 테이블 또는 내부 진단 정보 공개가 아닙니다.

Claude Code 플러그인 설치의 경우 OAuth MCP 설정은 이 저장소의 .mcp.json에서 제공됩니다. 플러그인 지원이 없는 클라이언트의 경우 AdsAgent 대시보드 설치 프롬프트가 수동 대체 수단으로 남아 있습니다:

AdsAgent dashboard -> Settings -> MCP Access -> Copy install prompt

Claude 플러그인 번들을 설치하지 않는 경우에만 복사된 프롬프트를 사용하십시오. 이 저장소는 MCP 연결이 설정된 후의 에이전트 행동을 가르칩니다.

포함된 스킬

점진적 공개

에이전트 클라이언트는 검색을 위해 모든 스킬 설명을 로드하지만, 선택된 SKILL.md 본문만 로드해야 합니다. 각 진입점은 의도적으로 작으며, 선택된 워크플로가 해당 세부 정보를 필요로 할 때만 읽히는 로컬 참조 파일에 연결됩니다.

docs/ 아래의 파일은 사람을 위한 제품 및 운영자 문서입니다. 이는 자동 에이전트 컨텍스트가 아니며 스킬 참조 탐색의 일부가 아닙니다. 에이전트 행동 계약은 skills/ 아래에 있으며 선택된 SKILL.md에서 접근됩니다.

에이전트 출력 계약

AdsAgent를 사용하는 에이전트는 기본적으로 Markdown으로 응답해야 합니다:

## Answer
One-sentence answer.

## Scope
- Date:
- Entity:
- Grouping:
- Attribution / channel:

## Results
| Metric | Value |
| --- | ---: |

## Notes
- Data freshness:
- Limits or missing fields:
- Next safe action:

JSON, CSV, 숨겨진 진단 정보, 원시 행 또는 반환된 모든 필드를 채팅에 덤프하지 마십시오. 응답을 운영자용 테이블과 짧은 글머리 기호로 정리하십시오. 법의학적 원시 검사가 필요한 경우, 원시 행을 에이전트 응답으로 만드는 대신 운영자 인계를 생성하십시오.

반-블랙박스 정책

이 저장소는 의도적으로 결과와 에이전트 행동을 문서화하며, 완전한 내부 인터페이스는 문서화하지 않습니다. 에이전트는 다음을 수행해야 합니다:

• 연결 후 라이브 AdsAgent MCP 가이드를 읽습니다.

• 인증된 MCP 세션을 통해 사용 가능한 도구를 사용합니다.

• 숨겨진 페이로드 필드를 추측하지 않습니다.

• 거부된 요청을 조사하지 않습니다.

• 운영자 검토 응답에서 중지하고 AdsAgent 운영자에게 내부 진단 정보를 검사하도록 요청합니다.

• 호출하기 전에 가장 작은 안전한 데이터 계획을 사용합니다.

• 원시 행보다 그룹화된 요약과 정리된 분석을 선호합니다.

외부 에이전트 계약은 다음과 같습니다: 명확한 질문을 하고, 제한을 존중하며, 쓰기 전에 확인하고, 대시보드 제공 온보딩을 사용하십시오.

공식 출처 및 권리

이 저장소에는 클라이언트가 읽을 수 있는 행동 팩만 포함되어 있습니다. AdsAgent 서버 소스, 자격 증명, 스키마, 라우팅 로직 및 운영 진단 정보는 여기에 배포되지 않습니다.

이 패키지는 독점적이며 모든 권리는 adsagents LLC에 있습니다. 공개 GitHub 호스팅을 통해 사람들은 GitHub 서비스 약관에 따라 저장소를 보고 포크할 수 있지만, 포크 또는 로컬 복사본은 LICENSE.md의 제한된 Anthropic Claude 플러그인 디렉토리 미러링 권한을 제외한 추가 지적 재산권 라이선스를 부여하지 않습니다. 수정된 버전을 재배포, 미러링, 판매, 서브라이선스, 게시, 파생 저작물 생성, 팩에서 경쟁 제품 훈련 또는 포크를 공식 버전으로 대표하는 것은 허용되지 않습니다. LICENSE.md 및 NOTICE.md를 참조하십시오.

예제 프롬프트

Use AdsAgent to list my connected Meta products, Google Ads customers, or TikTok advertisers, then ask which scope's today data I want to inspect.

For Google Ads, inspect agent_method_profile, pick an enabled non-manager customer, and use one cached insights_query_consistent request when the profile is advertised.

For TikTok, inspect agent_method_profile and use one insights_query_consistent scopes request when advertised; otherwise use the native batch overview fallback.

Prepare a copy of this winning Meta ad into the target account, but ask me for confirmation before creating anything.

Group these distinct Meta Ads by language into the requested Campaign and AdSet layout. Prepare one grouped_plan, show every settings_source_ad_id and geography override, and wait for my approval before confirming once.

더 많은 예제는 docs/examples.md에 있습니다.

검증

로컬 릴리스 계약 및 테스트를 실행합니다:

python scripts/validate_tri_channel_pack.py
python -m pytest -q

릴리스 검증은 contracts/manifests/의 세 가지 커밋된 스냅샷에 대해 실패 시 폐쇄됩니다. 각 스냅샷은 커밋된 서비스 아티팩트에서 바이트 단위로 복사되며, contracts/manifests/provenance.json에서 해당 채널, 소스 개정, 공개 아티팩트 경로, 메타데이터 및 SHA-256에 잠겨 있습니다. CI는 라이브 네트워크 요청을 하지 않습니다.

python scripts/validate_public_tool_manifests.py

운영자는 서비스 매니페스트가 변경된 후 세 가지 스냅샷을 모두 결정론적으로 업데이트할 수 있습니다. 명령은 커밋되지 않았거나, 더티하거나, 누락되었거나, 계약과 호환되지 않는 소스를 거부하며 네트워크에서 가져오지 않습니다:

python scripts/sync_public_tool_manifests.py \
  --source meta=/path/to/meta-tools.json \
  --source google=/path/to/google-tools.json \
  --source tiktok=/path/to/tiktok-tools.json

세 가지 소스는 모두 필수입니다. 누락된 참조 도구, 입증되지 않은 필수 기능 또는 게이트, 오래된 출처 다이제스트 또는 부재한 채널은 릴리스 검증을 실패시킵니다. --allow-missing은 명시적인 로컬 진단용으로만 존재하며 릴리스 CI에서 사용되지 않습니다.

설치

이 저장소는 adsagent Claude 플러그인 (스킬 + .mcp.json MCP URL)으로 제공됩니다. GitHub 저장소 이름은 adsagent-ai-skills로 유지됩니다.

Claude Code (권장)

claude plugin marketplace add adsagents/adsagent-ai-skills
claude plugin install adsagent@adsagent

기존 사용자 범위 설치를 업데이트합니다:

claude plugin update --scope user adsagent@adsagent

claude plugin list에 중복된 로컬 및 사용자 설치가 표시되면 사용자 범위를 유지합니다:

claude plugin uninstall --scope local adsagent@adsagent

설치 또는 업데이트 후 새 Claude Code 세션을 시작합니다.

Cloud / Cowork 사전 설치 (설정 스니펫)

{
  "extraKnownMarketplaces": {
    "adsagent": {
      "source": {
        "source": "github",
        "repo": "adsagents/adsagent-ai-skills"
      }
    }
  },
  "enabledPlugins": ["adsagent@adsagent"]
}

설치 후 /mcp에 표시된 각 MCP 서버(Meta, Google, TikTok)를 인증합니다. .mcp.json에 headers.Authorization을 추가하지 마십시오. OAuth가 인증 경로로 유지되어야 합니다.

레거시 플러그인 슬러그에서 마이그레이션

이전 설치에서는 adsagent-ai-skills@adsagent-ai-skills 또는 adsagent-meta-ai-skills@adsagent-meta-ai-skills를 사용했습니다. 마켓플레이스는 adsagent@adsagent로 이름 변경을 선언합니다. 마이그레이션 후 레거시 중복을 제거합니다:

claude plugin uninstall --scope user adsagent-ai-skills@adsagent-ai-skills
claude plugin uninstall --scope user adsagent-meta-ai-skills@adsagent-meta-ai-skills

Codex CLI

codex plugin marketplace add adsagents/adsagent-ai-skills
codex plugin add adsagent@adsagent

새로 고침:

codex plugin marketplace upgrade adsagent

설치 또는 업그레이드 후 새 Codex 세션을 시작합니다.

Git 대체 및 기타 Agent-Skills 호환 클라이언트

skills/의 스킬은 표준 Agent Skills 레이아웃 (skills/<name>/SKILL.md with YAML frontmatter)을 사용합니다. 스킬만 사용하는 클라이언트(플러그인 MCP 번들 없음)는 수동으로 클론할 수 있습니다:

git clone https://github.com/adsagents/adsagent-ai-skills.git ~/.codex/skills/adsagent-ai-skills

해당 클라이언트는 여전히 별도의 MCP 연결(대시보드 설치 프롬프트 또는 Connectors Directory)이 필요합니다. 플러그인 경로는 원스텝 스킬 + MCP 번들입니다.

그런 다음 비플러그인 클라이언트를 위해 대시보드 OAuth/토큰 설정이 필요한 경우에만 AdsAgent를 엽니다:

Settings -> MCP Access -> Copy install prompt

플러그인 번들을 사용하지 않는 경우 복사된 프롬프트를 새 채팅에 붙여넣습니다. 프롬프트는 다음을 위한 호스티드 HTTP MCP URL을 제공합니다:

Meta default: https://adsagent.md/mcp/v2
Meta legacy fallback: https://adsagent.md/mcp
Google Ads: https://google.adsagent.md/mcp
TikTok: https://tiktok.adsagent.md/mcp

중요한 런타임 규칙

• 호스팅된 HTTP MCP만 사용합니다.

• 새로운 Meta 연결에는 https://adsagent.md/mcp/v2를 사용하고, /mcp는 레거시 폴백입니다.

• AdsAgent MCP 코드를 로컬에서 실행하지 마십시오.

• AdsAgent 대시보드에서 명시적으로 지시하지 않는 한 로컬 릴레이를 사용하지 마십시오.

• 클라이언트가 지원하는 경우 연결 설정을 캐시합니다.

• 토큰별 MCP 동시성을 제한하십시오.

• Retry-After를 준수합니다.

• HTTP 헤더, 최상위 data 또는 JSON-RPC error.data에서 Retry-After를 파싱합니다.

• mcp_concurrency_limited를 존중하고 지연과 지터(jitter)를 추가합니다.

• mcp_fanout_detected를 존중하여 차단된 단일 범위 요청을 재시도하는 대신 플랫폼 배치 개요 도구로 전환합니다.

• agent_method_profile.profile_id=adsagent_agent_methods_v1이고 해당 일관된 읽기가 클라이언트 로컬 카탈로그에 있는 경우, 세 플랫폼 모두에 대해 scope 또는 정렬된 scopes를 사용하여 하나의 insights_query_consistent 요청을 사용합니다.

• 해당 프로필이 없거나 클라이언트 로컬 카탈로그에서만 광고된 읽기가 누락된 경우, 프로필의 명명된 네이티브 폴백 또는 문서화된 서버 측 도구(Meta/TikTok insights_query_batch_overview, Google google_ads_insights_overview_batch)를 사용하십시오. 로컬 선택기 누락으로 인한 서버 등록 실패를 보고하지 마십시오.

• 먼저 집계된 데이터를 쿼리하고 공유된 도구 이름에서 크로스 플랫폼 기능 동등성을 유추하지 마십시오.

• 응답에서 서버가 계산한 합계를 보고하고 현재 표시된 행을 합산하지 마십시오.

• meta.complete=true인 경우에만 합계를 신뢰하십시오. 누락된 범위는 알 수 없으며 0이 아닙니다.

• 큐에 있는 작업을 terminal=true가 될 때까지 폴링하고 원시 CSV 대신 아티팩트 링크를 반환합니다.

• 서버가 직접 작업 참조를 광고하는 경우 tasks_get_status(task_ref=...)로 큐에 있는 작업을 직접 폴링합니다.

• QuickCreate 확인 토큰은 일회용이며 15분 후에 만료됩니다. expires_at을 확인하고, confirm_token_invalid 후에는 다시 준비하고 새 요약을 표시한 후 새로운 명시적 승인을 받으십시오.

• tasks_get_status(task_ref=..., response_mode=compact)로 Meta 생성 작업을 폴링합니다. no_create_permission 발생 시 사용자를 /dashboard/assets/fb-users로 안내하고, 고객 권한을 변경하거나 실패한 생성을 자동으로 재시도하지 마십시오.

• 일반 사용자 대화에서 원시 행 읽기를 피하십시오.

• 숫자는 Markdown 테이블을 사용하십시오.

• 광고 생성 또는 수정 전에 확인하십시오.

• 여러 개의 개별 소스 광고에는 grouped_plan을 사용하고, 클라이언트 측의 일련의 복사 변형을 통해 이를 에뮬레이트하지 마십시오.

• 운영자 검토 오류 시 중단하십시오.

• 오류에 support_ref가 포함된 경우 지원을 위해 그대로 보존하고 표시하십시오. 이는 권한이 아닙니다. 토큰, 요청 본문 또는 로그로 이를 생성, 수정, 열거 또는 대체하지 마십시오.

링크

• 공식 웹사이트: https://adsagent.md

• 공식 저장소: https://github.com/adsagents/adsagent-ai-skills

• 지원: support@adsagent.md

• 공개 온보딩 경로: https://adsagent.md/docs/mcp-onboarding

라이선스

모든 권리 보유. LICENSE.md를 참조하십시오.