What this skill does
Admin MCP のUsing only read-only tools, identify "where the costs are being incurred" and "which endpoints are slow / not being cached" for the Kuroco site, and create a report that lists countermeasures in order of cost-effectiveness.
The main focus of the investigation isCache. Kuroco's metered billing is dominated by the number of requests, and whether or not they are cached changes the unit price by an order of magnitude. Therefore, "reduce requests" and "increase the cache ratio" are almost all of the countermeasures.
This skill handles up to investigation and proposals. Configuration changes (cache duration, CORS, endpoint definitions) are made after obtaining the user's approval, and as a rule we guide the user to carry them out in the admin panel (→ Boundaries of changes）。
Prerequisites
- Being connected to the Admin MCP. For connection method, authentication, and scopes, see
/kuroco-admin-mcp. For investigation only,x/all/readonlyormcp:tools.readscope is sufficient - For tool names and arguments, the inputSchema of
tools/listis authoritative. The arguments listed in this skill have been verified against the implementation, but before calling, confirm existence withtools/list. Required modules:site（usage）、logs（api_analytics / api_log）、rcms_api（api） - Admin MCP requests themselves are also billable. Do not make wasteful calls such as fetching all raw logs
(aggregate with
api_analytics-list, and fetch raw logs only for the necessary time period)
Billing model (minimal)
For details, see references/cost-model.md. Here, only what is essential for decisions.
- Cost = ceil(actual count ÷ UNIT) × unit price. Example: if the API request UNIT is 1000 hits and the unit price is 55 yen, then even 100 hits gives ceil(0.1)=1 → 55 yen
- Cache HITs are also billed. They do not become free; the unit price merely decreases. "Because it is a HIT on the CDN, it has nothing to do with cost" is incorrect
- Billing is aggregated within the month. However, for file storage only, the maximum value of the aggregation periodis used
- Unit prices differ depending on the contract. When discussing amounts, use the actual results from
usage-getto back-calculate yen/request (→ Step 2） - The display items for usage status and the billing expense items are not 1:1. For the correspondence table, see
references/cost-model.md
Tools to use
| Tool | Purpose | Main constraints |
|---|---|---|
usage-get |
Monthly/daily costs and usage volume. Trends by expense item | Only for the connected site (site_id cannot be specified). Daily series is up to the previous day |
api_analytics-list |
Aggregation by endpoint (count, average execution time, average response size) | One range is at most 35 days.Not subject to the 12-hour limit or rate limit(explicitly excluded in the implementation) |
api_log-list |
1 raw log line = 1 request (UA, country, referer, token, IP, etc.) | Last 12 hoursonly (timestamp_start judged by).Once per 5-second slot per memberrate limit |
api-list |
List of API definitions (api_id, title, security) | — |
api_uri-list |
Endpoint definitions +usage aggregation for the last 8 daysand cache settings | api_id required (called per API). The return is uri_list[]. What to look at is uri_data（→ references/mcp-tools.md） |
front_log-list / img_log-list / edge_log-list |
Breakdown of transfer volume (frontend / images / Edge) | Same 12-hour limit and rate limit as api_log |
For aggregation, api_analytics-list takes priority. Raw logs are used only to
confirm "behavior that cannot be explained by aggregation" (since it is 1 line per request, it is expensive for looking at trends).
The arguments, return fields, and value formats of each tool are references/mcp-tools.md.
Return values arestrings formatted for display（"15.61 KB" "426 ms" "1,234hits",
note that the execution time of HIT lines is " - "). Filtering and sorting work on the raw numeric values.
Standard workflow
If the request is a comprehensive investigation such as "find out why usage costs increased", carry out steps 1 onward in order. If the request is limited to an already-identified symptom (e.g., this endpoint is slow), you may carry out only the relevant step(omission conditions are stated for each step).
Step 1: Understand the cost structure
// tool: usage-get
{ "ym": "<調査対象月 YYYY-MM>", "chart_begin_ym": "<開始月>", "chart_end_ym": "<終了月>" }
cost_monthlyis the monthly series by expense category (key/disp_nm/dataarray).A single call can retrieve long-term trends, so do not call separately for each monthcost_siteis theymmonthly cost by expense category for the connected site,cost_all_sitesはthe total of all environments (dev/stg/prod, etc.) under the parent site. Confusing them will overstate the amount. If not specified,cost_siteis usedusage_listis the daily raw count (api_count/cached_api_count/api_traffic/db_bytes/files_bytesand others) + a total row at the end.The current day's row is not included- The determination of "increased" is made by comparing with the same month last year or the previous month, using the same number of days. Do not compare an in-progress month as is
Omission condition: When the request is limited to the performance of a specific endpoint rather than costs.
Step 2: Back-calculate the unit price
From the expense-category amounts for the same month and the usage_list total row (expense-category counts),
calculate yen/request and yen/GB.Always produce the unit-price ratio for cached vs. non-cached
(this ratio determines all subsequent priorities).
cost_site は disp_nm / value alone does not have machine-readable keys, so
if you want to mechanically associate expense categories with counts,the keyed cost_monthlyUse (the elements for the relevant month).
Write in the report that the obtained unit price is the "effective unit price for this contract" and is not a transcription of the official price list.
Omission condition: When the report does not mention monetary amounts (a pure performance investigation).
Step 3: Aggregate by endpoint
// tool: api_analytics-list
{ "timestamp_start": "<YYYY-MM-DD HH:MM>", "timestamp_end": "<YYYY-MM-DD HH:MM>",
"sort": "hit", "desc": true, "cnt": 100 }
- What is returned is
api_id（Resolved to API title）・api_uri_id（/rcms-api/{id}/{uri}resolved to）・request(HTTP method)・cache_status・status・hit・execution_time(average)・execution_time_additional(total of the portion exceeding 300ms = the substance of computing charges)・body_size(average) - Even for the same URI,
cache_statusit becomes a separate row for each.Create the denominator by adding the HIT rows and the MISS rows - How you construct the comparison is crucial: Obtain the same period of the previous year (same number of days) in a separate call, and first derive the overall growth rate (= baseline). Then, treat only the endpoints that "grew far beyond the baseline / newly appeared" as anomalies
- One range is a maximum of 35 days. For year-over-year comparison, obtain it in two calls
- Filters apply to the raw values and raw api_id (even if the display is the title, write
api_id = 3)
Omission condition: None (this step is the core of the investigation).
Step 4: Cross-check the cache settings against recent results
// tool: api-list（引数なし。MODE はサーバー側で付与される）
{}
// tool: api_uri-list
{ "api_id": <ステップ3で問題が出た API の api_id> }
uri_data にBoth the cache settings and the usage aggregation for the most recent 8 days are included:
cache_settings（JSON）:maxage(cache seconds. If unset/0, it is not cached),cache_by_group(group-level cache that can be set only for Topics::list / Topics::details)rate_settings:limit_req/limit_slotapi_count/cached_api_count/body_avg/exec_avg(most recent 8 days. No data is"-"）
Here, distinguish between "is the TTL unset, or is the TTL set but not being hit?". These two have completely different countermeasures (the former is configuration, the latter is cache key dispersion or the authentication method).
Omission condition: When the request is only to understand the cost breakdown and does not include endpoint improvement.
Step 5: Verify with raw logs
Only when checking phenomena that cannot be explained by aggregation alone (0-byte responses, repeated 400s, unexpected referers, crawler ratio, repeated calls from the same client).
// tool: api_log-list
{ "timestamp_start": "<直近12時間内 YYYY-MM-DD HH:MM>", "timestamp_end": "<同上>",
"filter": "cache_status = \"MISS\"",
"columns": ["timestamp", "uri", "cache_status", "status", "body_size", "execution_time",
"request_user_agent", "geo_country_code", "request_referer", "api_access_token"],
"cnt": 200 }
- Data before 12 hours cannot be obtained. For past events,
api_analytics-listcheck with - Rate limit of once every 5 seconds. Leave intervals between consecutive calls
columnsto narrow down to the necessary columns (log rows are wide)- Take a representative sample of 30 minutes to 1 hour, and speak in terms of ratios.If you extrapolate monthly figures from the sample, state clearly in the report that it is an extrapolation and the basis period
Omission condition: When the cause can be identified in Steps 3 and 4 and no additional hypothesis verification is needed.
Step 6: Identify the cause from the symptoms
references/diagnostics.md use the symptom-based recipes. Representative examples:
| Symptom | Main cause |
|---|---|
Cache hit ratio is low (cached_api_count is small) |
maxage Not set / cache is split by Cookie authentication and dynamic tokens / designed to result in PASS |
| TTL is sufficient yet there are many MISSes | High URL cardinality (detail pages) + exhaustive crawling by crawlers |
| Many requests per page view | Frontend N+1 fan-out (a separate API for each element in a list) |
| PASS + 4xx occur constantly for the same URI | Frontend bug (e.g., passing an undefined value in a query). PASS is never cached permanently |
| Execution time is long | The portion exceeding 300ms is billed as computing.execution_time_additional to see the contribution |
| Transfer volume increased | First break it down by cost category into API, frontend, or images, then take countermeasures |
| There are many 0-byte responses | Possibility of CORS preflight (→ references/diagnostics.md identification procedure and confirmation method) |
Step 7: Summarize countermeasures in order of cost-effectiveness
references/cache-tuning.md From the countermeasure catalog, select the applicable ones and
estimated reduction amount, man-hours, side effectslist them along with these. The report format is as follows.
Decision rules
Errors in reports almost always arise from one of these 6 points.
- Prioritize by "monetary contribution," not by "rate." The cost category with the largest increase rate and the cost category with the largest increase amount often do not match
- Do not simply sum the estimated reductions. Countermeasures overlap in what they reduce. If they overlap, state clearly that "if countermeasure A is implemented first, the estimate for countermeasure B shrinks to about N tenths"
- Do not assert implementation from correlation. Mechanisms read from logs (e.g., frontend behavior inferred from the ordering of requests) should bewritten as hypotheses, and include the means of confirmation (checking the frontend implementation, the browser HAR, response headers, inquiry to Kuroco support)
- Do not revert items that have already been optimized. If there is a cost category that dropped sharply in the past,
check whether the proposal would undo the optimization made at that time (the trend can be seen in
cost_monthly) - Always cite sources for unit prices and counts(from which tool, for which period)
- Clearly state what could not be determined as "limitations." Logs that can only go back 12 hours, extrapolation from samples, and unverified hypotheses should be written alongside the conclusions
Boundaries of changes
| Operation | Allowed |
|---|---|
| Investigation with read-only tools | May be performed as is |
Cache period (maxage) change |
api_uri-upsert There is no cache_settings in the inputSchema, and passing it will be rejected. Since it cannot be changed from MCP, guide the procedure in the admin screen (fields omitted during an update are preserved, so existing settings will not be lost by other updates) |
Changes to CORS settings (cors.maxAge etc.) |
api-upsert are possible with.User approval required. The change is delayed by the remaining Access-Control-Max-Age time |
| Changing the security method (Cookie → static token, etc.) | api-upsert are possible with.All issued tokens are invalidated, so planning must be done together with frontend modifications. Approval required |
CDN cache purge (api-cdn_cache_purge） |
The target is specified with api_uri_id(single) / api_uri_ids(multiple) / all: true(all endpoints) using theexactly one(no selector is 400). Immediately afterward, MISSes to the origin concentrate (all is the entire site). Approval required. Do not execute for investigation purposes |
annotation cache purge (api-annotation_cache_purge） |
The CDN cache for all API endpoints is also purged at the same time. Approval required. Do not execute for investigation purposes |
| Creating/deleting endpoints | Out of scope for this skill./kuroco-api-content Use |
Report type
1. 結論（3行）— 何が費用/遅延の主因か、金額規模、最大の対策
2. コスト内訳と推移 — 費目別の差分と寄与率（出典: usage-get, 期間）
3. エンドポイント別の変化 — ベースライン成長率と、それを超えた異常値（出典: api_analytics-list, 期間）
4. 原因（要因ごとに: 根拠データ / 確定か仮説か / 影響度）
5. 対策一覧（費用対効果順: 削減見込み・工数・副作用・重複の注意）
6. 調査方法と限界（データ源・取得条件・未確認事項）
Do not mix hypotheses and confirmed facts in the same section. For items later found to be incorrect, leaving them as "previous view / after correction" rather than deleting them allows readers to trace the basis for decisions.
Troubleshooting
| Symptom | Cause and remedy |
|---|---|
api_log-list is an error/empty |
A time earlier than 12 hours is specified. Set the range within the last 12 hours |
api_log-list is a rate limit error |
Limit of once per member per 5-second slot. Re-run after an interval (api_analytics-list is excluded) |
api_analytics-list is a range error |
The maximum range per request is 35 days. Split the period |
usage-get cannot be passed site_id |
By specification. MCP is bound to the connected site. For other environments, connect to the MCP endpoint of the relevant site and investigate |
| The amount is larger than expected | cost_all_sitesCheck whether you are not reading (all environments total) |
| Filters do not work | Write using raw values ("15.61 KB"), not display values (API title,api_id numeric values, byte counts) |
| Tools are not visible | Checklist for scoped site / logs / rcms_api Check whether is included (/kuroco-admin-mcp ) |
References
| File | Content |
|---|---|
references/mcp-tools.md |
Arguments, return fields, value formats, and constraints for each tool |
references/cost-model.md |
Billing model, correspondence between usage items and cost categories, and procedure for back-calculating unit prices |
references/diagnostics.md |
Investigation recipes by symptom (query examples and criteria) |
references/cache-tuning.md |
List of cache design levers, application conditions, and side effects |
Cooperation with other skills
| Skill | Proper use |
|---|---|
/kuroco-admin-mcp |
Basics of connection, authentication, scopes, and tool naming |
/kuroco-api-content |
Endpoint design, authentication methods, and how to write filter queries |
/kuroco-frontend-integration |
SSG conversion and reducing requests on the frontend |
/kuroco-server-processing |
Billing differences for internal API calls ({api_internal} / {api_method}),purge_cdn_cache |
/kuroco-docs |
Checking the original text of the official documentation (usage status, API cache, usage fee optimization) |