k3cloud-query-mcp 1.0.0__py3-none-any.whl

k3cloud_query_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""k3cloud-query-mcp — 金蝶云星空 K3Cloud MCP 查询服务（纯查询版）"""
+
+__version__ = "1.0.0"

k3cloud_query_mcp/server.py

@@ -0,0 +1,764 @@
+"""
+k3cloud-query-mcp — 金蝶云星空 K3Cloud MCP 查询服务（纯查询版）
+
+从 kingdee-k3cloud-mcp 派生，仅保留查询（只读）工具，移除所有写入/操作工具。
+"""
+
+import csv
+import json
+import logging
+import os
+import sys
+import time
+from collections.abc import Iterator
+from datetime import date, timedelta
+from pathlib import Path
+
+from dotenv import load_dotenv
+from k3cloud_webapi_sdk.const.const_define import InvokeMethod
+from k3cloud_webapi_sdk.main import K3CloudApiSdk
+from k3cloud_webapi_sdk.model.cookie_store import CookieStore
+from mcp.server.auth.provider import AccessToken
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+SESSION_LOST_MSG = "会话信息已丢失"
+
+# SDK instance: initialized in setup() after environment is validated.
+api_sdk: "RetryableK3CloudApiSdk | None" = None
+
+
+def _sdk() -> "RetryableK3CloudApiSdk":
+    """Return the initialized SDK, asserting it is not None."""
+    assert api_sdk is not None, "api_sdk not initialized — call setup() first"
+    return api_sdk
+
+
+class ApiKeyVerifier:
+    """验证静态 API Key（Bearer Token）。
+
+    仅在 SSE/streamable-http 传输时生效；MCP_API_KEY 未设置时禁用鉴权。
+    """
+
+    def __init__(self, api_key: str):
+        self._key = api_key
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        if token == self._key:
+            return AccessToken(token=token, client_id="api-key-client", scopes=[])
+        return None
+
+
+mcp = FastMCP("k3cloud-query")
+
+
+# ---------------------------------------------------------------------------
+# 内部辅助函数
+# ---------------------------------------------------------------------------
+
+def _check_expired(data) -> bool:
+    if isinstance(data, list):
+        return any(_check_expired(item) for item in data)
+    if isinstance(data, dict):
+        errors = (data.get("Result") or {}).get("ResponseStatus", {}).get("Errors", [])
+        return any(SESSION_LOST_MSG in (e.get("Message") or "") for e in errors)
+    return False
+
+
+def _is_session_expired(result: str) -> bool:
+    try:
+        return _check_expired(json.loads(result))
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return False
+
+
+class RetryableK3CloudApiSdk(K3CloudApiSdk):
+    """K3CloudApiSdk with automatic session recovery on expiry.
+
+    When K3Cloud returns "会话信息已丢失", the recovery flow is:
+      1. If the last session reset was more than _RESET_COOLDOWN seconds ago:
+         clear cookiesStore so BuildHeader() sends no session headers on retry.
+         The retry call lets the server issue a fresh SID (stored by
+         FillCookieAndHeader), even though the response body still reports
+         "session lost" while the new session activates server-side.
+      2. If we reset recently (within cooldown), skip clearing — the freshly
+         issued SID is preserved and retried directly.
+
+    Rapid consecutive resets would destroy each newly-issued SID before it
+    activates, so the 300-second cooldown keeps the latest SID intact until
+    the server accepts it.
+    """
+
+    _RESET_COOLDOWN = 300  # seconds
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._session_reset_at = 0.0
+
+    def Execute(self, service_name, json_data=None, invoke_type=InvokeMethod.SYNC):
+        result = super().Execute(service_name, json_data, invoke_type)
+        if isinstance(result, str) and _is_session_expired(result):
+            now = time.monotonic()
+            if now - self._session_reset_at >= self._RESET_COOLDOWN:
+                logger.warning("[k3cloud] session expired, re-establishing SID...")
+                self._session_reset_at = now
+                if hasattr(self, "cookiesStore"):
+                    self.cookiesStore = CookieStore()
+                else:
+                    logger.warning(
+                        "[k3cloud] SDK internals changed: cookiesStore not found, cannot reset SID"
+                    )
+                super().Execute(
+                    service_name, json_data, invoke_type
+                )  # establishes SID, result discarded
+            else:
+                logger.warning("[k3cloud] session recovering, SID not yet active — skipping retry")
+        return result
+
+
+# ---------------------------------------------------------------------------
+# 结果包装 & 翻页
+# ---------------------------------------------------------------------------
+
+def _wrap_query_result(raw: str, top_count: int, limit: int, start_row: int) -> str:
+    """将 SDK 查询结果包装为带分页元数据的 envelope。
+
+    仅对成功的列表响应生效；错误响应（如会话过期）原样透传。
+
+    返回格式：
+        {
+          "rows": [...原始数据...],
+          "row_count": N,
+          "truncated": true/false,
+          "next_start_row": N,   # 仅 truncated=true 时存在
+          "hint": "..."          # 仅 truncated=true 时存在
+        }
+    """
+    if _is_session_expired(raw):
+        return raw
+
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return raw
+
+    if not isinstance(data, list):
+        return raw
+
+    row_count = len(data)
+    cap = top_count if top_count > 0 else limit
+    truncated = row_count > 0 and row_count >= cap
+
+    result: dict = {
+        "rows": data,
+        "row_count": row_count,
+        "truncated": truncated,
+    }
+    if truncated:
+        result["next_start_row"] = start_row + row_count
+        result["hint"] = (
+            f"返回行数已达上限（{cap} 行），数据可能被截断。"
+            f"请用 start_row={start_row + row_count} 继续翻页获取下一页数据。"
+        )
+
+    return json.dumps(result, ensure_ascii=False)
+
+
+def _paginate_bill(
+    params: dict, page_size: int, max_rows: int
+) -> "tuple[list, bool, int, str | None]":
+    """内部翻页原语。返回 (rows, exhausted, next_start_row, error_raw)。"""
+    rows: list = []
+    initial_start = params.get("StartRow", 0)
+    current_start = initial_start
+
+    while True:
+        page_params = {
+            **params,
+            "StartRow": current_start,
+            "TopRowCount": current_start + page_size,
+            "Limit": page_size,
+        }
+        raw = _sdk().BillQuery(page_params)
+
+        if _is_session_expired(raw):
+            return rows, False, current_start, raw
+
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return rows, False, current_start, raw
+
+        if not isinstance(data, list):
+            return rows, False, current_start, raw
+
+        rows.extend(data)
+        page_count = len(data)
+
+        if len(rows) >= max_rows:
+            rows = rows[:max_rows]
+            return rows, False, initial_start + max_rows, None
+
+        if page_count < page_size:
+            return rows, True, initial_start + len(rows), None
+
+        current_start += page_size
+
+
+def _iter_date_chunks(date_from: str, date_to: str, chunk: str) -> "Iterator[tuple[str, str]]":
+    """将 [date_from, date_to) 切成 N 个半开区间。chunk ∈ {'month','week','day'}。"""
+    if chunk not in {"month", "week", "day"}:
+        raise ValueError(f"chunk 必须是 month/week/day，收到: {chunk!r}")
+    try:
+        current = date.fromisoformat(date_from)
+        end = date.fromisoformat(date_to)
+    except ValueError as e:
+        raise ValueError(f"日期格式错误（需要 YYYY-MM-DD）: {e}") from e
+    if end <= current:
+        raise ValueError("date_to 必须晚于 date_from")
+
+    while current < end:
+        if chunk == "month":
+            if current.month == 12:
+                next_dt = date(current.year + 1, 1, 1)
+            else:
+                next_dt = date(current.year, current.month + 1, 1)
+        elif chunk == "week":
+            next_dt = current + timedelta(weeks=1)
+        else:
+            next_dt = current + timedelta(days=1)
+        chunk_end = min(next_dt, end)
+        yield current.isoformat(), chunk_end.isoformat()
+        current = chunk_end
+
+
+def _stream_to_file_handle(
+    f,
+    params: dict,
+    page_size: int,
+    max_rows: int,
+    fields: list,
+    fmt: str,
+    header_written: bool,
+) -> "tuple[int, bool, str | None]":
+    """将分页查询结果流式追加写入已打开的文件句柄。
+
+    Returns:
+        (rows_written, header_written, error_raw)
+    """
+    writer = csv.writer(f) if fmt == "csv" else None
+    rows_written = 0
+    current_start = params.get("StartRow", 0)
+
+    while True:
+        page_params = {
+            **params,
+            "StartRow": current_start,
+            "TopRowCount": current_start + page_size,
+            "Limit": page_size,
+        }
+        raw = _sdk().BillQuery(page_params)
+
+        if _is_session_expired(raw):
+            return rows_written, header_written, raw
+
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return rows_written, header_written, raw
+
+        if not isinstance(data, list):
+            return rows_written, header_written, raw
+
+        for row in data:
+            if fmt == "ndjson":
+                f.write(json.dumps(row, ensure_ascii=False) + "\n")
+            elif writer is not None:
+                if not header_written:
+                    writer.writerow(fields)
+                    header_written = True
+                writer.writerow([row.get(field, "") for field in fields])
+            rows_written += 1
+            if rows_written >= max_rows:
+                return rows_written, header_written, None
+
+        if len(data) < page_size:
+            break
+
+        current_start += page_size
+
+    return rows_written, header_written, None
+
+
+# ===================================================================
+# 查询工具（只读）
+# ===================================================================
+
+@mcp.tool()
+def query_bill(
+    form_id: str,
+    field_keys: str,
+    filter_string: str = "",
+    order_string: str = "",
+    top_count: int = 100,
+    start_row: int = 0,
+    limit: int = 2000,
+) -> str:
+    """查询金蝶云星空单据数据（返回二维数组）。
+
+    Args:
+        form_id: 表单ID。常用值：
+            BD_MATERIAL(物料)、BD_Customer(客户)、BD_Supplier(供应商)、
+            SAL_SaleOrder(销售订单)、PUR_PurchaseOrder(采购订单)、
+            STK_InStock(入库单)、STK_OutStock(出库单)、GL_VOUCHER(凭证)
+        field_keys: 查询字段，逗号分隔。如 "FName,FNumber"
+        filter_string: 过滤条件。如 "FNumber like 'MAT%'"
+        order_string: 排序字段。如 "FNumber ASC"
+        top_count: 本次最多返回行数，默认100。映射到金蝶 TopRowCount（绝对终止行号 = start_row + top_count），
+            同时作为金蝶 Limit（单次页大小）。设为 0 表示不限制行数（仅靠 limit 控制）。
+        start_row: 起始行号，默认0。翻页时传入上一次返回的 next_start_row。
+        limit: 仅在 top_count=0 时生效，作为金蝶 Limit 页大小上限，默认2000。
+            top_count>0 时此参数被忽略（页大小由 top_count 决定）。
+    """
+    raw = _sdk().ExecuteBillQuery(
+        {
+            "FormId": form_id,
+            "FieldKeys": field_keys,
+            "FilterString": filter_string,
+            "OrderString": order_string,
+            "TopRowCount": (start_row + top_count) if top_count > 0 else 0,
+            "StartRow": start_row,
+            "Limit": top_count if top_count > 0 else limit,
+        }
+    )
+    return _wrap_query_result(raw, top_count, limit, start_row)
+
+
+@mcp.tool()
+def query_bill_json(
+    form_id: str,
+    field_keys: str,
+    filter_string: str = "",
+    order_string: str = "",
+    top_count: int = 100,
+    start_row: int = 0,
+    limit: int = 2000,
+) -> str:
+    """查询金蝶云星空单据数据（返回JSON格式，字段名作为key）。
+
+    与 query_bill 的区别：返回结果是JSON对象数组，每条记录的字段名作为key，更易读。
+
+    Args:
+        form_id: 表单ID。常用值：
+            BD_MATERIAL(物料)、BD_Customer(客户)、BD_Supplier(供应商)、
+            SAL_SaleOrder(销售订单)、PUR_PurchaseOrder(采购订单)、
+            STK_InStock(入库单)、STK_OutStock(出库单)、GL_VOUCHER(凭证)
+        field_keys: 查询字段，逗号分隔。如 "FName,FNumber,FCreateOrgId,FUseOrgId"
+        filter_string: 过滤条件。如 "FNumber like 'MAT%'"
+        order_string: 排序字段。如 "FNumber ASC"
+        top_count: 本次最多返回行数，默认100。映射到金蝶 TopRowCount（绝对终止行号 = start_row + top_count），
+            同时作为金蝶 Limit（单次页大小）。设为 0 表示不限制行数（仅靠 limit 控制）。
+        start_row: 起始行号，默认0。翻页时传入上一次返回的 next_start_row。
+        limit: 仅在 top_count=0 时生效，作为金蝶 Limit 页大小上限，默认2000。
+            top_count>0 时此参数被忽略（页大小由 top_count 决定）。
+    """
+    raw = _sdk().BillQuery(
+        {
+            "FormId": form_id,
+            "FieldKeys": field_keys,
+            "FilterString": filter_string,
+            "OrderString": order_string,
+            "TopRowCount": (start_row + top_count) if top_count > 0 else 0,
+            "StartRow": start_row,
+            "Limit": top_count if top_count > 0 else limit,
+        }
+    )
+    return _wrap_query_result(raw, top_count, limit, start_row)
+
+
+@mcp.tool()
+def count_bill(form_id: str, filter_string: str = "") -> str:
+    """估算某查询条件下的数据行数（不返回数据内容）。用于大数据量查询前的探测。
+
+    返回 JSON 格式：
+        {"estimated_rows": N, "is_exact": true/false, "hint": "..."}
+    当 is_exact=false 时，实际行数 ≥ estimated_rows，建议按月/周分片查询。
+
+    Args:
+        form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
+        filter_string: 过滤条件。如 "FDate >= '2025-01-01' AND FDate < '2026-01-01'"
+    """
+    _PROBE_LIMIT = 5000
+    raw = _sdk().BillQuery(
+        {
+            "FormId": form_id,
+            "FieldKeys": "FID",
+            "FilterString": filter_string,
+            "TopRowCount": _PROBE_LIMIT,
+            "StartRow": 0,
+            "Limit": _PROBE_LIMIT,
+        }
+    )
+
+    if _is_session_expired(raw):
+        return raw
+
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return raw
+
+    if not isinstance(data, list):
+        return raw
+
+    count = len(data)
+    is_exact = count < _PROBE_LIMIT
+    result: dict = {"estimated_rows": count, "is_exact": is_exact}
+    if not is_exact:
+        result["hint"] = (
+            f"实际行数 ≥ {_PROBE_LIMIT}，建议按自然月分片查询（每月单独调用 query_bill_json）。"
+        )
+    return json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool()
+def query_bill_all(
+    form_id: str,
+    field_keys: str,
+    filter_string: str = "",
+    order_string: str = "",
+    max_rows: int = 20000,
+    page_size: int = 2000,
+) -> str:
+    """自动翻页查询直到拉完或达到 max_rows 安全上限。
+
+    适合估算 ≤ 数千行的场景。大数据量（> 5000 行）请用 query_bill_to_file（落盘）
+    或 query_bill_range（日期分片），避免超过 MCP 1 MB 返回限制。
+
+    返回格式：
+        {"rows": [...], "row_count": N, "exhausted": true/false,
+         "next_start_row": N,   # 仅 exhausted=false 时
+         "hint": "..."}         # 仅 exhausted=false 时
+
+    Args:
+        form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
+        field_keys: 查询字段，逗号分隔。如 "FBillNo,FDate,FAmount"
+        filter_string: 过滤条件。如 "FDate >= '2025-01-01'"
+        order_string: 排序字段。如 "FDate ASC"
+        max_rows: 安全上限，默认 20000；超过则提前终止并返回 exhausted=false
+        page_size: 每页行数，默认 2000，建议不超过 2000
+    """
+    params = {
+        "FormId": form_id,
+        "FieldKeys": field_keys,
+        "FilterString": filter_string,
+        "OrderString": order_string,
+    }
+    rows, exhausted, next_start, err = _paginate_bill(params, page_size, max_rows)
+    if err is not None:
+        return err
+    result: dict = {"rows": rows, "row_count": len(rows), "exhausted": exhausted}
+    if not exhausted:
+        result["next_start_row"] = next_start
+        result["hint"] = (
+            "已达 max_rows 安全上限，如需继续请调用 query_bill_range 或缩小 filter_string 后手动分片"
+        )
+    return json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool()
+def query_bill_to_file(
+    form_id: str,
+    field_keys: str,
+    filter_string: str = "",
+    output_path: str = "",
+    format: str = "ndjson",
+    page_size: int = 2000,
+    max_rows: int = 500000,
+) -> str:
+    """自动翻页并流式写入本地文件，适合大数据量导出（万行以上）。
+
+    不在内存中累积数据，写入完成后返回文件路径和统计信息。
+    文件可用 Read 工具抽检，或交由 pandas/polars 处理。
+
+    返回格式：
+        {"path": "...", "row_count": N, "bytes": M, "format": "ndjson"}
+        若中途出错：{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
+
+    Args:
+        form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
+        field_keys: 查询字段，逗号分隔。如 "FBillNo,FDate,FAmount"
+        filter_string: 过滤条件。如 "FDate >= '2025-01-01'"
+        output_path: 输出文件绝对路径。如 "/tmp/orders.ndjson"
+        format: 输出格式，ndjson（每行一个 JSON 对象）或 csv，默认 ndjson
+        page_size: 每页行数，默认 2000
+        max_rows: 最大写入行数，默认 500000；超过则截断并正常返回
+    """
+    if not output_path or not os.path.isabs(output_path):
+        return json.dumps({"error": "output_path 必须为非空绝对路径"}, ensure_ascii=False)
+    if format not in {"ndjson", "csv"}:
+        return json.dumps(
+            {"error": f"format 必须是 ndjson 或 csv，收到: {format!r}"}, ensure_ascii=False
+        )
+    parent = os.path.dirname(output_path)
+    if not os.path.isdir(parent):
+        return json.dumps({"error": f"目录不存在: {parent}"}, ensure_ascii=False)
+
+    fields = [f.strip() for f in field_keys.split(",") if f.strip()]
+    params = {
+        "FormId": form_id,
+        "FieldKeys": field_keys,
+        "FilterString": filter_string,
+        "OrderString": "",
+        "StartRow": 0,
+    }
+
+    try:
+        with open(output_path, "w", encoding="utf-8", newline="") as f:
+            rows_written, _, error_raw = _stream_to_file_handle(
+                f, params, page_size, max_rows, fields, format, False
+            )
+    except OSError as e:
+        return json.dumps({"error": f"文件写入失败: {e}"}, ensure_ascii=False)
+
+    file_bytes = os.path.getsize(output_path)
+
+    if error_raw is not None:
+        return json.dumps(
+            {
+                "error": "查询中途遇到错误，已写入部分数据",
+                "path": output_path,
+                "row_count": rows_written,
+                "bytes": file_bytes,
+            },
+            ensure_ascii=False,
+        )
+
+    return json.dumps(
+        {
+            "path": output_path,
+            "row_count": rows_written,
+            "bytes": file_bytes,
+            "format": format,
+        },
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def query_bill_range(
+    form_id: str,
+    field_keys: str,
+    date_field: str,
+    date_from: str,
+    date_to: str,
+    extra_filter: str = "",
+    chunk: str = "month",
+    output_path: str = "",
+    page_size: int = 2000,
+) -> str:
+    """按日期自动切片 + 翻页，适合跨月/跨年查询。
+
+    将 [date_from, date_to) 按 chunk 切成 N 段，每段独立翻页拉取。
+    output_path 为空时内联返回（受 MCP 1 MB 限制，适合小跨度）；
+    非空时流式落盘，适合大跨度（年级）查询。
+
+    返回格式（内联）：
+        {"rows": [...], "row_count": N, "chunks": K, "exhausted": true}
+    返回格式（落盘）：
+        {"path": "...", "row_count": N, "bytes": M, "chunks": K, "format": "ndjson"}
+        若中途出错：{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
+
+    Args:
+        form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder 等
+        field_keys: 查询字段，逗号分隔
+        date_field: 日期字段名。通常是 FDate 或 FCreateDate
+        date_from: 起始日期（含），YYYY-MM-DD
+        date_to: 结束日期（不含），YYYY-MM-DD
+        extra_filter: 额外过滤条件（与日期条件 AND 拼接）
+        chunk: 切片粒度，month（默认）/ week / day
+        output_path: 落盘路径（绝对路径）。空=内联返回
+        page_size: 每页行数，默认 2000
+    """
+    try:
+        chunks = list(_iter_date_chunks(date_from, date_to, chunk))
+    except ValueError as e:
+        return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    inline_mode = not output_path
+
+    if not inline_mode:
+        if not os.path.isabs(output_path):
+            return json.dumps({"error": "output_path 必须为绝对路径"}, ensure_ascii=False)
+        parent = os.path.dirname(output_path)
+        if not os.path.isdir(parent):
+            return json.dumps({"error": f"目录不存在: {parent}"}, ensure_ascii=False)
+
+    fields = [f.strip() for f in field_keys.split(",") if f.strip()]
+
+    def _build_filter(chunk_from: str, chunk_to: str) -> str:
+        date_filter = f"{date_field} >= '{chunk_from}' AND {date_field} < '{chunk_to}'"
+        return f"({extra_filter}) AND {date_filter}" if extra_filter else date_filter
+
+    if inline_mode:
+        all_rows: list = []
+        for chunk_from, chunk_to in chunks:
+            params: dict = {
+                "FormId": form_id,
+                "FieldKeys": field_keys,
+                "FilterString": _build_filter(chunk_from, chunk_to),
+                "OrderString": "",
+            }
+            rows, _exhausted, _next, err = _paginate_bill(params, page_size, 20000)
+            if err is not None:
+                return err
+            all_rows.extend(rows)
+        return json.dumps(
+            {
+                "rows": all_rows,
+                "row_count": len(all_rows),
+                "chunks": len(chunks),
+                "exhausted": True,
+            },
+            ensure_ascii=False,
+        )
+
+    # Streaming / file mode
+    total_count = 0
+    error_raw = None
+    try:
+        with open(output_path, "w", encoding="utf-8", newline="") as f:
+            header_written = False
+            for chunk_from, chunk_to in chunks:
+                params = {
+                    "FormId": form_id,
+                    "FieldKeys": field_keys,
+                    "FilterString": _build_filter(chunk_from, chunk_to),
+                    "OrderString": "",
+                    "StartRow": 0,
+                }
+                rows_written, header_written, error_raw = _stream_to_file_handle(
+                    f, params, page_size, 500000, fields, "ndjson", header_written
+                )
+                total_count += rows_written
+                if error_raw is not None:
+                    break
+    except OSError as e:
+        return json.dumps({"error": f"文件写入失败: {e}"}, ensure_ascii=False)
+
+    file_bytes = os.path.getsize(output_path)
+
+    if error_raw is not None:
+        return json.dumps(
+            {
+                "error": "查询中途遇到错误，已写入部分数据",
+                "path": output_path,
+                "row_count": total_count,
+                "bytes": file_bytes,
+            },
+            ensure_ascii=False,
+        )
+
+    return json.dumps(
+        {
+            "path": output_path,
+            "row_count": total_count,
+            "bytes": file_bytes,
+            "chunks": len(chunks),
+            "format": "ndjson",
+        },
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def view_bill(
+    form_id: str,
+    number: str = "",
+    bill_id: str = "",
+) -> str:
+    """查看金蝶云星空单条记录的完整详情。
+
+    通过编号或内码查看单条记录的所有字段信息。
+
+    Args:
+        form_id: 表单ID。如 BD_MATERIAL、SAL_SaleOrder 等
+        number: 单据编号。如 "MATERIAL001"（number 和 bill_id 二选一）
+        bill_id: 单据内码ID（number 和 bill_id 二选一）
+    """
+    data = {"CreateOrgId": 0, "Number": number, "Id": bill_id, "IsSortBySeq": "false"}
+    return _sdk().View(form_id, data)
+
+
+@mcp.tool()
+def query_metadata(form_id: str) -> str:
+    """查询金蝶云星空表单的元数据（字段结构信息）。
+
+    用于获取某个表单有哪些字段、字段类型等信息，便于构造查询和保存参数。
+
+    Args:
+        form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
+    """
+    return _sdk().QueryBusinessInfo({"FormId": form_id})
+
+
+# ===================================================================
+# 初始化 & 入口
+# ===================================================================
+
+def setup() -> None:
+    """Initialize environment, validate required vars, and create the SDK instance."""
+    global api_sdk
+    load_dotenv(dotenv_path=Path.cwd() / ".env")
+    _required_env = ["KD_SERVER_URL", "KD_ACCT_ID", "KD_USERNAME", "KD_APP_ID", "KD_APP_SEC"]
+    _missing_env = [k for k in _required_env if not os.getenv(k)]
+    if _missing_env:
+        raise RuntimeError(f"Missing required env vars: {', '.join(_missing_env)}")
+
+    api_key = os.getenv("MCP_API_KEY", "")
+    if api_key:
+        issuer_url = os.getenv("MCP_ISSUER_URL", "http://localhost:8000")
+        mcp._token_verifier = ApiKeyVerifier(api_key)
+        mcp.settings.auth = AuthSettings(issuer_url=issuer_url, resource_server_url=issuer_url)  # type: ignore[arg-type]
+
+    server_url = os.getenv("KD_SERVER_URL", "")
+    api_sdk = RetryableK3CloudApiSdk(server_url)
+    api_sdk.InitConfig(
+        acct_id=os.getenv("KD_ACCT_ID", ""),
+        user_name=os.getenv("KD_USERNAME", ""),
+        app_id=os.getenv("KD_APP_ID", ""),
+        app_secret=os.getenv("KD_APP_SEC", ""),
+        server_url=server_url,
+        lcid=int(os.getenv("KD_LCID", "2052")),
+        org_num=int(os.getenv("KD_ORG_NUM", "0") or "0"),
+    )
+
+
+def main():
+    import argparse
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+        stream=sys.stderr,
+    )
+
+    parser = argparse.ArgumentParser(description="Nxr K3Cloud Query MCP Server（纯查询版）")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="传输协议（默认 stdio）",
+    )
+    args = parser.parse_args()
+
+    setup()
+
+    logger.info("[k3cloud-query] 纯查询模式，共 8 个查询工具")
+    mcp.run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

k3cloud_query_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: k3cloud-query-mcp
+Version: 1.0.0
+Summary: Nxr K3Cloud Query MCP Server — 金蝶云星空纯查询 MCP 服务，仅提供只读查询工具
+Project-URL: Homepage, https://github.com/nxr/k3cloud-query-mcp
+Project-URL: Repository, https://github.com/nxr/k3cloud-query-mcp
+Author: Nxr Team
+License: Apache-2.0
+License-File: LICENSE
+Keywords: erp,k3cloud,kingdee,mcp,mcp-server,nxr,query,金蝶
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: kingdee-cdp-webapi-sdk<9.0.0,>=8.2.0
+Requires-Dist: mcp<2,>=1.26.0
+Requires-Dist: python-dotenv<2,>=1.2.1
+Description-Content-Type: text/markdown
+
+# k3cloud-query-mcp
+
+金蝶云星空 K3Cloud MCP 查询服务（纯查询版）—— 让 AI 助手通过自然语言查询金蝶 ERP 数据。
+
+## 特性
+
+| 特性 | k3cloud-query-mcp |
+|------|----------------------|
+| 查询工具 |  ✅ 8 个 |
+| 写入/操作工具 | ❌ 已移除 |
+| 适用场景 | 纯查询 |
+
+## 查询工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `query_bill` | 查询单据数据（二维数组） |
+| `query_bill_json` | 查询单据数据（JSON 对象数组） |
+| `count_bill` | 估算查询条件下的数据行数 |
+| `query_bill_all` | 自动翻页查询（≤ 数千行） |
+| `query_bill_to_file` | 大数据量流式导出到文件 |
+| `query_bill_range` | 按日期分片查询（跨月/跨年） |
+| `view_bill` | 查看单条记录完整详情 |
+| `query_metadata` | 查询表单字段元数据 |
+
+## 安装
+
+```bash
+pip install k3cloud-query-mcp
+```
+
+或使用 uv：
+
+```bash
+uv add k3cloud-query-mcp
+```
+
+## 配置
+
+在项目根目录创建 `.env` 文件：
+
+```env
+KD_ACCT_ID=your_acct_id
+KD_USERNAME=your_username
+KD_APP_ID=your_app_id
+KD_APP_SEC=your_app_secret
+KD_SERVER_URL=https://your-server/k3cloud/
+KD_LCID=2052
+```
+
+## 使用
+
+### Claude Desktop 配置
+
+```json
+{
+  "mcpServers": {
+    "k3cloud-query": {
+      "command": "uvx",
+      "args": ["k3cloud-query-mcp"],
+      "env": {
+        "KD_ACCT_ID": "your_acct_id",
+        "KD_USERNAME": "your_username",
+        "KD_APP_ID": "your_app_id",
+        "KD_APP_SEC": "your_app_secret",
+        "KD_SERVER_URL": "https://your-server/k3cloud/"
+      }
+    }
+  }
+}
+```
+
+### SSE 模式
+
+```bash
+k3cloud-query-mcp --transport sse
+```
+
+### 开发
+
+```bash
+# 安装依赖
+uv sync
+
+# 运行
+uv run k3cloud-query-mcp
+
+# 测试
+make test
+
+# 代码检查
+make lint
+
+# 格式化
+make format
+```

k3cloud_query_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+k3cloud_query_mcp/__init__.py,sha256=cG2PwYZFo8hQzSwX1RIqfbnKHMp435mvJgLfvw0UOPQ,113
+k3cloud_query_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+k3cloud_query_mcp/server.py,sha256=cLCVJMQiaEW4CDo38_L8mvvu14jH5J70MLJZK2BwS6U,28065
+k3cloud_query_mcp-1.0.0.dist-info/METADATA,sha256=wXbYvhnvrv-6VZGMW8K-ek4nG5I9Gmu9zxQabs5JU6g,2957
+k3cloud_query_mcp-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+k3cloud_query_mcp-1.0.0.dist-info/entry_points.txt,sha256=Z4A4D-qUBNUlIVA7KbE1QdQH1St_e8-T_YmO-7t3y5w,68
+k3cloud_query_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=9BoAnlWUzbAVcRR-6VO8G6fGBdyQR0ziygxBKBYazJE,10364
+k3cloud_query_mcp-1.0.0.dist-info/RECORD,,

k3cloud_query_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

k3cloud_query_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+k3cloud-query-mcp = k3cloud_query_mcp.server:main

k3cloud_query_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,183 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Nxr Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.