owner-clone-ai-mcp 1.36.2 → 1.36.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/domains/analytics.js +189 -0
- package/index.js +2 -1
- package/package.json +1 -1
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { callApi } = require('../lib/api');
|
|
3
|
+
|
|
4
|
+
// 集計・分析（Meta広告）ツール。/api/mcp/v1/analytics を叩く（backend の analyticsToolCore/WriteCore と同一SSoT）。
|
|
5
|
+
// 読取＝目標達成状況付き集計・比較・上位/下位・日次推移・定義。書込＝数値upsert・目標記入・目標算出・シート/エンティティ作成・CSV取込。
|
|
6
|
+
// 削除系はAIに公開しない（安全ガード）。機能フラグ analytics（マスタープラン限定）でサーバー側403ゲート。
|
|
7
|
+
|
|
8
|
+
// 期間指定の共通プロパティ（各ツールで再利用）。
|
|
9
|
+
const PERIOD_PROPS = {
|
|
10
|
+
period: { type: 'string', enum: ['all', 'this_month', 'last_month', 'last_7d', 'last_14d', 'last_30d', 'custom'], description: '期間プリセット（既定all）。任意期間は custom＋from/to。' },
|
|
11
|
+
from: { type: 'string', description: 'custom時の開始日 YYYY-MM-DD' },
|
|
12
|
+
to: { type: 'string', description: 'custom時の終了日 YYYY-MM-DD（終端日を含む）' },
|
|
13
|
+
};
|
|
14
|
+
const SHEET_PROPS = {
|
|
15
|
+
sheet_name: { type: 'string', description: '対象シート名（部分一致可）' },
|
|
16
|
+
sheet_id: { type: 'string', description: '対象シートのID（分かる場合）' },
|
|
17
|
+
level: { type: 'number', description: 'レベル番号（0=最上位＝キャンペーン相当）' },
|
|
18
|
+
level_label: { type: 'string', description: 'レベル名（例: "キャンペーン"/"広告セット"/"広告"）。number より優先。' },
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const tools = [
|
|
22
|
+
{
|
|
23
|
+
name: 'analytics_list_sheets',
|
|
24
|
+
description: '集計・分析のシート一覧（媒体・レベルラベル・設定済み目標値）を取得。対象シートを特定する起点。',
|
|
25
|
+
annotations: { readOnlyHint: true },
|
|
26
|
+
inputSchema: { type: 'object', properties: {} },
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
name: 'analytics_defs',
|
|
30
|
+
description: '指標の定義（ラベル・単位・方向dir・派生の計算式）を取得。CPA=spend÷conversions 等、指標を正しく解釈するための定義。',
|
|
31
|
+
annotations: { readOnlyHint: true },
|
|
32
|
+
inputSchema: { type: 'object', properties: { platform: { type: 'string', description: '媒体（省略時 meta）' } } },
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
name: 'analytics_query',
|
|
36
|
+
description: 'シート×レベル×期間で広告集計を取得。各指標に「目標達成状況(good/bad/neutral)」を同梱するので、どの指標が未達かを判断できる。クリエイティブ紐付け(knowledge_item_id)も返す。filters/sort/limitで絞り込み・並べ替え可。【読取】',
|
|
37
|
+
annotations: { readOnlyHint: true },
|
|
38
|
+
inputSchema: {
|
|
39
|
+
type: 'object',
|
|
40
|
+
properties: {
|
|
41
|
+
...SHEET_PROPS, ...PERIOD_PROPS,
|
|
42
|
+
filters: { type: 'array', description: '指標フィルタ [{metric, op:gte|lte|gt|lt|eq, value}]。metricは小文字の指標key（spend/impressions/clicks/conversions/seats/purchasers/revenue/reach/ctr/cpc/cvr/cpa/cpo/cpo_seat/roas/cpm）＝analytics_defsで一覧取得可。', items: { type: 'object' } },
|
|
43
|
+
sort: { type: 'object', description: '並べ替え {metric, dir:asc|desc}。metricは小文字の指標key。' },
|
|
44
|
+
limit: { type: 'number', description: '最大件数（既定100）' },
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
name: 'analytics_compare',
|
|
50
|
+
description: '2つの期間を取得して増減比較（各指標の増減%＋方向考慮の良化判定）。期間Aと期間Bを比較して最適広告や悪化を発見する。【読取】',
|
|
51
|
+
annotations: { readOnlyHint: true },
|
|
52
|
+
inputSchema: {
|
|
53
|
+
type: 'object',
|
|
54
|
+
properties: {
|
|
55
|
+
...SHEET_PROPS,
|
|
56
|
+
periodA: { type: 'object', description: '主期間 {period, from, to}' },
|
|
57
|
+
periodB: { type: 'object', description: '比較期間 {period, from, to}' },
|
|
58
|
+
sort: { type: 'object', description: '並べ替え {metric, dir}' },
|
|
59
|
+
limit: { type: 'number' },
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
name: 'analytics_top_ads',
|
|
65
|
+
description: '指標で上位/下位の広告を抽出（目標達成状況＋クリエイティブ紐付け付き）。「どの広告のどの指標が未達か」を1回で把握＝改善ループの起点。クリエイティブ本文は get_knowledge_item(knowledge_item_id) で取得して優劣・改善点を評価する。【読取】',
|
|
66
|
+
annotations: { readOnlyHint: true },
|
|
67
|
+
inputSchema: {
|
|
68
|
+
type: 'object',
|
|
69
|
+
properties: {
|
|
70
|
+
...SHEET_PROPS, ...PERIOD_PROPS,
|
|
71
|
+
metric: { type: 'string', description: '並べ替える指標key（小文字。例: cpa, roas, cvr, spend）。既定spend。値が算出不能(0除算)の行は末尾。' },
|
|
72
|
+
order: { type: 'string', enum: ['asc', 'desc'], description: 'desc=上位(大きい順)/asc=下位。既定desc。※CPA/CPC等「低いほど良い」指標の優良はasc、ROAS/CTR等はdesc。' },
|
|
73
|
+
limit: { type: 'number', description: '件数（既定10）' },
|
|
74
|
+
},
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
name: 'analytics_timeseries',
|
|
79
|
+
description: '指定エンティティ（広告等）の日次推移を取得。悪化トレンドの早期検知やフィードバック品質向上に使う。【読取】',
|
|
80
|
+
annotations: { readOnlyHint: true },
|
|
81
|
+
inputSchema: {
|
|
82
|
+
type: 'object',
|
|
83
|
+
properties: { ...SHEET_PROPS, ...PERIOD_PROPS, entity_id: { type: 'string', description: '対象の広告/広告セット/キャンペーンのID（必須）' } },
|
|
84
|
+
required: ['entity_id'],
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
name: 'analytics_upsert_metrics',
|
|
89
|
+
description: '広告の日次/範囲の数値を追加・修正（同一日は上書き＝冪等）。items=[{entity_id, date(YYYY-MM-DD), period_end?(範囲の終端), values:{spend,impressions,clicks,conversions,seats,purchasers,revenue,reach}}]。valuesのキーは小文字の加算指標のみ（派生CPA/ROAS等は保存不可＝自動算出）。数値は円/回/人/件（%やCPA等の派生値は入れない）。【書き込み権限付きキーが必要】',
|
|
90
|
+
annotations: { destructiveHint: false, idempotentHint: true },
|
|
91
|
+
inputSchema: {
|
|
92
|
+
type: 'object',
|
|
93
|
+
properties: { items: { type: 'array', description: '[{entity_id, date, period_end?, values}]', items: { type: 'object' } } },
|
|
94
|
+
required: ['items'],
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
name: 'analytics_set_targets',
|
|
99
|
+
description: 'シートの目標値を記入（指標key→数値）。既定は既存目標にマージ（merge:falseで置換）。目標に使える指標key（小文字）: cpa/cpm/ctr/cvr/cpc/roas/cpo/cpo_seat/spend/conversions 等。analytics_goal_plan の結果 plan.targets をそのまま渡して保存できる。無効キー・大文字は自動で正規化/除外。【書き込み権限付きキーが必要】',
|
|
100
|
+
annotations: { destructiveHint: false, idempotentHint: true },
|
|
101
|
+
inputSchema: {
|
|
102
|
+
type: 'object',
|
|
103
|
+
properties: { ...SHEET_PROPS, targets: { type: 'object', description: '{指標key(小文字): 数値}。例 {"cpa":1000,"roas":800,"cpo_seat":5000}' }, merge: { type: 'boolean', description: 'false=置換（既定はマージ）' } },
|
|
104
|
+
required: ['targets'],
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
name: 'analytics_goal_plan',
|
|
109
|
+
description: '販売フローから目標値(CPA/CPM/CTR/CPC/CVR/ROAS/CPO/CPO_seat等)を自動算出・提案。事業ジャンル(A-E)＋最小入力から。戻り値 plan.targets（小文字key）を analytics_set_targets の targets にそのまま渡して保存できる。warnings に下限割れ等の注意も返る（この呼び出し自体は保存しない）。',
|
|
110
|
+
annotations: { readOnlyHint: true },
|
|
111
|
+
inputSchema: {
|
|
112
|
+
type: 'object',
|
|
113
|
+
properties: {
|
|
114
|
+
genre: { type: 'string', description: '事業ジャンル A:起業/副業/ビジネス, B:健康/ダイエット, C:スピ/自己啓発, D:趣味その他(競合多), E:趣味その他(ニッチ)' },
|
|
115
|
+
monthly_revenue: { type: 'number', description: '月間売上目標(円)' },
|
|
116
|
+
unit_price: { type: 'number', description: '顧客単価(円)' },
|
|
117
|
+
monthly_budget: { type: 'number', description: '月間広告予算(円)' },
|
|
118
|
+
sell_method: { type: 'string', enum: ['seminar', 'vsl'], description: 'seminar=個別相談/セミナー, vsl=非対面' },
|
|
119
|
+
attendees: { type: 'number', description: '[seminar]参加者数' },
|
|
120
|
+
vsl_performance: { type: 'string', enum: ['baseline', 'target', 'high'], description: '[vsl]想定成約率レベル' },
|
|
121
|
+
},
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
name: 'analytics_create_sheet',
|
|
126
|
+
description: '集計シートを作成（現状 Meta広告のみ）。level_labels 省略時は キャンペーン/広告セット/広告。【書き込み権限付きキーが必要】',
|
|
127
|
+
annotations: { destructiveHint: false, idempotentHint: false },
|
|
128
|
+
inputSchema: {
|
|
129
|
+
type: 'object',
|
|
130
|
+
properties: { name: { type: 'string', description: 'シート名（媒体・アカウントが分かる名前）' }, level_labels: { type: 'array', items: { type: 'string' }, description: '階層ラベル（2〜4）' } },
|
|
131
|
+
required: ['name'],
|
|
132
|
+
},
|
|
133
|
+
},
|
|
134
|
+
{
|
|
135
|
+
name: 'analytics_create_entity',
|
|
136
|
+
description: '広告階層のエンティティ（キャンペーン/広告セット/広告）を作成。親は parent_id か parent_name で指定。knowledge_item_id で広告クリエイティブ(ad/image/videoカテゴリのナレッジ)を紐付け可。external_id にMeta広告IDを保持すると将来のAPI同期に前方互換。【書き込み権限付きキーが必要】',
|
|
137
|
+
annotations: { destructiveHint: false, idempotentHint: false },
|
|
138
|
+
inputSchema: {
|
|
139
|
+
type: 'object',
|
|
140
|
+
properties: {
|
|
141
|
+
...SHEET_PROPS,
|
|
142
|
+
name: { type: 'string', description: '作成する名前' },
|
|
143
|
+
parent_id: { type: 'string', description: '親エンティティID（level>0で必要）' },
|
|
144
|
+
parent_name: { type: 'string', description: '親の名前（IDが不明な時・部分一致）' },
|
|
145
|
+
external_id: { type: 'string', description: 'Meta広告ID等（任意・将来の自動同期用）' },
|
|
146
|
+
knowledge_item_id: { type: 'string', description: '紐付ける広告クリエイティブ（ナレッジ ad/image/video）のID（任意）' },
|
|
147
|
+
},
|
|
148
|
+
required: ['name'],
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
{
|
|
152
|
+
name: 'analytics_import_csv',
|
|
153
|
+
description: 'Meta広告のエクスポートCSV(テキスト)を取り込み、キャンペーン>広告セット>広告を自動作成＋数値をupsert。csvにはCSV全文を渡す。date_mode="period"なら取込時のperiod_start/period_end(YYYY-MM-DD)を全行へ適用、"csv"ならCSV各行の日付を使用。overwrite=trueで対象期間の既存を消して入れ直し。【書き込み権限付きキーが必要】',
|
|
154
|
+
annotations: { destructiveHint: false, idempotentHint: true },
|
|
155
|
+
inputSchema: {
|
|
156
|
+
type: 'object',
|
|
157
|
+
properties: {
|
|
158
|
+
...SHEET_PROPS,
|
|
159
|
+
csv: { type: 'string', description: 'Meta広告エクスポートCSVの全文テキスト' },
|
|
160
|
+
match_mode: { type: 'string', enum: ['reuse', 'new'], description: '同名広告を再利用reuse(既定)/新規作成new' },
|
|
161
|
+
date_mode: { type: 'string', enum: ['period', 'csv'], description: 'period=指定期間を全行へ(既定)/csv=各行の日付' },
|
|
162
|
+
period_start: { type: 'string', description: 'date_mode=period時の開始日 YYYY-MM-DD' },
|
|
163
|
+
period_end: { type: 'string', description: 'date_mode=period時の終了日 YYYY-MM-DD' },
|
|
164
|
+
overwrite: { type: 'boolean', description: '対象期間の既存データを削除して入れ直す' },
|
|
165
|
+
},
|
|
166
|
+
required: ['csv'],
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
];
|
|
170
|
+
|
|
171
|
+
const j = data => JSON.stringify(data, null, 2);
|
|
172
|
+
const post = (path, body) => callApi(path, { method: 'POST', body: JSON.stringify(body || {}) });
|
|
173
|
+
|
|
174
|
+
const handlers = {
|
|
175
|
+
async analytics_list_sheets() { return j(await callApi('/analytics/sheets')); },
|
|
176
|
+
async analytics_defs(args) { return j(await callApi(`/analytics/defs${args && args.platform ? `?platform=${encodeURIComponent(args.platform)}` : ''}`)); },
|
|
177
|
+
async analytics_query(args) { return j(await post('/analytics/query', args)); },
|
|
178
|
+
async analytics_compare(args) { return j(await post('/analytics/compare', args)); },
|
|
179
|
+
async analytics_top_ads(args) { return j(await post('/analytics/top-ads', args)); },
|
|
180
|
+
async analytics_timeseries(args) { return j(await post('/analytics/timeseries', args)); },
|
|
181
|
+
async analytics_upsert_metrics(args) { return j(await post('/analytics/metrics', { items: args.items })); },
|
|
182
|
+
async analytics_set_targets(args) { return j(await post('/analytics/targets', args)); },
|
|
183
|
+
async analytics_goal_plan(args) { return j(await post('/analytics/goal-plan', args)); },
|
|
184
|
+
async analytics_create_sheet(args) { return j(await post('/analytics/create-sheet', args)); },
|
|
185
|
+
async analytics_create_entity(args) { return j(await post('/analytics/create-entity', args)); },
|
|
186
|
+
async analytics_import_csv(args) { return j(await post('/analytics/import', args)); },
|
|
187
|
+
};
|
|
188
|
+
|
|
189
|
+
module.exports = { tools, handlers };
|
package/index.js
CHANGED
|
@@ -20,8 +20,9 @@ const projects = require('./domains/projects');
|
|
|
20
20
|
const brain = require('./domains/brain');
|
|
21
21
|
const funnels = require('./domains/funnels');
|
|
22
22
|
const skills = require('./domains/skills');
|
|
23
|
+
const analytics = require('./domains/analytics');
|
|
23
24
|
|
|
24
|
-
const allDomains = [knowledge, agentPresets, workflows, chatbots, schedulesAndTasks, projects, brain, funnels, skills];
|
|
25
|
+
const allDomains = [knowledge, agentPresets, workflows, chatbots, schedulesAndTasks, projects, brain, funnels, skills, analytics];
|
|
25
26
|
|
|
26
27
|
const TOOLS = allDomains.flatMap(d => d.tools);
|
|
27
28
|
const HANDLERS = Object.assign({}, ...allDomains.map(d => d.handlers));
|