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