Qingflow MCP (CRUD)

This MCP server exposes a canonical, agent-native public surface:

• qf_tool_spec_get

• qf_form_get

• qf_field_resolve

• qf_value_probe

• qf.query.plan

• qf.query.rows

• qf.query.record

• qf.query.aggregate

• qf.query.export

• qf.records.mutate

Legacy tools still exist internally for compatibility logic, but they are no longer advertised via listTools().

It intentionally excludes delete for now.

Setup

Runtime requirement:

• Node.js >=18

1. Install dependencies:

npm install

2. Set environment variables:

export QINGFLOW_BASE_URL="https://api.qingflow.com"
export QINGFLOW_ACCESS_TOKEN="your_access_token"

Optional:

export QINGFLOW_FORM_CACHE_TTL_MS=300000
export QINGFLOW_REQUEST_TIMEOUT_MS=18000
export QINGFLOW_EXECUTION_BUDGET_MS=20000
export QINGFLOW_ADAPTIVE_PAGING=1
export QINGFLOW_ADAPTIVE_MIN_PAGE_SIZE=20
export QINGFLOW_ADAPTIVE_TARGET_PAGE_MS=1200
export QINGFLOW_EXPORT_MAX_ROWS=10000
export QINGFLOW_EXPORT_DIR="/tmp/qingflow-mcp-exports"

Run

Development:

npm run dev

Build and run:

npm run build
npm start

Run tests:

npm test

Command Line Usage

qingflow-mcp still defaults to MCP stdio mode:

qingflow-mcp

Use CLI mode for quick local invocation:

# list all available tools
qingflow-mcp cli tools

# machine-readable tool list
qingflow-mcp cli tools --json

# canonical plan -> execute
qingflow-mcp cli call qf.query.plan --args '{
  "kind":"rows",
  "query":{
    "app_key":"your_app_key",
    "select":[1001,1002],
    "where":[{"field":1003,"op":"between","from":"2026-01-01","to":"2026-01-31"}],
    "limit":20
  }
}'

# then execute with returned plan_id
qingflow-mcp cli call qf.query.rows --args '{"plan_id":"plan_xxx"}'

CLI Install

Global install from GitHub:

npm i -g git+https://github.com/853046310/qingflow-mcp.git

Install from npm (pinned version):

npm i -g qingflow-mcp@0.7.0

Or one-click installer:

curl -fsSL https://raw.githubusercontent.com/853046310/qingflow-mcp/main/install.sh | bash

Safer (review script before execution):

curl -fsSL https://raw.githubusercontent.com/853046310/qingflow-mcp/main/install.sh -o install.sh
less install.sh
bash install.sh

MCP client config example:

{
  "mcpServers": {
    "qingflow": {
      "command": "qingflow-mcp",
      "env": {
        "QINGFLOW_BASE_URL": "https://api.qingflow.com",
        "QINGFLOW_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Recommended Flow

1. qf_apps_list to pick app.

2. qf_form_get to inspect field ids/titles.

3. qf_field_resolve for field-name to que_id mapping.

4. qf_value_probe when the agent needs candidate field values and explicit match evidence.

5. qf_record_create or qf_record_update.

6. If create/update returns only request_id, call qf_operation_get to resolve async result.

Full calling contract (Chinese):

• MCP 调用规范

• vNext Agent-Native 设计稿

Canonical Usage

Public agent flow is now:

1. qf_form_get / qf_field_resolve when field mapping is unclear

2. qf_value_probe when field value candidates are unclear

3. qf.query.plan

4. Execute the returned plan_id with:

   • qf.query.rows

   • qf.query.record

   • qf.query.aggregate

   • qf.query.export

   • qf.records.mutate

Planner Example

{
  "kind": "aggregate",
  "query": {
    "app_key": "your_app_key",
    "where": [
      { "field": 1003, "op": "between", "from": "2026-01-01", "to": "2026-01-31" }
    ],
    "group_by": [1003],
    "metrics": [
      { "op": "count" },
      { "column": 1002, "op": "sum" }
    ],
    "strict_full": true
  }
}

Execute Example

{
  "plan_id": "plan_xxx"
}

Rules:

1. Public execute tools require plan_id.

2. Optional query / action echo is only used for drift checking.

3. If execute input drifts from the planned canonical query, the server returns PLAN_DRIFT.

4. Public filtering uses canonical where[]; legacy filters are no longer part of the public contract.

Aggregate Business Counts

Aggregate business summaries use one canonical count contract:

{
  "summary": {
    "counts": {
      "source_record_count": 370,
      "group_assignment_count": 405,
      "metric_nonnull_record_count": 395
    },
    "primary_metric_total": 12272931.75,
    "primary_metric_missing_count": 10
  }
}

Default answer for “多少单/多少条” must read summary.counts.source_record_count.

Completeness

Canonical completeness is technical-only:

• is_complete

• raw_scan_complete

• scan_limit_hit

• fetched_pages

• requested_pages

• actual_scanned_pages

• scanned_pages

• scan_limit

• has_more

• next_page_token

• stop_reason

• output_truncated

• omitted_items

• omitted_chars

When strict_full=true, any incomplete result fails with INCOMPLETE_RESULT.

Error Protocol

Failures return structured JSON with a machine-readable error.code, for example:

{
  "ok": false,
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "...",
    "fix_hint": "...",
    "retryable": true
  }
}

Common codes:

• PLAN_REQUIRED

• PLAN_NOT_READY

• PLAN_DRIFT

• FORBIDDEN_RUNTIME_ALIAS

• VALIDATION_ERROR

• INCOMPLETE_RESULT

• UPSTREAM_TIMEOUT

• UPSTREAM_API_ERROR

Troubleshooting

If you see runtime errors around Headers or missing web APIs:

1. Upgrade Node to >=18.

2. Upgrade package to latest:

npm i -g qingflow-mcp@latest

3. Verify runtime:

node -e "console.log(process.version, typeof fetch, typeof Headers)"

Publish

npm login
npm publish

If you publish under an npm scope, use:

npm publish --access public

Security Notes

1. Keep QINGFLOW_ACCESS_TOKEN only in runtime env vars; do not commit .env.

2. Rotate token immediately if it appears in screenshots, logs, or chat history.

Community

• Contributing: CONTRIBUTING.md

• Security: SECURITY.md

• Conduct: CODE_OF_CONDUCT.md