Goal

Use NocoBase MCP tools to locate the right collection, query business data safely, and produce reliable summaries or grouped analysis.

Prerequisite

NocoBase MCP must already be reachable and authenticated.
If MCP returns authentication errors such as
```
Auth required
```
, stop and ask the user to refresh MCP authentication before continuing.

Default strategy

Inspect the data source path first.
Prefer the
```
main
```
data source.
If the target collection is not in
```
main
```
, inspect other enabled data sources.
Once the collection is located, use that
```
dataSource
```
explicitly in every subsequent
```
resource_*
```
call.
Prefer
```
resource_query
```
for counts and grouped analysis only after confirming the query parameter contract.
Fall back to
```
resource_list
```
plus manual counting when query results are suspicious or need cross-checking.

Useful references:

```
references/analysis-patterns.md
```
for common business analysis shapes
```
references/metric-checklist.md
```
for metric definition and scope checks
```
references/entity-mapping.md
```
for mapping business terms to collections and fields

Data source discovery

If the user explicitly names a data source, use it directly.
Otherwise start with
```
main
```
.
When the target collection is not found in
```
main
```
, call
```
data_sources:list_enabled
```
and inspect other enabled data sources one by one.
If multiple data sources contain the same collection name:
- default to
```
main
```
  when
```
main
```
  is one of them;
- otherwise present the candidates and explain which one you are using.
In the final answer, state which data source was used.

Collection discovery

If the user gives a collection name, verify it exists before querying.
If the user uses business terms such as "leads", "users", "orders", or "opportunities", inspect collection metadata to map the business term to the actual collection name.
Prefer
```
collections:listMeta
```
for a fast overview.
Then use
```
collections:get
```
with
```
appends: ["fields"]
```
when you need exact field names, relation targets, or enum options.
Use
```
references/entity-mapping.md
```
as a reusable heuristic for common business nouns and likely field categories.

Query contract checks

Before using

resource_query

, verify the request shape matches the real backend contract:

```
measures[].aggregation
```
, not
```
aggregate
```
```
orders[].order
```
, not
```
direction
```
```
field
```
should usually be passed as a field path array such as
```
["id"]
```
or
```
["owner", "nickname"]
```
Use
```
alias
```
whenever the result will be referenced in output or
```
having
```

Correct examples:

json

{
  "resource": "lead",
  "dataSource": "main",
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ]
}

json

{
  "resource": "lead",
  "dataSource": "main",
  "dimensions": [
    { "field": ["status"], "alias": "status" }
  ],
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ],
  "orders": [
    { "field": ["status"], "alias": "status", "order": "asc" }
  ]
}

Recommended workflow

1. Confirm reachability

Use
```
auth:check
```
.
If authentication fails, stop.

2. Find the collection

First inspect
```
main
```
.
If not found, inspect other enabled data sources.
Read fields before querying if field names or relations are uncertain.

3. Start with simple counts

Use
```
resource_query
```
with a single
```
count(id)
```
measure.
Keep the first query minimal so you can validate the result shape quickly.

4. Add grouped analysis

Common grouped views:

by status
by owner
by source
by department
by created date or month

For relation labels, use field paths such as:

```
["owner", "nickname"]
```
```
["mainDepartment", "title"]
```

5. Cross-check when needed

Re-check with

resource_list

when:

the grouped rows look duplicated unexpectedly;
the numeric result looks like record IDs instead of counts;
totals do not match between summary and grouped output;
the collection may be affected by ACL scope or hidden filters.

When cross-checking:

fetch enough rows to cover the visible dataset or use pagination;
count and group manually from the returned records;
compare the manual result with
```
resource_query
```
.

6. Present the result

Report:

the collection used;
the data source used;
the total count;
the key grouped breakdowns;
any caveat such as ACL scope, null values, or fallback to manual verification.

Analysis entry points

Classify the user request before querying:

```
overview
```
for current totals and main distributions
```
distribution
```
for grouped counts by status, owner, source, team, or department
```
funnel
```
for stage-based business progression
```
trend
```
for date or month-based change over time
```
ranking
```
for top owners, sources, accounts, or products
```
quality-check
```
for missing values, null-heavy fields, suspicious statuses, or orphaned relations

Use

references/analysis-patterns.md

for the recommended query shapes for each pattern.

Metric definition checks

Before returning an answer, verify the metric scope:

what time range is included
which time field drives the range
whether the metric is total count, distinct count, sum, or average
whether archived, inactive, null, or other terminal states should be included
whether grouped totals reconcile with the grand total

Use

references/metric-checklist.md

when the user request is ambiguous or the metric may be interpreted in more than one way.

Common pitfalls

Do not assume the collection is in
```
main
```
; check
```
main
```
first, then search other enabled data sources.
Do not omit
```
dataSource
```
after the collection has been located.
Do not use
```
aggregate
```
in query measures; the backend expects
```
aggregation
```
.
Do not use
```
direction
```
in query orders; the backend expects
```
order
```
.
Do not assume suspicious aggregate output is correct.
If a "count" result looks like
```
36
```
,
```
54
```
,
```
80
```
, or another plausible record ID, verify whether aggregation was actually applied.
Relation label grouping requires the real relation path and target field, not guessed labels.

Verification checklist

MCP is authenticated.
The collection exists in the chosen data source.
The fields used in
```
dimensions
```
,
```
measures
```
,
```
orders
```
, and
```
filter
```
actually exist.
```
resource_query
```
uses
```
aggregation
```
and
```
order
```
.
Summary totals match grouped totals, or any mismatch is explained.
The final answer states the data source and any verification fallback used.

nocobase-data-analysis

NPX Install

Tags

SKILL.md Content