qingflow-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# Qingflow MCP (CRUD)
+
+This MCP server wraps Qingflow OpenAPI for:
+
+- `qf_apps_list`
+- `qf_form_get`
+- `qf_records_list`
+- `qf_record_get`
+- `qf_record_create`
+- `qf_record_update`
+- `qf_operation_get`
+
+It intentionally excludes delete for now.
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Set environment variables:
+
+```bash
+export QINGFLOW_BASE_URL="https://api.qingflow.com"
+export QINGFLOW_ACCESS_TOKEN="your_access_token"
+```
+
+Optional:
+
+```bash
+export QINGFLOW_FORM_CACHE_TTL_MS=300000
+```
+
+## Run
+
+Development:
+
+```bash
+npm run dev
+```
+
+Build and run:
+
+```bash
+npm run build
+npm start
+```
+
+## CLI Install
+
+Global install from GitHub:
+
+```bash
+npm i -g git+https://github.com/853046310/qingflow-mcp.git
+```
+
+Or one-click installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/853046310/qingflow-mcp/main/install.sh | bash
+```
+
+Safer (review script before execution):
+
+```bash
+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:
+
+```json
+{
+  "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_record_create` or `qf_record_update`.
+4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
+
+## Publish
+
+```bash
+npm login
+npm publish
+```
+
+If you publish under an npm scope, use:
+
+```bash
+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](./CONTRIBUTING.md)
+- Security: [SECURITY.md](./SECURITY.md)
+- Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)

package/dist/qingflow-client.js

@@ -0,0 +1,255 @@
+export class QingflowApiError extends Error {
+    errCode;
+    errMsg;
+    httpStatus;
+    details;
+    constructor(params) {
+        super(params.message);
+        this.name = "QingflowApiError";
+        this.errCode = params.errCode ?? null;
+        this.errMsg = params.errMsg ?? params.message;
+        this.httpStatus = params.httpStatus ?? null;
+        this.details = params.details;
+    }
+}
+export class QingflowClient {
+    baseUrl;
+    accessToken;
+    timeoutMs;
+    constructor(config) {
+        this.baseUrl = normalizeBaseUrl(config.baseUrl);
+        this.accessToken = normalizeAccessToken(config.accessToken);
+        this.timeoutMs = config.timeoutMs ?? 30_000;
+    }
+    listApps(options = {}) {
+        return this.request({
+            method: "GET",
+            path: "/app",
+            options: {
+                query: {
+                    userId: options.userId,
+                    favourite: options.favourite
+                }
+            }
+        });
+    }
+    getForm(appKey, options = {}) {
+        return this.request({
+            method: "GET",
+            path: `/app/${encodeURIComponent(appKey)}/form`,
+            options: {
+                userId: options.userId
+            }
+        });
+    }
+    listRecords(appKey, payload, options = {}) {
+        return this.request({
+            method: "POST",
+            path: `/app/${encodeURIComponent(appKey)}/apply/filter`,
+            options: {
+                userId: options.userId,
+                body: payload
+            }
+        });
+    }
+    getRecord(applyId) {
+        return this.request({
+            method: "GET",
+            path: `/apply/${encodeURIComponent(applyId)}`
+        });
+    }
+    createRecord(appKey, payload, options = {}) {
+        return this.request({
+            method: "POST",
+            path: `/app/${encodeURIComponent(appKey)}/apply`,
+            options: {
+                userId: options.userId,
+                body: payload
+            }
+        });
+    }
+    updateRecord(applyId, payload, options = {}) {
+        return this.request({
+            method: "POST",
+            path: `/apply/${encodeURIComponent(applyId)}`,
+            options: {
+                userId: options.userId,
+                body: payload
+            }
+        });
+    }
+    getOperation(requestId) {
+        return this.request({
+            method: "GET",
+            path: `/operation/${encodeURIComponent(requestId)}`
+        });
+    }
+    async request(params) {
+        const options = params.options ?? {};
+        const url = new URL(params.path, this.baseUrl);
+        appendQuery(url, options.query);
+        const headers = new Headers();
+        headers.set("accessToken", this.accessToken);
+        if (options.userId) {
+            headers.set("userId", options.userId);
+        }
+        const init = {
+            method: params.method,
+            headers
+        };
+        if (options.body !== undefined) {
+            headers.set("content-type", "application/json");
+            init.body = JSON.stringify(options.body);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        init.signal = controller.signal;
+        try {
+            const response = await fetch(url, init);
+            const text = await response.text();
+            const data = safeJsonParse(text);
+            if (!response.ok) {
+                throw new QingflowApiError({
+                    message: `Qingflow HTTP ${response.status}`,
+                    httpStatus: response.status,
+                    errMsg: extractErrMsg(data, text),
+                    details: data ?? text
+                });
+            }
+            if (!data || typeof data !== "object") {
+                throw new QingflowApiError({
+                    message: "Qingflow response is not JSON object",
+                    httpStatus: response.status,
+                    details: text
+                });
+            }
+            const parsed = parseResponseEnvelope(data);
+            if (parsed.errCode === null) {
+                throw new QingflowApiError({
+                    message: "Qingflow response missing code field",
+                    httpStatus: response.status,
+                    details: data
+                });
+            }
+            if (parsed.errCode !== 0) {
+                throw new QingflowApiError({
+                    message: `Qingflow API error ${parsed.errCode}: ${parsed.errMsg}`,
+                    errCode: parsed.errCode,
+                    errMsg: parsed.errMsg,
+                    httpStatus: response.status,
+                    details: data
+                });
+            }
+            return {
+                errCode: parsed.errCode,
+                errMsg: parsed.errMsg,
+                result: parsed.result
+            };
+        }
+        catch (error) {
+            if (error instanceof QingflowApiError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new QingflowApiError({
+                    message: `Qingflow request timeout after ${this.timeoutMs}ms`
+                });
+            }
+            throw new QingflowApiError({
+                message: error instanceof Error ? error.message : "Unknown request error",
+                details: error
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function normalizeBaseUrl(url) {
+    const normalized = url.trim();
+    if (!normalized) {
+        throw new Error("QINGFLOW_BASE_URL is required");
+    }
+    return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+function normalizeAccessToken(token) {
+    const normalized = token.trim();
+    if (!normalized) {
+        throw new Error("QINGFLOW_ACCESS_TOKEN is required");
+    }
+    if (/[\r\n]/.test(normalized)) {
+        throw new Error("QINGFLOW_ACCESS_TOKEN contains newline characters");
+    }
+    if (/[\u0100-\uFFFF]/.test(normalized)) {
+        throw new Error("QINGFLOW_ACCESS_TOKEN contains non-ASCII characters; please paste raw token only");
+    }
+    return normalized;
+}
+function appendQuery(url, query) {
+    if (!query) {
+        return;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function extractErrMsg(json, rawText) {
+    if (json && typeof json === "object") {
+        const obj = json;
+        const msgCandidates = [obj.errMsg, obj.errorMsg, obj.message];
+        for (const msg of msgCandidates) {
+            if (typeof msg === "string" && msg.trim()) {
+                return msg;
+            }
+        }
+    }
+    const sample = rawText.trim().slice(0, 200);
+    return sample || "request failed";
+}
+function parseResponseEnvelope(data) {
+    const codeCandidates = [data.errCode, data.errorCode, data.statusCode];
+    let errCode = null;
+    for (const candidate of codeCandidates) {
+        const parsed = toFiniteNumber(candidate);
+        if (parsed !== null) {
+            errCode = parsed;
+            break;
+        }
+    }
+    const messageCandidates = [data.errMsg, data.errorMsg, data.message];
+    let errMsg = "";
+    for (const candidate of messageCandidates) {
+        if (typeof candidate === "string" && candidate.trim()) {
+            errMsg = candidate.trim();
+            break;
+        }
+    }
+    return {
+        errCode,
+        errMsg,
+        result: data.result
+    };
+}
+function toFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return null;
+}

package/dist/server.js

@@ -0,0 +1,889 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { QingflowApiError, QingflowClient } from "./qingflow-client.js";
+const MODE_TO_TYPE = {
+    todo: 1,
+    done: 2,
+    mine_approved: 3,
+    mine_rejected: 4,
+    mine_draft: 5,
+    mine_need_improve: 6,
+    mine_processing: 7,
+    all: 8,
+    all_approved: 9,
+    all_rejected: 10,
+    all_processing: 11,
+    cc: 12
+};
+const FORM_CACHE_TTL_MS = Number(process.env.QINGFLOW_FORM_CACHE_TTL_MS ?? "300000");
+const formCache = new Map();
+const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
+const baseUrl = process.env.QINGFLOW_BASE_URL;
+if (!accessToken) {
+    throw new Error("QINGFLOW_ACCESS_TOKEN is required");
+}
+if (!baseUrl) {
+    throw new Error("QINGFLOW_BASE_URL is required");
+}
+const client = new QingflowClient({
+    accessToken,
+    baseUrl
+});
+const server = new McpServer({
+    name: "qingflow-mcp",
+    version: "0.2.0"
+});
+const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const answerValueSchema = z.union([
+    jsonPrimitiveSchema,
+    z
+        .object({
+        value: z.unknown().optional(),
+        dataValue: z.unknown().optional(),
+        id: z.union([z.string(), z.number()]).optional(),
+        email: z.string().optional(),
+        optionId: z.union([z.string(), z.number()]).optional(),
+        otherInfo: z.string().optional(),
+        queId: z.union([z.string(), z.number()]).optional(),
+        valueStr: z.string().optional(),
+        matchValue: z.unknown().optional(),
+        ordinal: z.union([z.number(), z.string()]).optional(),
+        pluginValue: z.unknown().optional()
+    })
+        .passthrough()
+]);
+const answerInputSchema = z
+    .object({
+    que_id: z.union([z.string().min(1), z.number().int()]).optional(),
+    queId: z.union([z.string().min(1), z.number().int()]).optional(),
+    que_title: z.string().optional(),
+    queTitle: z.string().optional(),
+    que_type: z.unknown().optional(),
+    queType: z.unknown().optional(),
+    value: answerValueSchema.optional(),
+    values: z.array(answerValueSchema).optional(),
+    table_values: z.array(z.array(z.unknown())).optional(),
+    tableValues: z.array(z.array(z.unknown())).optional()
+})
+    .passthrough()
+    .refine((value) => Boolean(value.que_id ?? value.queId), {
+    message: "answer item requires que_id or queId"
+})
+    .refine((value) => value.value !== undefined ||
+    value.values !== undefined ||
+    value.table_values !== undefined ||
+    value.tableValues !== undefined, {
+    message: "answer item requires value(s) or table_values"
+});
+const fieldValueSchema = z.union([
+    jsonPrimitiveSchema,
+    z.array(z.unknown()),
+    z.record(z.unknown())
+]);
+const apiMetaSchema = z.object({
+    provider_err_code: z.number(),
+    provider_err_msg: z.string().nullable(),
+    base_url: z.string()
+});
+const appSchema = z.object({
+    appKey: z.string(),
+    appName: z.string()
+});
+const fieldSummarySchema = z.object({
+    que_id: z.union([z.number(), z.string(), z.null()]),
+    que_title: z.string().nullable(),
+    que_type: z.unknown(),
+    has_sub_fields: z.boolean(),
+    sub_field_count: z.number().int().nonnegative()
+});
+const recordItemSchema = z.object({
+    apply_id: z.union([z.string(), z.number(), z.null()]),
+    app_key: z.string().nullable(),
+    apply_num: z.union([z.number(), z.string(), z.null()]),
+    apply_time: z.string().nullable(),
+    last_update_time: z.string().nullable(),
+    answers: z.array(z.unknown()).optional()
+});
+const operationResultSchema = z.object({
+    request_id: z.string(),
+    operation_result: z.unknown()
+});
+const appsInputSchema = z.object({
+    user_id: z.string().min(1).optional(),
+    favourite: z.union([z.literal(0), z.literal(1)]).optional(),
+    keyword: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+});
+const appsOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        total_apps: z.number().int().nonnegative(),
+        returned_apps: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        apps: z.array(appSchema)
+    }),
+    meta: apiMetaSchema
+});
+const formInputSchema = z.object({
+    app_key: z.string().min(1),
+    user_id: z.string().min(1).optional(),
+    force_refresh: z.boolean().optional(),
+    include_raw: z.boolean().optional()
+});
+const formOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        app_key: z.string(),
+        total_fields: z.number().int().nonnegative(),
+        field_summaries: z.array(fieldSummarySchema),
+        form: z.unknown().optional()
+    }),
+    meta: apiMetaSchema
+});
+const listInputSchema = z.object({
+    app_key: z.string().min(1),
+    user_id: z.string().min(1).optional(),
+    page_num: z.number().int().positive().optional(),
+    page_size: z.number().int().positive().max(200).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.number().int().min(1).max(12).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.enum(["and", "or"]).optional(),
+    apply_ids: z.array(z.union([z.string(), z.number()])).optional(),
+    sort: z
+        .array(z.object({
+        que_id: z.union([z.string().min(1), z.number().int()]),
+        ascend: z.boolean().optional()
+    }))
+        .optional(),
+    filters: z
+        .array(z.object({
+        que_id: z.union([z.string().min(1), z.number().int()]).optional(),
+        search_key: z.string().optional(),
+        search_keys: z.array(z.string()).optional(),
+        min_value: z.string().optional(),
+        max_value: z.string().optional(),
+        scope: z.number().int().optional(),
+        search_options: z.array(z.union([z.string(), z.number()])).optional(),
+        search_user_ids: z.array(z.string()).optional()
+    }))
+        .optional(),
+    include_answers: z.boolean().optional()
+});
+const listOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        app_key: z.string(),
+        pagination: z.object({
+            page_num: z.number().int().positive(),
+            page_size: z.number().int().positive(),
+            page_amount: z.number().int().nonnegative().nullable(),
+            result_amount: z.number().int().nonnegative()
+        }),
+        items: z.array(recordItemSchema)
+    }),
+    meta: apiMetaSchema
+});
+const recordGetInputSchema = z.object({
+    apply_id: z.union([z.string().min(1), z.number().int()])
+});
+const recordGetOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        apply_id: z.union([z.string(), z.number(), z.null()]),
+        answer_count: z.number().int().nonnegative(),
+        record: z.unknown()
+    }),
+    meta: apiMetaSchema
+});
+const createInputSchema = z
+    .object({
+    app_key: z.string().min(1),
+    user_id: z.string().min(1).optional(),
+    force_refresh_form: z.boolean().optional(),
+    apply_user: z
+        .object({
+        email: z.string().optional(),
+        areaCode: z.string().optional(),
+        mobile: z.string().optional()
+    })
+        .passthrough()
+        .optional(),
+    answers: z.array(answerInputSchema).optional(),
+    fields: z.record(fieldValueSchema).optional()
+})
+    .refine((value) => hasWritePayload(value.answers, value.fields), {
+    message: "Either answers or fields is required"
+});
+const createOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        request_id: z.string().nullable(),
+        apply_id: z.union([z.string(), z.number(), z.null()]),
+        async_hint: z.string()
+    }),
+    meta: apiMetaSchema
+});
+const updateInputSchema = z
+    .object({
+    apply_id: z.union([z.string().min(1), z.number().int()]),
+    app_key: z.string().min(1).optional(),
+    user_id: z.string().min(1).optional(),
+    force_refresh_form: z.boolean().optional(),
+    answers: z.array(answerInputSchema).optional(),
+    fields: z.record(fieldValueSchema).optional()
+})
+    .refine((value) => hasWritePayload(value.answers, value.fields), {
+    message: "Either answers or fields is required"
+});
+const updateOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        request_id: z.string().nullable(),
+        async_hint: z.string()
+    }),
+    meta: apiMetaSchema
+});
+const operationInputSchema = z.object({
+    request_id: z.string().min(1)
+});
+const operationOutputSchema = z.object({
+    ok: z.literal(true),
+    data: operationResultSchema,
+    meta: apiMetaSchema
+});
+server.registerTool("qf_apps_list", {
+    title: "Qingflow Apps List",
+    description: "List Qingflow apps with optional filtering and client-side slicing.",
+    inputSchema: appsInputSchema,
+    outputSchema: appsOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const response = await client.listApps({
+            userId: args.user_id,
+            favourite: args.favourite
+        });
+        const appList = asArray(asObject(response.result)?.appList)
+            .map((item) => asObject(item))
+            .filter((item) => Boolean(item))
+            .map((item) => ({
+            appKey: String(item.appKey ?? ""),
+            appName: String(item.appName ?? "")
+        }))
+            .filter((item) => item.appKey.length > 0);
+        const keyword = args.keyword?.trim().toLowerCase();
+        const filtered = keyword
+            ? appList.filter((item) => item.appKey.toLowerCase().includes(keyword) ||
+                item.appName.toLowerCase().includes(keyword))
+            : appList;
+        const offset = args.offset ?? 0;
+        const limit = args.limit ?? 50;
+        const apps = filtered.slice(offset, offset + limit);
+        return okResult({
+            ok: true,
+            data: {
+                total_apps: filtered.length,
+                returned_apps: apps.length,
+                limit,
+                offset,
+                apps
+            },
+            meta: buildMeta(response)
+        }, `Returned ${apps.length}/${filtered.length} apps`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_form_get", {
+    title: "Qingflow Form Get",
+    description: "Get form metadata and compact field summaries for one app.",
+    inputSchema: formInputSchema,
+    outputSchema: formOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const response = await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh));
+        const form = asObject(response.result);
+        const fieldSummaries = extractFieldSummaries(form);
+        return okResult({
+            ok: true,
+            data: {
+                app_key: args.app_key,
+                total_fields: fieldSummaries.length,
+                field_summaries: fieldSummaries,
+                ...(args.include_raw ? { form: response.result } : {})
+            },
+            meta: buildMeta(response)
+        }, `Fetched form for ${args.app_key}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_records_list", {
+    title: "Qingflow Records List",
+    description: "List records with pagination, filters and sorting.",
+    inputSchema: listInputSchema,
+    outputSchema: listOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const payload = buildListPayload({
+            pageNum: args.page_num ?? 1,
+            pageSize: args.page_size ?? 50,
+            mode: args.mode,
+            type: args.type,
+            keyword: args.keyword,
+            queryLogic: args.query_logic,
+            applyIds: args.apply_ids,
+            sort: args.sort,
+            filters: args.filters
+        });
+        const response = await client.listRecords(args.app_key, payload, { userId: args.user_id });
+        const result = asObject(response.result);
+        const rawItems = asArray(result?.result);
+        const includeAnswers = Boolean(args.include_answers);
+        const items = rawItems.map((raw) => normalizeRecordItem(raw, includeAnswers));
+        return okResult({
+            ok: true,
+            data: {
+                app_key: args.app_key,
+                pagination: {
+                    page_num: toPositiveInt(result?.pageNum) ?? (args.page_num ?? 1),
+                    page_size: toPositiveInt(result?.pageSize) ?? (args.page_size ?? 50),
+                    page_amount: toNonNegativeInt(result?.pageAmount),
+                    result_amount: toNonNegativeInt(result?.resultAmount) ?? items.length
+                },
+                items
+            },
+            meta: buildMeta(response)
+        }, `Fetched ${items.length} records`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_record_get", {
+    title: "Qingflow Record Get",
+    description: "Get one record by applyId.",
+    inputSchema: recordGetInputSchema,
+    outputSchema: recordGetOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const response = await client.getRecord(String(args.apply_id));
+        const record = asObject(response.result) ?? {};
+        const answerCount = asArray(record.answers).length;
+        return okResult({
+            ok: true,
+            data: {
+                apply_id: record.applyId ?? null,
+                answer_count: answerCount,
+                record: response.result
+            },
+            meta: buildMeta(response)
+        }, `Fetched record ${String(args.apply_id)}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_record_create", {
+    title: "Qingflow Record Create",
+    description: "Create one record. Supports explicit answers and ergonomic fields mapping (title or queId).",
+    inputSchema: createInputSchema,
+    outputSchema: createOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        idempotentHint: false
+    }
+}, async (args) => {
+    try {
+        const form = needsFormResolution(args.fields) || Boolean(args.force_refresh_form)
+            ? await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh_form))
+            : null;
+        const normalizedAnswers = resolveAnswers({
+            explicitAnswers: args.answers,
+            fields: args.fields,
+            form: form?.result
+        });
+        const payload = {
+            answers: normalizedAnswers
+        };
+        if (args.apply_user) {
+            payload.applyUser = args.apply_user;
+        }
+        const response = await client.createRecord(args.app_key, payload, {
+            userId: args.user_id
+        });
+        const result = asObject(response.result);
+        return okResult({
+            ok: true,
+            data: {
+                request_id: asNullableString(result?.requestId),
+                apply_id: result?.applyId ?? null,
+                async_hint: "Use qf_operation_get with request_id when apply_id is null."
+            },
+            meta: buildMeta(response)
+        }, `Create request sent for app ${args.app_key}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_record_update", {
+    title: "Qingflow Record Update",
+    description: "Patch one record by applyId with explicit answers or ergonomic fields mapping.",
+    inputSchema: updateInputSchema,
+    outputSchema: updateOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        idempotentHint: false
+    }
+}, async (args) => {
+    try {
+        const requiresForm = needsFormResolution(args.fields);
+        if (requiresForm && !args.app_key) {
+            throw new Error("app_key is required when fields uses title-based keys");
+        }
+        const form = requiresForm && args.app_key
+            ? await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh_form))
+            : null;
+        const normalizedAnswers = resolveAnswers({
+            explicitAnswers: args.answers,
+            fields: args.fields,
+            form: form?.result
+        });
+        const response = await client.updateRecord(String(args.apply_id), { answers: normalizedAnswers }, { userId: args.user_id });
+        const result = asObject(response.result);
+        return okResult({
+            ok: true,
+            data: {
+                request_id: asNullableString(result?.requestId),
+                async_hint: "Use qf_operation_get with request_id to fetch update result when needed."
+            },
+            meta: buildMeta(response)
+        }, `Update request sent for apply ${String(args.apply_id)}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_operation_get", {
+    title: "Qingflow Operation Get",
+    description: "Resolve async operation result by request_id.",
+    inputSchema: operationInputSchema,
+    outputSchema: operationOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const response = await client.getOperation(args.request_id);
+        return okResult({
+            ok: true,
+            data: {
+                request_id: args.request_id,
+                operation_result: response.result
+            },
+            meta: buildMeta(response)
+        }, `Resolved operation ${args.request_id}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+void main();
+function hasWritePayload(answers, fields) {
+    return Boolean((answers && answers.length > 0) || (fields && Object.keys(fields).length > 0));
+}
+function buildMeta(response) {
+    return {
+        provider_err_code: response.errCode,
+        provider_err_msg: response.errMsg || null,
+        base_url: baseUrl
+    };
+}
+function buildListPayload(params) {
+    const payload = {
+        pageNum: params.pageNum,
+        pageSize: params.pageSize
+    };
+    if (params.mode) {
+        payload.type = MODE_TO_TYPE[params.mode];
+    }
+    else if (params.type !== undefined) {
+        payload.type = params.type;
+    }
+    if (params.keyword) {
+        payload.queryKey = params.keyword;
+    }
+    if (params.queryLogic) {
+        payload.queriesRel = params.queryLogic;
+    }
+    if (params.applyIds?.length) {
+        payload.applyIds = params.applyIds.map((id) => String(id));
+    }
+    if (params.sort?.length) {
+        payload.sorts = params.sort.map((item) => ({
+            queId: item.que_id,
+            ...(item.ascend !== undefined ? { isAscend: item.ascend } : {})
+        }));
+    }
+    if (params.filters?.length) {
+        payload.queries = params.filters.map((item) => ({
+            ...(item.que_id !== undefined ? { queId: item.que_id } : {}),
+            ...(item.search_key !== undefined ? { searchKey: item.search_key } : {}),
+            ...(item.search_keys !== undefined ? { searchKeys: item.search_keys } : {}),
+            ...(item.min_value !== undefined ? { minValue: item.min_value } : {}),
+            ...(item.max_value !== undefined ? { maxValue: item.max_value } : {}),
+            ...(item.scope !== undefined ? { scope: item.scope } : {}),
+            ...(item.search_options !== undefined ? { searchOptions: item.search_options } : {}),
+            ...(item.search_user_ids !== undefined ? { searchUserIds: item.search_user_ids } : {})
+        }));
+    }
+    return payload;
+}
+function normalizeRecordItem(raw, includeAnswers) {
+    const item = asObject(raw) ?? {};
+    const normalized = {
+        apply_id: item.applyId ?? null,
+        app_key: asNullableString(item.appKey),
+        apply_num: item.applyNum ?? null,
+        apply_time: asNullableString(item.applyTime),
+        last_update_time: asNullableString(item.lastUpdateTime),
+        ...(includeAnswers ? { answers: asArray(item.answers) } : {})
+    };
+    return normalized;
+}
+function resolveAnswers(params) {
+    const normalizedFromFields = resolveFieldAnswers(params.fields, params.form);
+    const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers);
+    const merged = new Map();
+    for (const answer of normalizedFromFields) {
+        merged.set(String(answer.queId), answer);
+    }
+    for (const answer of normalizedExplicit) {
+        merged.set(String(answer.queId), answer);
+    }
+    if (merged.size === 0) {
+        throw new Error("answers or fields must contain at least one field");
+    }
+    return Array.from(merged.values());
+}
+function normalizeExplicitAnswers(answers) {
+    if (!answers?.length) {
+        return [];
+    }
+    const output = [];
+    for (const item of answers) {
+        const queId = item.que_id ?? item.queId;
+        if (queId === undefined || queId === null || String(queId).trim() === "") {
+            throw new Error("answer item requires que_id or queId");
+        }
+        const normalized = {
+            queId: isNumericKey(String(queId)) ? Number(queId) : String(queId)
+        };
+        const queTitle = item.que_title ?? item.queTitle;
+        if (typeof queTitle === "string" && queTitle.trim()) {
+            normalized.queTitle = queTitle;
+        }
+        const queType = item.que_type ?? item.queType;
+        if (queType !== undefined) {
+            normalized.queType = queType;
+        }
+        const tableValues = item.table_values ?? item.tableValues;
+        if (tableValues !== undefined) {
+            normalized.tableValues = tableValues;
+            output.push(normalized);
+            continue;
+        }
+        const values = item.values ?? (item.value !== undefined ? [item.value] : undefined);
+        if (values === undefined) {
+            throw new Error(`answer item ${String(queId)} requires values or table_values`);
+        }
+        normalized.values = values.map((value) => normalizeAnswerValue(value));
+        output.push(normalized);
+    }
+    return output;
+}
+function resolveFieldAnswers(fields, form) {
+    const entries = Object.entries(fields ?? {});
+    if (entries.length === 0) {
+        return [];
+    }
+    const index = buildFieldIndex(form);
+    const answers = [];
+    for (const [fieldKey, fieldValue] of entries) {
+        const field = resolveFieldByKey(fieldKey, index);
+        if (!field) {
+            throw new Error(`Cannot resolve field key "${fieldKey}" from form metadata`);
+        }
+        answers.push(makeAnswerFromField(field, fieldValue));
+    }
+    return answers;
+}
+function makeAnswerFromField(field, value) {
+    const base = {
+        queId: field.queId
+    };
+    if (field.queTitle !== undefined) {
+        base.queTitle = field.queTitle;
+    }
+    if (field.queType !== undefined) {
+        base.queType = field.queType;
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const objectValue = value;
+        if ("tableValues" in objectValue || "table_values" in objectValue) {
+            return {
+                ...base,
+                tableValues: objectValue.tableValues ?? objectValue.table_values
+            };
+        }
+        if ("values" in objectValue) {
+            return {
+                ...base,
+                values: asArray(objectValue.values).map((item) => normalizeAnswerValue(item))
+            };
+        }
+    }
+    if (Array.isArray(value) && value.length > 0 && Array.isArray(value[0])) {
+        return {
+            ...base,
+            tableValues: value
+        };
+    }
+    const valueArray = Array.isArray(value) ? value : [value];
+    return {
+        ...base,
+        values: valueArray.map((item) => normalizeAnswerValue(item))
+    };
+}
+function normalizeAnswerValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return {
+            value,
+            dataValue: value
+        };
+    }
+    return value;
+}
+function needsFormResolution(fields) {
+    const keys = Object.keys(fields ?? {});
+    if (!keys.length) {
+        return false;
+    }
+    return keys.some((key) => !isNumericKey(key));
+}
+async function getFormCached(appKey, userId, forceRefresh = false) {
+    const cacheKey = `${appKey}::${userId ?? ""}`;
+    if (!forceRefresh) {
+        const cached = formCache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.data;
+        }
+    }
+    const response = await client.getForm(appKey, { userId });
+    formCache.set(cacheKey, {
+        expiresAt: Date.now() + FORM_CACHE_TTL_MS,
+        data: response
+    });
+    return response;
+}
+function extractFieldSummaries(form) {
+    const root = asArray(form?.questionBaseInfos);
+    return root.map((raw) => {
+        const field = asObject(raw) ?? {};
+        const sub = asArray(field.subQuestionBaseInfos);
+        return {
+            que_id: field.queId ?? null,
+            que_title: asNullableString(field.queTitle),
+            que_type: field.queType,
+            has_sub_fields: sub.length > 0,
+            sub_field_count: sub.length
+        };
+    });
+}
+function buildFieldIndex(form) {
+    const byId = new Map();
+    const byTitle = new Map();
+    const root = asArray(asObject(form)?.questionBaseInfos);
+    const queue = [...root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        if (current.queId !== undefined && current.queId !== null) {
+            byId.set(String(current.queId), current);
+        }
+        if (typeof current.queTitle === "string" && current.queTitle.trim()) {
+            const titleKey = current.queTitle.trim().toLowerCase();
+            const list = byTitle.get(titleKey) ?? [];
+            list.push(current);
+            byTitle.set(titleKey, list);
+        }
+        const sub = asArray(current.subQuestionBaseInfos);
+        for (const child of sub) {
+            queue.push(child);
+        }
+    }
+    return { byId, byTitle };
+}
+function resolveFieldByKey(fieldKey, index) {
+    if (isNumericKey(fieldKey)) {
+        const normalized = String(Number(fieldKey));
+        const hit = index.byId.get(normalized);
+        if (hit) {
+            return hit;
+        }
+        return { queId: Number(fieldKey) };
+    }
+    const titleKey = fieldKey.trim().toLowerCase();
+    const matches = index.byTitle.get(titleKey) ?? [];
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        const candidateIds = matches.map((item) => String(item.queId)).join(", ");
+        throw new Error(`Field title "${fieldKey}" is ambiguous. Candidate queId: ${candidateIds}`);
+    }
+    return null;
+}
+function isNumericKey(value) {
+    return /^\d+$/.test(value.trim());
+}
+function okResult(payload, message) {
+    return {
+        structuredContent: payload,
+        content: [
+            {
+                type: "text",
+                text: message
+            }
+        ]
+    };
+}
+function errorResult(error) {
+    const payload = toErrorPayload(error);
+    return {
+        isError: true,
+        structuredContent: payload,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2)
+            }
+        ]
+    };
+}
+function toErrorPayload(error) {
+    if (error instanceof QingflowApiError) {
+        return {
+            ok: false,
+            message: error.message,
+            err_code: error.errCode,
+            err_msg: error.errMsg || null,
+            http_status: error.httpStatus,
+            details: error.details ?? null
+        };
+    }
+    if (error instanceof z.ZodError) {
+        return {
+            ok: false,
+            message: "Invalid arguments",
+            issues: error.issues
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            ok: false,
+            message: error.message
+        };
+    }
+    return {
+        ok: false,
+        message: "Unknown error",
+        details: error
+    };
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function toPositiveInt(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function toNonNegativeInt(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isInteger(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function asNullableString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "qingflow-mcp",
+  "version": "0.2.0",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "description": "MCP server for Qingflow CRUD workflows",
+  "author": "Yanqi Dong",
+  "homepage": "https://github.com/853046310/qingflow-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/853046310/qingflow-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/853046310/qingflow-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "qingflow",
+    "openapi",
+    "automation",
+    "agent"
+  ],
+  "bin": {
+    "qingflow-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/server.ts",
+    "start": "node dist/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}