CRZbulabula commented on code in PR #18: URL: https://github.com/apache/iotdb-mcp-server/pull/18#discussion_r3948320043
########## src/iotdb_mcp_server/services/sql_driver.py: ########## @@ -0,0 +1,1276 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +import asyncio +from concurrent.futures import ThreadPoolExecutor +from dataclasses import dataclass, field +from functools import partial +import logging +import os +import re +import threading +import time +import uuid +from datetime import datetime, timezone +from typing import Any + +from iotdb.Session import Session +from iotdb.table_session import TableSession +from iotdb.utils.SessionDataSet import SessionDataSet +from mcp.types import TextContent + +from iotdb_mcp_server.config import Config +from iotdb_mcp_server.result_store import result_store_from_export_path +from iotdb_mcp_server.result_store import StoredCsvResult +from iotdb_mcp_server.runtime_policy import dynamic_env_bool +from iotdb_mcp_server.runtime_policy import dynamic_getenv +from iotdb_mcp_server.runtime_policy import dynamic_policy_snapshot +from iotdb_mcp_server.runtime_policy import permission_enforcement_mode +from iotdb_mcp_server.runtime_policy import strict_permission_enforcement +from iotdb_mcp_server.services.json_response import ( + csv_result_payload_response, + payload_response, +) +from iotdb_mcp_server.services.target_selection import ( + iotdb_target_response_context, + select_target_config, + table_session_pool, + tree_session_pool, +) +from iotdb_mcp_server.services.tree_sql_guardrails import assert_tree_query_shape +from iotdb_mcp_server.services.tree_sql_guardrails import ( + tree_from_wildcard_runtime_hint, +) + +_READONLY_PREFIXES_COMMON = ( + "SELECT", + "SHOW", + "EXPLAIN", + "DESC", + "DESCRIBE", +) +_READONLY_PREFIXES_TREE = ( + "COUNT TIMESERIES", + "COUNT NODES", + "COUNT DEVICES", + "CALL INFERENCE", + "SHOW CONTINUOUS QUERIES", + "SHOW CQS", +) +_READONLY_PREFIXES_TABLE: tuple[str, ...] = () + +_DDL_PREFIXES_COMMON = ( + "CREATE DATABASE", + "ALTER DATABASE", + "DROP DATABASE", + "CREATE TABLE", + "ALTER TABLE", + "DROP TABLE", + "USE", + "SET TTL", + "UNSET TTL", + "CREATE MODEL", + "DROP MODEL", + "LOAD MODEL", + "UNLOAD MODEL", + "REMOVE AINODE", +) +_DDL_PREFIXES_TREE = ( + "CREATE TIMESERIES", + "CREATE ALIGNED TIMESERIES", + "ALTER TIMESERIES", + "DROP TIMESERIES", + "DELETE TIMESERIES", + "CREATE CONTINUOUS QUERY", + "CREATE CQ", + "DROP CONTINUOUS QUERY", + "DROP CQ", +) +_DDL_PREFIXES_TABLE: tuple[str, ...] = () + +_FULL_PREFIXES_COMMON = ( + "INSERT INTO", + "UPDATE", + "DELETE FROM", + "DELETE DEVICES", +) +_FULL_PREFIXES_TREE: tuple[str, ...] = () +_FULL_PREFIXES_TABLE: tuple[str, ...] = () + +_DESTRUCTIVE_PREFIXES = ( + "DROP ", + "DELETE ", + "UNSET TTL", + "REMOVE AINODE", + "UNLOAD MODEL", +) + +_PERMISSION_RANK = {"readonly": 0, "ddl": 1, "full": 2} +_TEMPLATE_FIELD_PATTERN = re.compile( + r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)(?::(literal|path|identifier))?\s*\}\}" +) +_PATH_SEGMENT_PATTERN = re.compile(r"^([A-Za-z0-9_]+|\*|\*\*)$") +_IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +_DEFAULT_BATCH_PER_ITEM_TIMEOUT_MS = 60_000 +_DEFAULT_BATCH_TIMEOUT_MS = 300_000 +_DEFAULT_BATCH_MAX_ROWS_PER_ITEM = 10_000 +_DEFAULT_BATCH_MAX_BYTES_PER_ITEM = 16 * 1024 * 1024 +_DEFAULT_BATCH_MAX_TOTAL_ROWS = 100_000 +_DEFAULT_BATCH_MAX_TOTAL_BYTES = 64 * 1024 * 1024 +_DEFAULT_BATCH_WORKER_POOL_SIZE = 4 + + +def _env_bool(name: str, default: bool) -> bool: + return dynamic_env_bool(name, default) + + +def _env_int( + name: str, default: int, minimum: int = 1, maximum: int | None = None +) -> int: + raw = (dynamic_getenv(name, "") or os.getenv(name, "") or "").strip() + if not raw: + value = default + else: + try: + value = int(raw) + except ValueError: + value = default + value = max(minimum, value) + if maximum is not None: + value = min(maximum, value) + return value + + +def _positive_int( + value: int | None, + *, + env_name: str, + default: int, + minimum: int = 1, + maximum: int | None = None, +) -> int: + if value is None: + return _env_int(env_name, default, minimum=minimum, maximum=maximum) + resolved = max(minimum, int(value)) + if maximum is not None: + resolved = min(maximum, resolved) + return resolved + + +def _csv_set(value: str) -> set[str]: + return {item.strip() for item in value.split(",") if item.strip()} + + +def _parse_mode() -> str: + mode = ( + (dynamic_getenv("IOTDB_SQL_DRIVER_MODE", "readonly") or "readonly") + .strip() + .lower() + ) + if mode not in ("readonly", "ddl", "full"): + raise ValueError( + "Invalid IOTDB_SQL_DRIVER_MODE. Expected one of: readonly, ddl, full." + ) + return mode + + +def _strip_single_trailing_semicolon(sql: str, empty_message: str) -> str: + cleaned = sql.strip() + if not cleaned: + raise ValueError(empty_message) + + quote: str | None = None + escaped = False + semicolon_indexes: list[int] = [] + index = 0 + while index < len(cleaned): + char = cleaned[index] + if escaped: + escaped = False + index += 1 + continue + if char == "\\" and quote: + escaped = True + index += 1 + continue + if quote: + if char == quote: + if index + 1 < len(cleaned) and cleaned[index + 1] == quote: + index += 2 + continue + quote = None + index += 1 + continue + if char in {"'", '"'}: + quote = char + elif char == ";": + semicolon_indexes.append(index) + index += 1 + + if not semicolon_indexes: + return cleaned + if semicolon_indexes == [len(cleaned) - 1]: + return cleaned[:-1].strip() + raise ValueError("Only a single SQL statement is allowed.") + + +def _normalize_sql(sql: str) -> str: + return _strip_single_trailing_semicolon(sql, "SQL cannot be empty.") + + +def _normalize_for_prefix(sql: str) -> str: + return re.sub(r"\s+", " ", sql).strip().upper() + + +def _matches_prefix(normalized_upper: str, prefix: str) -> bool: + if not normalized_upper.startswith(prefix): + return False + return ( + len(normalized_upper) == len(prefix) + or normalized_upper[len(prefix)].isspace() + or normalized_upper[len(prefix)] == "(" + ) + + +def _merge_prefixes(base: tuple[str, ...], env_var: str) -> tuple[str, ...]: + extra = tuple( + item.strip().upper() + for item in (dynamic_getenv(env_var, "") or "").split(",") + if item.strip() + ) + all_prefixes = tuple(dict.fromkeys([*base, *extra])) + return tuple(sorted(all_prefixes, key=len, reverse=True)) + + +def _resolve_whitelists(sql_dialect: str) -> dict[str, tuple[str, ...]]: + readonly = _READONLY_PREFIXES_COMMON + ( + _READONLY_PREFIXES_TREE if sql_dialect == "tree" else _READONLY_PREFIXES_TABLE + ) + ddl = _DDL_PREFIXES_COMMON + ( + _DDL_PREFIXES_TREE if sql_dialect == "tree" else _DDL_PREFIXES_TABLE + ) + full = _FULL_PREFIXES_COMMON + ( + _FULL_PREFIXES_TREE if sql_dialect == "tree" else _FULL_PREFIXES_TABLE + ) + + return { + "readonly": _merge_prefixes( + readonly, "IOTDB_SQL_DRIVER_EXTRA_READONLY_PREFIXES" + ), + "ddl": _merge_prefixes(ddl, "IOTDB_SQL_DRIVER_EXTRA_DDL_PREFIXES"), + "full": _merge_prefixes(full, "IOTDB_SQL_DRIVER_EXTRA_FULL_PREFIXES"), + } + + +def _classify_sql(sql: str, whitelists: dict[str, tuple[str, ...]]) -> tuple[str, str]: + normalized_upper = _normalize_for_prefix(sql) + + for category in ("readonly", "ddl", "full"): + for prefix in whitelists[category]: + if _matches_prefix(normalized_upper, prefix): Review Comment: **[P1] Do not classify Tree `SELECT ... INTO ...` as readonly** - IoTDB Tree `SELECT ... INTO ...` writes the selected data into destination time series. - The prefix-only classifier returns `readonly` for every statement starting with `SELECT`. - I reproduced this with strict enforcement, `IOTDB_SQL_DRIVER_MODE=readonly`, and writes disabled: `sql_executor_batch` accepted `SELECT s1 INTO root.dest.d1(s1) FROM root.source.d1` and sent it to the database client. Please parse or explicitly detect write-producing SELECT forms before assigning the readonly category. ########## src/iotdb_mcp_server/runtime_policy.py: ########## @@ -0,0 +1,327 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +from __future__ import annotations + +from collections.abc import Mapping +import json +import os +from pathlib import Path +import re +from threading import RLock +from typing import Any + + +_DEFAULT_SERVER_NAME = "iotdb" +_SHELL_DEFAULT_RE = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*):-([^}]*)\}$") +_SENSITIVE_KEY_RE = re.compile(r"(PASSWORD|SECRET|TOKEN|API_KEY|ACCESS_KEY)", re.IGNORECASE) +_SESSION_POLICY_LOCK = RLock() +_SESSION_POLICY: dict[str, str] = {} + +_POLICY_KEYS = frozenset( + { + "IOTDB_ENABLE_METADATA_QUERY", + "IOTDB_METADATA_ALLOWED_USERS", + "IOTDB_ENABLE_DATABASE_DDL", + "IOTDB_DATABASE_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_DROP_CONFIRM", + "IOTDB_ENABLE_TABLE_DDL", + "IOTDB_TABLE_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_TABLE_DROP_CONFIRM", + "IOTDB_ENABLE_TIMESERIES_DDL", + "IOTDB_TIMESERIES_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_TIMESERIES_DROP_CONFIRM", + "IOTDB_ENABLE_TTL_SQL", + "IOTDB_TTL_ALLOWED_USERS", + "IOTDB_REQUIRE_TTL_UNSET_CONFIRM", + "IOTDB_ENABLE_WRITE_DML", + "IOTDB_WRITE_ALLOWED_USERS", + "IOTDB_REQUIRE_DELETE_CONFIRM", + "IOTDB_ENABLE_SQL_DRIVER", + "IOTDB_SQL_DRIVER_ALLOWED_USERS", + "IOTDB_SQL_DRIVER_MODE", + "IOTDB_SQL_DRIVER_REQUIRE_DESTRUCTIVE_CONFIRM", + "IOTDB_SQL_DRIVER_EXTRA_READONLY_PREFIXES", + "IOTDB_SQL_DRIVER_EXTRA_DDL_PREFIXES", + "IOTDB_SQL_DRIVER_EXTRA_FULL_PREFIXES", + "IOTDB_ENABLE_MODEL_MANAGEMENT", + "IOTDB_MODEL_ALLOWED_USERS", + "IOTDB_REQUIRE_MODEL_DESTRUCTIVE_CONFIRM", + "TIMESEEK_MCP_PERMISSION_ENFORCEMENT", + "IOTDB_STRICT_PERMISSION_ENFORCEMENT", + } +) + +_FULL_PERMISSION_DEFAULTS = { + "IOTDB_ENABLE_METADATA_QUERY": "true", + "IOTDB_METADATA_ALLOWED_USERS": "*", + "IOTDB_ENABLE_DATABASE_DDL": "true", + "IOTDB_DATABASE_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TABLE_DDL": "true", + "IOTDB_TABLE_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TABLE_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TIMESERIES_DDL": "true", + "IOTDB_TIMESERIES_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TIMESERIES_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TTL_SQL": "true", + "IOTDB_TTL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TTL_UNSET_CONFIRM": "true", + "IOTDB_ENABLE_WRITE_DML": "true", + "IOTDB_WRITE_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_DELETE_CONFIRM": "true", + "IOTDB_ENABLE_SQL_DRIVER": "true", + "IOTDB_SQL_DRIVER_ALLOWED_USERS": "*", + "IOTDB_SQL_DRIVER_MODE": "full", + "IOTDB_SQL_DRIVER_REQUIRE_DESTRUCTIVE_CONFIRM": "true", + "IOTDB_ENABLE_MODEL_MANAGEMENT": "true", + "IOTDB_MODEL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_MODEL_DESTRUCTIVE_CONFIRM": "true", + "TIMESEEK_MCP_PERMISSION_ENFORCEMENT": "advisory", + "IOTDB_STRICT_PERMISSION_ENFORCEMENT": "false", +} + +_PRESET_POLICIES = { + "full": dict(_FULL_PERMISSION_DEFAULTS), + "ddl": { + **_FULL_PERMISSION_DEFAULTS, + "IOTDB_SQL_DRIVER_MODE": "ddl", + "IOTDB_ENABLE_WRITE_DML": "false", + }, + "readonly": { + **_FULL_PERMISSION_DEFAULTS, + "IOTDB_ENABLE_DATABASE_DDL": "false", + "IOTDB_ENABLE_TABLE_DDL": "false", + "IOTDB_ENABLE_TIMESERIES_DDL": "false", + "IOTDB_ENABLE_TTL_SQL": "false", + "IOTDB_ENABLE_WRITE_DML": "false", + "IOTDB_SQL_DRIVER_MODE": "readonly", + }, +} + + +def _candidate_mcp_config_paths() -> list[Path]: + candidates: list[Path] = [] + explicit = os.getenv("TIMESEEK_MCP_CONFIG_PATH") + if explicit: + candidates.append(Path(explicit).expanduser()) + + timeseek_root = os.getenv("TIMESEEK_ROOT") + if timeseek_root: + root = Path(timeseek_root).expanduser() + candidates.extend( + [ + root / ".mcp.json", + root / "timeseek-codex-multi-plugin" / ".mcp.json", + root / "timeseek-codex-single-plugin" / ".mcp.json", + ] + ) + + repo_root = os.getenv("REPO_ROOT") or os.getenv("TIMESEEK_REPO_ROOT") + if repo_root: + root = Path(repo_root).expanduser() + candidates.extend( + [ + root / ".mcp.json", + root / "timeseek_codex" / "timeseek-codex-multi-plugin" / ".mcp.json", + root / "timeseek_codex" / "timeseek-codex-single-plugin" / ".mcp.json", + root / "timeseek_cc" / ".mcp.json", + ] + ) + + cwd = Path.cwd() + candidates.extend( + [ + cwd / ".mcp.json", + cwd / "timeseek_codex" / "timeseek-codex-multi-plugin" / ".mcp.json", + cwd / "timeseek_codex" / "timeseek-codex-single-plugin" / ".mcp.json", + cwd / "timeseek_cc" / ".mcp.json", + ] + ) + + deduped: list[Path] = [] + seen: set[str] = set() + for candidate in candidates: + key = str(candidate) + if key not in seen: + seen.add(key) + deduped.append(candidate) + return deduped + + +def _expand_config_value(value: Any) -> str: + text = str(value) + match = _SHELL_DEFAULT_RE.fullmatch(text) + if not match: + return text + name, default = match.groups() + current = os.getenv(name) + return current if current not in (None, "") else default + + +def _load_mcp_env() -> tuple[dict[str, str], str]: + server_name = os.getenv("TIMESEEK_MCP_SERVER_NAME", _DEFAULT_SERVER_NAME) + for path in _candidate_mcp_config_paths(): + if not path.exists(): + continue + try: + data = json.loads(path.read_text(encoding="utf-8")) + except Exception: + continue + server = data.get("mcpServers", {}).get(server_name, {}) + env = server.get("env", {}) + if isinstance(env, dict): + return {str(key): _expand_config_value(value) for key, value in env.items()}, str(path) + return {}, "" + + +def dynamic_getenv(name: str, default: str | None = None) -> str | None: + with _SESSION_POLICY_LOCK: + value = _SESSION_POLICY.get(name) + if value not in (None, ""): + return value + + env, _ = _load_mcp_env() + value = env.get(name) + if value not in (None, ""): + return value + + value = os.getenv(name) + if value not in (None, ""): + return value + + return _FULL_PERMISSION_DEFAULTS.get(name, default) + + +def dynamic_env_bool(name: str, default: bool) -> bool: + value = dynamic_getenv(name) + if value is None: + return default + normalized = value.strip().lower() + if normalized in {"1", "true", "yes", "on"}: + return True + if normalized in {"0", "false", "no", "off", ""}: + return False + return default + + +def permission_enforcement_mode() -> str: + if dynamic_env_bool("IOTDB_STRICT_PERMISSION_ENFORCEMENT", False): + return "strict" + mode = (dynamic_getenv("TIMESEEK_MCP_PERMISSION_ENFORCEMENT", "advisory") or "advisory").strip().lower() + if mode not in {"advisory", "strict"}: + return "advisory" + return mode + + +def strict_permission_enforcement() -> bool: + return permission_enforcement_mode() == "strict" + + +def _redact_env(env: dict[str, str]) -> dict[str, str]: + return { + key: "***" if _SENSITIVE_KEY_RE.search(key) else value Review Comment: **[P1] Redact credentials embedded in structured environment values** - This redacts only when the environment variable name matches `_SENSITIVE_KEY_RE`. - `TIMESEEK_IOTDB_TARGETS_JSON` does not match that pattern, but its JSON value can contain target `password` and `last_known_good_credential` fields. - `get_iotdb_session_policy()` returns `mcp_env`, so those credentials are currently returned verbatim to the caller. Please withhold known structured connection variables or parse them and recursively redact secret fields before returning the snapshot. ########## src/iotdb_mcp_server/services/udf.py: ########## @@ -0,0 +1,528 @@ +from __future__ import annotations + +import datetime +import logging +import re +import uuid +from typing import Any + +from mcp.types import TextContent + +from iotdb_mcp_server.config import Config +from iotdb_mcp_server.result_store import result_store_from_export_path +from iotdb_mcp_server.services.json_response import ( + csv_result_payload_response, + payload_response, + text_payload_response, +) +from iotdb_mcp_server.services.query import ( + _ensure_export_directory, + _prepare_table_res, + _prepare_tree_res, + sanitize_filename, +) +from iotdb_mcp_server.services.target_selection import ( + iotdb_target_response_context, + select_target_config, + table_session_pool, + tree_session_pool, +) +from iotdb_mcp_server.services.tree_sql_guardrails import assert_tree_query_shape + +_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +_TREE_PATH_RE = re.compile(r"^root(?:\.[A-Za-z_][A-Za-z0-9_]*|\.\*|\.\*\*)*$") +_TREE_EXPR_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$") +_DANGEROUS_SQL_RE = re.compile( + r";|--|/\*|\*/|\b(INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|LOAD|SET|GRANT|REVOKE|TRUNCATE)\b", + re.IGNORECASE, +) + + +def _validate_identifier(value: str, label: str) -> str: + cleaned = str(value or "").strip() + if not _IDENTIFIER_RE.fullmatch(cleaned): + raise ValueError(f"Invalid {label}. Use letters, numbers, and underscore only.") + return cleaned + + +def _validate_function_name(function_name: str) -> str: + return _validate_identifier(function_name, "function_name") + + +def _validate_tree_path(path: str) -> str: + cleaned = str(path or "").strip() + if not _TREE_PATH_RE.fullmatch(cleaned): + raise ValueError("Invalid tree from_path. Use path like root.sg.d1 or root.sg.*.") + return cleaned + + +def _validate_expression(expression: str, *, dialect: str) -> str: + cleaned = str(expression or "").strip() + if not cleaned: + raise ValueError("UDF expression cannot be empty.") + if _DANGEROUS_SQL_RE.search(cleaned): + raise ValueError("UDF expression contains unsupported SQL syntax.") + if dialect == "table": + return _validate_identifier(cleaned, "table expression") + if not _TREE_EXPR_RE.fullmatch(cleaned): + raise ValueError("Invalid tree expression. Use measurement names or relative paths.") + return cleaned + + +def _validate_where_clause(where_clause: str | None) -> str | None: + if where_clause is None: + return None + cleaned = str(where_clause).strip() + if not cleaned: + return None + if _DANGEROUS_SQL_RE.search(cleaned): + raise ValueError("where_clause contains unsupported or non-readonly SQL syntax.") + if cleaned.upper().startswith("WHERE "): + cleaned = cleaned[6:].strip() + if not cleaned: + return None + return cleaned + + +def _render_attribute_value(value: Any) -> str: + text = str(value) + escaped = text.replace("\\", "\\\\").replace('"', '\\"') + return f'"{escaped}"' + + +def _render_attributes(attributes: dict[str, Any] | None) -> list[str]: + if not attributes: + return [] + rendered = [] + for key, value in attributes.items(): + safe_key = _validate_identifier(str(key), "attribute key") + rendered.append(f'"{safe_key}"={_render_attribute_value(value)}') + return rendered + + +def _normalize_expressions(expressions: list[str] | str | None, *, dialect: str) -> list[str]: + if expressions is None: + raise ValueError("expressions is required.") + raw_values = [expressions] if isinstance(expressions, str) else list(expressions) + if not raw_values: + raise ValueError("expressions cannot be empty.") + return [_validate_expression(str(value), dialect=dialect) for value in raw_values] + + +def _build_udf_query_plan( + *, + dialect: str, + function_name: str, + expressions: list[str] | str, + table_name: str | None = None, + from_path: str | None = None, + attributes: dict[str, Any] | None = None, + where_clause: str | None = None, + limit: int | None = None, + alias: str | None = None, + align_by_device: bool = False, +) -> dict[str, Any]: + safe_dialect = str(dialect or "").strip().lower() + if safe_dialect not in {"tree", "table"}: + raise ValueError("dialect must be tree or table.") + safe_function = _validate_function_name(function_name) + safe_expressions = _normalize_expressions(expressions, dialect=safe_dialect) + function_args = safe_expressions + _render_attributes(attributes) + projection = f"{safe_function}({', '.join(function_args)})" + if alias: + projection += f" AS {_validate_identifier(alias, 'alias')}" + + where = _validate_where_clause(where_clause) + clauses: list[str] + if safe_dialect == "table": + source = _validate_identifier(str(table_name or ""), "table_name") + clauses = [f"SELECT {projection}", f"FROM {source}"] + else: + source = _validate_tree_path(str(from_path or "")) + clauses = [f"SELECT {projection}", f"FROM {source}"] + + if where: + clauses.append(f"WHERE {where}") + if limit is not None: + safe_limit = int(limit) + if safe_limit <= 0: + raise ValueError("limit must be positive.") + clauses.append(f"LIMIT {safe_limit}") + if safe_dialect == "tree" and align_by_device: + clauses.append("ALIGN BY DEVICE") + + sql = " ".join(clauses) + return { + "version": "v0", + "kind": "iotdb_udf_query_plan_ir", + "sql": sql, + "dialect": safe_dialect, + "function_name": safe_function, + "expressions": safe_expressions, + "source": {"table_name": source} if safe_dialect == "table" else {"from_path": source}, + "attributes": attributes or {}, + "where_clause": where, + "limit": limit, + "alias": alias, + "align_by_device": bool(align_by_device), + "readonly": True, + } + + +def _export_dataset( + *, + res: Any, + session: Any, + selected_config: Config, + tool_name: str, + query_sql: str, + filename: str | None, + fmt: str, + logger: logging.Logger, +) -> list[TextContent]: + try: + df = res.todf() + finally: + session.close() + + timestamp = int(datetime.datetime.now().timestamp()) + if filename is None: + filename = f"udf_{uuid.uuid4().hex[:4]}_{timestamp}" + + fmt_lower = fmt.lower() + if fmt_lower == "csv": + if filename.lower().endswith(".csv"): + filename = filename[:-4] + filepath = sanitize_filename(f"{filename}.csv", selected_config.export_path) + df.to_csv(filepath, index=False) + elif fmt_lower == "excel": + if filename.lower().endswith(".xlsx"): + filename = filename[:-5] + filepath = sanitize_filename(f"{filename}.xlsx", selected_config.export_path) + df.to_excel(filepath, index=False) + else: + raise ValueError("format must be either 'csv' or 'excel'.") + + preview_rows = min(10, len(df)) + preview_data = [",".join(df.columns)] + for index in range(preview_rows): + preview_data.append(",".join(map(str, df.iloc[index]))) + logger.info("Exported UDF query result to %s", filepath) + return text_payload_response( + tool_name, + f"Query results exported to {filepath}\n\nSQL:\n{query_sql}\n\nPreview (first {preview_rows} rows):\n" + + "\n".join(preview_data), + ) + + +def _prepare_udf_res( + res: Any, + session: Any, + tool_name: str, + export_path: str, + plan: dict[str, Any], + owner_session_id: str | None = None, + max_inline_rows: int | None = None, + page_size_rows: int | None = None, +) -> list[TextContent]: + columns = res.get_column_names() + + def rows(): + while res.has_next(): + row = res.next().get_fields() Review Comment: **[P2] Include the Tree timestamp when serializing UDF results** - For Tree `SessionDataSet`, `get_column_names()` includes `Time`, while `RowRecord.get_fields()` excludes the timestamp. - This produces a two-column header such as `Time,sin(...)` with one value per data row, shifting every value under the wrong column. - `_prepare_tree_res()` already handles this correctly by prepending `record.get_timestamp()`. Please apply the same Tree-specific serialization here. ########## src/iotdb_mcp_server/services/database.py: ########## @@ -0,0 +1,319 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +import logging +import re + +from iotdb.Session import Session +from iotdb.table_session import TableSession +from iotdb.utils.SessionDataSet import SessionDataSet +from mcp.types import TextContent + +from iotdb_mcp_server.config import Config +from iotdb_mcp_server.runtime_policy import dynamic_env_bool +from iotdb_mcp_server.runtime_policy import dynamic_getenv +from iotdb_mcp_server.runtime_policy import strict_permission_enforcement +from iotdb_mcp_server.services.json_response import ( + csv_payload_response, + sql_success_response, +) +from iotdb_mcp_server.services.target_selection import ( + iotdb_target_response_context, + select_target_config, + table_session_pool, + tree_session_pool, +) + +_TABLE_DB_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +_TREE_DB_PATTERN = re.compile(r"^root(?:\.[A-Za-z_][A-Za-z0-9_]*)+$") + + +def _env_bool(name: str, default: bool) -> bool: + return dynamic_env_bool(name, default) + + +def _csv_set(value: str) -> set[str]: + return {item.strip() for item in value.split(",") if item.strip()} + + +def _assert_database_ddl_permission( + config: Config, action: str, confirm: bool = False +) -> None: + if strict_permission_enforcement(): + if not _env_bool("IOTDB_ENABLE_DATABASE_DDL", False): + raise PermissionError( + "Database DDL tool is disabled by strict MCP policy. " + "Set IOTDB_ENABLE_DATABASE_DDL=true to enable." + ) + + allowed_users = _csv_set(dynamic_getenv("IOTDB_DATABASE_DDL_ALLOWED_USERS", "root") or "root") + if "*" not in allowed_users and config.user not in allowed_users: + raise PermissionError( + f"Current MCP user '{config.user}' is not allowed by IOTDB_DATABASE_DDL_ALLOWED_USERS." + ) + + if action == "DROP" and _env_bool("IOTDB_REQUIRE_DROP_CONFIRM", True) and not confirm: + raise PermissionError( + "DROP DATABASE requires confirm=True by server policy." + ) + + +def _validate_database_name(sql_dialect: str, database: str) -> str: + raw = database.strip() + if not raw: + raise ValueError("Database name/path cannot be empty.") + + if sql_dialect == "tree": + if not _TREE_DB_PATTERN.fullmatch(raw): + raise ValueError( + "Invalid tree database path. Expected pattern like root.sg or root.sg1.dev." + ) + elif sql_dialect == "table": + if not _TABLE_DB_PATTERN.fullmatch(raw): + raise ValueError( + "Invalid table database name. Use letters, numbers, and underscore only." + ) + else: + raise ValueError( + f"Unsupported sql_dialect '{sql_dialect}'. Expected 'tree' or 'table'." + ) + return raw + + +def _format_result( + res: SessionDataSet, + session_or_table_session: Session | TableSession, + tool_name: str, +) -> list[TextContent]: + columns = res.get_column_names() + rows: list[str] = [] + while res.has_next(): + row = res.next().get_fields() + rows.append(",".join(map(str, row))) + session_or_table_session.close() + return csv_payload_response(tool_name, columns, rows) + + +def register_database_tools(mcp, config: Config, logger: logging.Logger) -> None: + """Register database management tools with per-call IoTDB target selection.""" + max_pool_size = 100 + + @mcp.tool() + async def list_databases( + details: bool = False, + target_id: str | None = None, + target: dict[str, object] | None = None, + ) -> list[TextContent]: + """List databases in the selected IoTDB target.""" + selected_config = select_target_config(config, target_id=target_id, target=target) + with iotdb_target_response_context(selected_config): + sql = "SHOW DATABASES DETAILS" if details else "SHOW DATABASES" + if selected_config.sql_dialect == "tree": + _, session_pool = tree_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + wait_timeout_in_ms=5000, + tool_name="list_databases", + ) + session = None + try: + session = session_pool.get_session() + res = session.execute_query_statement(sql) + return _format_result(res, session, "list_databases") + except Exception as e: + if session: + session.close() + logger.error(f"Failed to list databases: {str(e)}") + raise + + _, session_pool = table_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + tool_name="list_databases", + ) + table_session = None + try: + table_session = session_pool.get_session() + res = table_session.execute_query_statement(sql) + return _format_result(res, table_session, "list_databases") + except Exception as e: + if table_session: + table_session.close() + logger.error(f"Failed to list databases: {str(e)}") + raise + + @mcp.tool() + async def create_database( + database: str, + if_not_exists: bool = True, + target_id: str | None = None, + target: dict[str, object] | None = None, + ) -> list[TextContent]: + """Create a database/storage group in the selected IoTDB target.""" + selected_config = select_target_config(config, target_id=target_id, target=target) + with iotdb_target_response_context(selected_config): + if selected_config.sql_dialect == "tree": + _, session_pool = tree_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + wait_timeout_in_ms=5000, + tool_name="create_database", + ) + session = None + try: + _assert_database_ddl_permission(selected_config, action="CREATE") + database_path = _validate_database_name( + selected_config.sql_dialect, database + ) + sql = f"CREATE DATABASE {database_path}" + session = session_pool.get_session() + session.execute_non_query_statement(sql) + session.close() + return sql_success_response("create_database", sql) + except Exception as e: + if session: + session.close() + logger.error(f"Failed to create database: {str(e)}") + raise + + _, session_pool = table_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + tool_name="create_database", + ) + table_session = None + try: + _assert_database_ddl_permission(selected_config, action="CREATE") + database_name = _validate_database_name( + selected_config.sql_dialect, database + ) + sql = ( + f"CREATE DATABASE IF NOT EXISTS {database_name}" + if if_not_exists + else f"CREATE DATABASE {database_name}" + ) + table_session = session_pool.get_session() + table_session.execute_non_query_statement(sql) + table_session.close() + return sql_success_response("create_database", sql) + except Exception as e: + if table_session: + table_session.close() + logger.error(f"Failed to create database: {str(e)}") + raise + + @mcp.tool() + async def drop_database( + database: str, + if_exists: bool = True, + confirm: bool = False, + target_id: str | None = None, + target: dict[str, object] | None = None, + ) -> list[TextContent]: + """Drop a database/storage group in the selected IoTDB target.""" + selected_config = select_target_config(config, target_id=target_id, target=target) + with iotdb_target_response_context(selected_config): + if selected_config.sql_dialect == "tree": + _, session_pool = tree_session_pool( + selected_config, + max_pool_size=max_pool_size, + wait_timeout_in_ms=5000, + tool_name="drop_database", + ) + session = None + try: + _assert_database_ddl_permission( + selected_config, action="DROP", confirm=confirm + ) + database_path = _validate_database_name( + selected_config.sql_dialect, database + ) + sql = f"DROP DATABASE {database_path}" + session = session_pool.get_session() + session.execute_non_query_statement(sql) + session.close() + return sql_success_response("drop_database", sql) + except Exception as e: + if session: + session.close() + logger.error(f"Failed to drop database: {str(e)}") + raise + + _, session_pool = table_session_pool( + selected_config, + max_pool_size=max_pool_size, + tool_name="drop_database", + ) + table_session = None + try: + _assert_database_ddl_permission( + selected_config, action="DROP", confirm=confirm + ) + database_name = _validate_database_name( + selected_config.sql_dialect, database + ) + sql = ( + f"DROP DATABASE IF EXISTS {database_name}" + if if_exists + else f"DROP DATABASE {database_name}" + ) + table_session = session_pool.get_session() + table_session.execute_non_query_statement(sql) + table_session.close() + return sql_success_response("drop_database", sql) + except Exception as e: + if table_session: + table_session.close() + logger.error(f"Failed to drop database: {str(e)}") + raise + + @mcp.tool() + async def use_database( + database: str, + target_id: str | None = None, + target: dict[str, object] | None = None, + ) -> list[TextContent]: + """Switch current database in a table-model IoTDB target.""" + selected_config, session_pool = table_session_pool( + config, + target_id=target_id, + target=target, + max_pool_size=max_pool_size, + tool_name="use_database", + ) + with iotdb_target_response_context(selected_config): + table_session = None + try: + database_name = _validate_database_name( + selected_config.sql_dialect, database + ) + sql = f"USE {database_name}" + table_session = session_pool.get_session() + table_session.execute_non_query_statement(sql) Review Comment: **[P1] Make database switching deterministic across pooled sessions** - `USE` changes only the one borrowed session; the selected target and other pooled sessions retain the original database. - Different tools can use pools with different cache keys and therefore continue querying the old database. I reproduced a successful `USE other_db`, followed by `read_query` using `other_db` while `sql_executor_batch` used `original_db`; the response context also still reported `original_db`. - A pool with multiple established connections can likewise alternate between old and new database state. Please update the target database and rebuild the relevant pools, or make database selection an explicit per-call input instead of mutating one pooled connection. ########## src/iotdb_mcp_server/session_manager.py: ########## @@ -0,0 +1,376 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +from __future__ import annotations + +from typing import Any, Callable, Mapping + +from iotdb.SessionPool import PoolConfig, SessionPool +from iotdb.table_session import TableSession +from iotdb.table_session_pool import TableSessionPoolConfig +from iotdb.utils.exception import IoTDBConnectionException + +from iotdb_mcp_server.target_registry import ( + IoTDBTarget, + IoTDBTargetRegistry, + merge_target, + target_from_mapping, +) + + +def target_from_config(config: Any) -> IoTDBTarget: + if isinstance(config, IoTDBTarget): + return config + if hasattr(config, "to_target"): + return config.to_target() + + keys = ( + "target_id", + "display_name", + "target_kind", + "kind", + "host", + "port", + "node_urls", + "user", + "password", + "database", + "sql_dialect", + "timezone", + "export_path", + "iotdb_home", + "use_ssl", + "ca_certs", + "connection_timeout_in_ms", + "enable_redirection", + "enable_compression", + "fetch_size", + "max_retry", + "max_pool_size", + "tree_wait_timeout_in_ms", + "table_wait_timeout_in_ms", + "policy", + "last_known_good_credential", + "verified_at", + ) + payload: dict[str, Any] = {} + for key in keys: + if hasattr(config, key): + payload[key] = getattr(config, key) + if "target_kind" in payload and "kind" not in payload: + payload["kind"] = payload["target_kind"] + return target_from_mapping(payload) + + +def _target_with_overrides( + config_or_target: Any, + overrides: Mapping[str, Any] | None = None, +) -> IoTDBTarget: + target = target_from_config(config_or_target) + clean_overrides = { + key: value for key, value in (overrides or {}).items() if value is not None + } + if not clean_overrides: + return target + return merge_target(target, clean_overrides) + + +def make_tree_pool_config(target: IoTDBTarget) -> PoolConfig: + return PoolConfig( + host=target.host, + port=target.port, + node_urls=None, + user_name=target.user, + password=target.password, + fetch_size=target.fetch_size, + time_zone=target.timezone, + max_retry=target.max_retry, + enable_compression=target.enable_compression, + enable_redirection=target.enable_redirection, + use_ssl=target.use_ssl, + ca_certs=target.ca_certs or None, + connection_timeout_in_ms=target.connection_timeout_in_ms, + ) + + +def make_table_pool_config( + target: IoTDBTarget, database: str | None = None +) -> TableSessionPoolConfig: + resolved_database = database if database is not None else target.database + return TableSessionPoolConfig( + node_urls=list(target.node_urls), + username=target.user, + password=target.password, + max_pool_size=target.max_pool_size, + database=resolved_database or None, + fetch_size=target.fetch_size, + time_zone=target.timezone, + enable_redirection=target.enable_redirection, + enable_compression=target.enable_compression, + wait_timeout_in_ms=target.table_wait_timeout_in_ms, + max_retry=target.max_retry, + use_ssl=target.use_ssl, + ca_certs=target.ca_certs or None, + connection_timeout_in_ms=target.connection_timeout_in_ms, + ) + + +def create_tree_session_pool( + config_or_target: Any, + max_pool_size: int | None = None, + wait_timeout_in_ms: int | None = None, +) -> SessionPool: + target = _target_with_overrides( + config_or_target, + { + "max_pool_size": max_pool_size, + "tree_wait_timeout_in_ms": wait_timeout_in_ms, + }, + ) + return SessionPool( + make_tree_pool_config(target), + target.max_pool_size, + target.tree_wait_timeout_in_ms, + ) + + +def create_table_session_pool( + config_or_target: Any, + max_pool_size: int | None = None, + database: str | None = None, + wait_timeout_in_ms: int | None = None, +) -> Any: + target = _target_with_overrides( + config_or_target, + { + "max_pool_size": max_pool_size, + "database": database, + "table_wait_timeout_in_ms": wait_timeout_in_ms, + }, + ) + return _SingleEndpointTableSessionPool(target) + + +class _SingleEndpointTableSessionPool: + """TableSessionPool equivalent that opens only the target's primary endpoint.""" + + def __init__(self, target: IoTDBTarget) -> None: + self.database = target.database or None + self._session_pool = SessionPool( + make_tree_pool_config(target), + target.max_pool_size, + target.table_wait_timeout_in_ms, + ) + self._session_pool.sql_dialect = "table" + self._session_pool.database = self.database + + def get_session(self) -> TableSession: + return TableSession(None, session_pool=self._session_pool) + + def close(self) -> None: + self._session_pool.close() + + +def is_iotdb_connection_error(error: BaseException) -> bool: + current: BaseException | None = error + seen: set[int] = set() + while current is not None and id(current) not in seen: + seen.add(id(current)) + if isinstance(current, (IoTDBConnectionException, ConnectionError, OSError)): + return True + message = str(current).lower() + if any( + marker in message + for marker in ( + "801: authentication failed", + "status code 801", + "822:", + "status code 822", + ) + ): + return True + current = current.__cause__ or current.__context__ + return False + + +class _ManagedSession: + def __init__(self, session: Any, on_connection_error: Callable[[BaseException], None]): + self._session = session + self._on_connection_error = on_connection_error + + def __getattr__(self, name: str) -> Any: + attribute = getattr(self._session, name) + if not callable(attribute): + return attribute + + def managed_call(*args: Any, **kwargs: Any) -> Any: + try: + return attribute(*args, **kwargs) + except Exception as exc: + if is_iotdb_connection_error(exc): + self._on_connection_error(exc) + raise + + return managed_call + + +class _ManagedPool: + def __init__(self, pool: Any, on_connection_error: Callable[[BaseException], None]): + self._pool = pool + self._on_connection_error = on_connection_error + + def get_session(self) -> _ManagedSession: + try: + session = self._pool.get_session() + except Exception as exc: + if is_iotdb_connection_error(exc): + self._on_connection_error(exc) + raise + return _ManagedSession(session, self._on_connection_error) Review Comment: **[P1] Return Tree sessions to `SessionPool` instead of closing the borrowed connection** - The IoTDB `SessionPool` increments its internal pool size on `get_session()` and expects callers to use `put_back(session)`. - `_ManagedSession.close()` currently forwards to the raw session, so the pool slot is never returned or decremented. Repeated Tree tool calls therefore exhaust the pool. - With `sql_executor_batch(max_concurrency=1)`, I reproduced one successful statement followed by a pool timeout on the second statement. Because `TimeoutError` is also an `OSError`, the connection-error callback then removes the otherwise healthy target. The managed wrapper needs pool-aware release semantics, with broken connections discarded separately. ########## src/iotdb_mcp_server/config.py: ########## @@ -49,82 +82,244 @@ class Config: database: str """ - IoTDB database + IoTDB database/session scope. + Table dialect: current database name. + Tree dialect: optional root scope hint; tree SQL still uses explicit root paths in queries. """ sql_dialect: str """ SQL dialect: tree or table """ + + timezone: str + """ + IoTDB session timezone. + """ export_path: str """ Path for exporting query results """ + target_id: str = "default" + display_name: str = "Default IoTDB" + target_kind: str = "local" + node_urls: tuple[str, ...] = () + iotdb_home: str = "" + use_ssl: bool = False + ca_certs: str = "" + connection_timeout_in_ms: int | None = None + enable_redirection: bool = True + enable_compression: bool = False + fetch_size: int = 1024 + max_retry: int = 3 + max_pool_size: int = 100 + tree_wait_timeout_in_ms: int = 5000 + table_wait_timeout_in_ms: int = 10000 + target_fingerprint: str = "" + policy: dict[str, str] = field(default_factory=dict) + last_known_good_credential: dict[str, object] = field(default_factory=dict) + verified_at: str = "" + target_registry: IoTDBTargetRegistry | None = field(default=None, repr=False, compare=False) + session_manager: Any | None = field(default=None, repr=False, compare=False) + targets_file: str = "" + targets_json: str = field(default="", repr=False, compare=False) + targets_file_mtime_ns: int | None = field(default=None, repr=False, compare=False) + + @classmethod + def from_target( + cls, + target: IoTDBTarget, + target_registry: IoTDBTargetRegistry | None = None, + session_manager: Any | None = None, + ) -> "Config": + return cls( + host=target.host, + port=target.port, + user=target.user, + password=target.password, + database=target.database, + sql_dialect=target.sql_dialect, + timezone=target.timezone, + export_path=target.export_path, + target_id=target.target_id, + display_name=target.display_name, + target_kind=target.kind, + node_urls=target.node_urls, + iotdb_home=target.iotdb_home, + use_ssl=target.use_ssl, + ca_certs=target.ca_certs, + connection_timeout_in_ms=target.connection_timeout_in_ms, + enable_redirection=target.enable_redirection, + enable_compression=target.enable_compression, + fetch_size=target.fetch_size, + max_retry=target.max_retry, + max_pool_size=target.max_pool_size, + tree_wait_timeout_in_ms=target.tree_wait_timeout_in_ms, + table_wait_timeout_in_ms=target.table_wait_timeout_in_ms, + target_fingerprint=target.fingerprint(), + policy={str(key): str(value) for key, value in target.policy.items()}, + last_known_good_credential=dict(target.last_known_good_credential), + verified_at=target.verified_at, + target_registry=target_registry, + session_manager=session_manager, + ) + + def to_target(self) -> IoTDBTarget: + return IoTDBTarget( + target_id=self.target_id, + display_name=self.display_name, + kind=self.target_kind, + host=self.host, + port=self.port, + node_urls=tuple(self.node_urls) or (f"{self.host}:{self.port}",), + user=self.user, + password=self.password, + database=self.database, + sql_dialect=self.sql_dialect, + timezone=self.timezone, + export_path=self.export_path, + iotdb_home=self.iotdb_home, + use_ssl=self.use_ssl, + ca_certs=self.ca_certs, + connection_timeout_in_ms=self.connection_timeout_in_ms, + enable_redirection=self.enable_redirection, + enable_compression=self.enable_compression, + fetch_size=self.fetch_size, + max_retry=self.max_retry, + max_pool_size=self.max_pool_size, + tree_wait_timeout_in_ms=self.tree_wait_timeout_in_ms, + table_wait_timeout_in_ms=self.table_wait_timeout_in_ms, + policy=dict(self.policy), + last_known_good_credential=dict(self.last_known_good_credential), + verified_at=self.verified_at, + ) + + def safe_dict(self) -> dict[str, object]: + target = self.to_target() + safe = target.as_dict(include_secret=False) + safe["password"] = "***" if self.password else "" + return safe + @staticmethod def from_env_arguments() -> "Config": """ Parse command line arguments. """ parser = argparse.ArgumentParser(description="IoTDB MCP Server") + parser.add_argument("--target-id", type=str, default=None, help="Named IoTDB target id") parser.add_argument( - "--host", + "--targets-file", type=str, - help="IoTDB host", - default=os.getenv("IOTDB_HOST", "127.0.0.1"), + default=None, + help="JSON IoTDB target registry file", ) + parser.add_argument("--host", type=str, help="IoTDB host", default=None) parser.add_argument( "--port", type=int, help="IoTDB MySQL protocol port", - default=os.getenv("IOTDB_PORT", 6667), + default=None, ) parser.add_argument( "--user", type=str, help="IoTDB username", - default=os.getenv("IOTDB_USER", "root"), + default=None, ) parser.add_argument( "--password", type=str, help="IoTDB password", - default=os.getenv("IOTDB_PASSWORD", "root"), + default=None, ) parser.add_argument( "--database", type=str, - help="IoTDB connect database name", - default=os.getenv("IOTDB_DATABASE", "test"), + help="IoTDB database/session scope. Table dialect uses database name; tree dialect still requires explicit root paths in SQL.", + default=None, ) parser.add_argument( "--sql-dialect", type=str, help="SQL dialect: tree or table", - default=os.getenv("IOTDB_SQL_DIALECT", "table"), + default=None, + ) + + parser.add_argument( + "--timezone", + type=str, + help="IoTDB session timezone", + default=None, ) parser.add_argument( "--export-path", type=str, help="Path for exporting query results", - default=os.getenv("IOTDB_EXPORT_PATH", "/tmp"), + default=None, ) + parser.add_argument("--node-urls", type=str, default=None, help="Comma-separated IoTDB node URLs") + parser.add_argument("--use-ssl", choices=("true", "false"), default=None) + parser.add_argument("--ca-certs", type=str, default=None) + parser.add_argument("--connection-timeout-ms", type=int, default=None) + parser.add_argument("--enable-redirection", choices=("true", "false"), default=None) + parser.add_argument("--enable-compression", choices=("true", "false"), default=None) + parser.add_argument("--fetch-size", type=int, default=None) + parser.add_argument("--max-retry", type=int, default=None) + parser.add_argument("--max-pool-size", type=int, default=None) + parser.add_argument("--wait-timeout-ms", type=int, default=None) args = parser.parse_args() - return Config( - host=args.host, - port=args.port, - user=args.user, - password=args.password, - database=args.database, - sql_dialect=args.sql_dialect, - export_path=args.export_path, + targets_file = args.targets_file or os.getenv("TIMESEEK_IOTDB_TARGETS_FILE", "") + targets_json = os.getenv("TIMESEEK_IOTDB_TARGETS_JSON", "") + registry = IoTDBTargetRegistry.from_env( + targets_file=targets_file or None, + targets_json=targets_json or None, + ) + if registry.list_targets(include_secret=False): + target = registry.resolve( + args.target_id or os.getenv("TIMESEEK_IOTDB_TARGET_ID") + ) + else: + target = target_from_mapping( + { + "target_id": "unverified-template", + "display_name": "Unverified IoTDB template", + "host": args.host or os.getenv("IOTDB_HOST") or "127.0.0.1", + "port": args.port or os.getenv("IOTDB_PORT") or 6667, + "user": args.user or os.getenv("IOTDB_USER") or "root", + "password": args.password + if args.password is not None + else os.getenv("IOTDB_PASSWORD", ""), + "database": args.database or os.getenv("IOTDB_DATABASE") or "test", + "sql_dialect": args.sql_dialect + or os.getenv("IOTDB_SQL_DIALECT") + or "tree", + "timezone": args.timezone or os.getenv("IOTDB_TIMEZONE") or "+00:00", + "export_path": args.export_path or default_export_path(), + "node_urls": args.node_urls, + } + ) + from iotdb_mcp_server.session_manager import IoTDBSessionManager + + config = Config.from_target( + target, + target_registry=registry, Review Comment: **[P1] Make the legacy single-target configuration routable** - When no registry file or JSON is configured, the code builds an `unverified-template` target from `IOTDB_*`. - It then creates `IoTDBSessionManager` with the still-empty registry rather than registering that fallback target. - Consequently, the first call to `select_target_config()` fails with `No verified IoTDB target is registered`, so existing deployments using only `IOTDB_HOST`, `IOTDB_USER`, and related variables cannot run any database tool. This contradicts the migration note that legacy single-target variables remain supported as fallback. Please either publish the legacy target into the manager registry or remove the compatibility claim and require explicit migration. ########## src/iotdb_mcp_server/runtime_policy.py: ########## @@ -0,0 +1,327 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +from __future__ import annotations + +from collections.abc import Mapping +import json +import os +from pathlib import Path +import re +from threading import RLock +from typing import Any + + +_DEFAULT_SERVER_NAME = "iotdb" +_SHELL_DEFAULT_RE = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*):-([^}]*)\}$") +_SENSITIVE_KEY_RE = re.compile(r"(PASSWORD|SECRET|TOKEN|API_KEY|ACCESS_KEY)", re.IGNORECASE) +_SESSION_POLICY_LOCK = RLock() +_SESSION_POLICY: dict[str, str] = {} + +_POLICY_KEYS = frozenset( + { + "IOTDB_ENABLE_METADATA_QUERY", + "IOTDB_METADATA_ALLOWED_USERS", + "IOTDB_ENABLE_DATABASE_DDL", + "IOTDB_DATABASE_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_DROP_CONFIRM", + "IOTDB_ENABLE_TABLE_DDL", + "IOTDB_TABLE_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_TABLE_DROP_CONFIRM", + "IOTDB_ENABLE_TIMESERIES_DDL", + "IOTDB_TIMESERIES_DDL_ALLOWED_USERS", + "IOTDB_REQUIRE_TIMESERIES_DROP_CONFIRM", + "IOTDB_ENABLE_TTL_SQL", + "IOTDB_TTL_ALLOWED_USERS", + "IOTDB_REQUIRE_TTL_UNSET_CONFIRM", + "IOTDB_ENABLE_WRITE_DML", + "IOTDB_WRITE_ALLOWED_USERS", + "IOTDB_REQUIRE_DELETE_CONFIRM", + "IOTDB_ENABLE_SQL_DRIVER", + "IOTDB_SQL_DRIVER_ALLOWED_USERS", + "IOTDB_SQL_DRIVER_MODE", + "IOTDB_SQL_DRIVER_REQUIRE_DESTRUCTIVE_CONFIRM", + "IOTDB_SQL_DRIVER_EXTRA_READONLY_PREFIXES", + "IOTDB_SQL_DRIVER_EXTRA_DDL_PREFIXES", + "IOTDB_SQL_DRIVER_EXTRA_FULL_PREFIXES", + "IOTDB_ENABLE_MODEL_MANAGEMENT", + "IOTDB_MODEL_ALLOWED_USERS", + "IOTDB_REQUIRE_MODEL_DESTRUCTIVE_CONFIRM", + "TIMESEEK_MCP_PERMISSION_ENFORCEMENT", + "IOTDB_STRICT_PERMISSION_ENFORCEMENT", + } +) + +_FULL_PERMISSION_DEFAULTS = { + "IOTDB_ENABLE_METADATA_QUERY": "true", + "IOTDB_METADATA_ALLOWED_USERS": "*", + "IOTDB_ENABLE_DATABASE_DDL": "true", + "IOTDB_DATABASE_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TABLE_DDL": "true", + "IOTDB_TABLE_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TABLE_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TIMESERIES_DDL": "true", + "IOTDB_TIMESERIES_DDL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TIMESERIES_DROP_CONFIRM": "true", + "IOTDB_ENABLE_TTL_SQL": "true", + "IOTDB_TTL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_TTL_UNSET_CONFIRM": "true", + "IOTDB_ENABLE_WRITE_DML": "true", + "IOTDB_WRITE_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_DELETE_CONFIRM": "true", + "IOTDB_ENABLE_SQL_DRIVER": "true", + "IOTDB_SQL_DRIVER_ALLOWED_USERS": "*", + "IOTDB_SQL_DRIVER_MODE": "full", + "IOTDB_SQL_DRIVER_REQUIRE_DESTRUCTIVE_CONFIRM": "true", + "IOTDB_ENABLE_MODEL_MANAGEMENT": "true", + "IOTDB_MODEL_ALLOWED_USERS": "*", + "IOTDB_REQUIRE_MODEL_DESTRUCTIVE_CONFIRM": "true", + "TIMESEEK_MCP_PERMISSION_ENFORCEMENT": "advisory", + "IOTDB_STRICT_PERMISSION_ENFORCEMENT": "false", +} + +_PRESET_POLICIES = { + "full": dict(_FULL_PERMISSION_DEFAULTS), + "ddl": { + **_FULL_PERMISSION_DEFAULTS, + "IOTDB_SQL_DRIVER_MODE": "ddl", + "IOTDB_ENABLE_WRITE_DML": "false", + }, + "readonly": { + **_FULL_PERMISSION_DEFAULTS, Review Comment: **[P1] Preserve strict enforcement when applying restrictive presets** - `_FULL_PERMISSION_DEFAULTS` sets `TIMESEEK_MCP_PERMISSION_ENFORCEMENT=advisory` and `IOTDB_STRICT_PERMISSION_ENFORCEMENT=false`. - Every preset copies those values, and the session overlay has higher precedence than the process environment. - Reproduction: start with `IOTDB_STRICT_PERMISSION_ENFORCEMENT=true`, then call `set_iotdb_session_policy(preset="readonly")`. `strict_permission_enforcement()` becomes false, so an INSERT passes `_assert_write_permission` even though this preset sets `IOTDB_ENABLE_WRITE_DML=false`. Please keep the enforcement mode outside capability presets, or make restrictive presets preserve the existing enforcement mode. ########## src/iotdb_mcp_server/result_store.py: ########## @@ -0,0 +1,837 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +from __future__ import annotations + +from dataclasses import dataclass +from datetime import timedelta +from datetime import datetime, timezone +import json +import os +from pathlib import Path +import re +import shutil +from typing import Any, Iterable +import uuid + +_RESULT_ID_PATTERN = re.compile(r"^res_[0-9]{8}T[0-9]{6}Z_[a-f0-9]{16}$") +_OWNER_PATTERN = re.compile(r"^[A-Za-z0-9_.:-]{1,180}$") +_MANIFEST_NAME = "manifest.json" +_STANDALONE_OWNER = "standalone" + + +def _env_int(name: str, default: int, minimum: int = 1) -> int: + raw = os.getenv(name, "").strip() + if not raw: + return default + try: + return max(minimum, int(raw)) + except ValueError: + return default + + +def _bounded_int(value: Any, default: int, minimum: int = 1, maximum: int | None = None) -> int: + if value is None or str(value).strip() == "": + resolved = default + else: + resolved = int(value) + resolved = max(minimum, resolved) + if maximum is not None: + resolved = min(maximum, resolved) + return resolved + + +def _safe_owner_session_id(value: str | None) -> str: + raw = ( + value + or os.getenv("TIMESEEK_MCP_SESSION_ID", "").strip() + or os.getenv("TIMESEEK_CODEX_SESSION_ID", "").strip() + or _STANDALONE_OWNER + ) + cleaned = re.sub(r"[^A-Za-z0-9_.:-]+", "_", str(raw)).strip("_") + if not cleaned: + cleaned = _STANDALONE_OWNER + cleaned = cleaned[:180] + if not _OWNER_PATTERN.fullmatch(cleaned): + raise ValueError("Invalid owner_session_id.") + return cleaned + + +@dataclass(frozen=True) +class ResultStoreSettings: + preview_rows: int = 50 + page_size_rows: int = 500 + max_page_rows: int = 5000 + shard_rows: int = 10000 + shard_bytes: int = 8 * 1024 * 1024 + ttl_seconds: int = 24 * 60 * 60 + max_session_results: int = 100 + max_session_bytes: int = 512 * 1024 * 1024 + max_global_results: int = 1000 + max_global_bytes: int = 2 * 1024 * 1024 * 1024 + + @classmethod + def from_env(cls) -> "ResultStoreSettings": + return cls( + preview_rows=_env_int("TIMESEEK_RESULT_PREVIEW_ROWS", 50, minimum=0), + page_size_rows=_env_int("TIMESEEK_RESULT_PAGE_SIZE_ROWS", 500), + max_page_rows=_env_int("TIMESEEK_RESULT_MAX_PAGE_ROWS", 5000), + shard_rows=_env_int("TIMESEEK_RESULT_SHARD_ROWS", 10000), + shard_bytes=_env_int("TIMESEEK_RESULT_SHARD_BYTES", 8 * 1024 * 1024), + ttl_seconds=_env_int( + "TIMESEEK_RESULT_TTL_SECONDS", 24 * 60 * 60, minimum=0 + ), + max_session_results=_env_int( + "TIMESEEK_RESULT_MAX_SESSION_RESULTS", 100, minimum=0 + ), + max_session_bytes=_env_int( + "TIMESEEK_RESULT_MAX_SESSION_BYTES", 512 * 1024 * 1024, minimum=0 + ), + max_global_results=_env_int( + "TIMESEEK_RESULT_MAX_GLOBAL_RESULTS", 1000, minimum=0 + ), + max_global_bytes=_env_int( + "TIMESEEK_RESULT_MAX_GLOBAL_BYTES", + 2 * 1024 * 1024 * 1024, + minimum=0, + ), + ) + + +@dataclass(frozen=True) +class StoredCsvResult: + result_id: str + owner_session_id: str + columns: list[str] + preview_rows: list[str] + row_count: int + byte_count: int + page_size_rows: int + manifest_path: str + shard_count: int + + +@dataclass(frozen=True) +class ResultStoreEntry: + result_id: str + owner_session_id: str + tool: str + row_count: int + byte_count: int + storage_bytes: int + shard_count: int + created_at: datetime + last_accessed_at: datetime + manifest_path: Path + result_dir: Path + legacy: bool = False + + def to_payload(self) -> dict[str, Any]: + return { + "result_id": self.result_id, + "owner_session_id": self.owner_session_id, + "tool": self.tool, + "row_count": self.row_count, + "byte_count": self.byte_count, + "storage_bytes": self.storage_bytes, + "shard_count": self.shard_count, + "created_at": self.created_at.isoformat(), + "last_accessed_at": self.last_accessed_at.isoformat(), + "manifest_path": str(self.manifest_path), + "legacy": self.legacy, + } + + +class FileResultStore: + """File-backed store for large MCP result sets. + + Rows are stored as JSON lines so callers can fetch a page without parsing a + whole CSV file. The public row representation intentionally remains the + existing CSV row string used by the IoTDB MCP response schema. + """ + + def __init__( + self, + root_dir: str | os.PathLike[str], + settings: ResultStoreSettings | None = None, + ) -> None: + self.root_dir = Path(root_dir).expanduser().resolve() + self.settings = settings or ResultStoreSettings.from_env() + + def _ensure_root(self) -> None: + self.root_dir.mkdir(parents=True, exist_ok=True) + + def _new_result_id(self) -> str: + timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + return f"res_{timestamp}_{uuid.uuid4().hex[:16]}" + + def _session_dir(self, owner_session_id: str | None = None) -> Path: + owner = _safe_owner_session_id(owner_session_id) + session_dir = (self.root_dir / "sessions" / owner).resolve() + sessions_root = (self.root_dir / "sessions").resolve() + if not str(session_dir).startswith(str(sessions_root) + os.sep): + raise ValueError("Invalid owner_session_id path.") + return session_dir + + def _legacy_result_dir(self, result_id: str) -> Path: + if not _RESULT_ID_PATTERN.fullmatch(result_id): + raise ValueError("Invalid result_id.") + result_dir = (self.root_dir / result_id).resolve() + if not str(result_dir).startswith(str(self.root_dir) + os.sep): + raise ValueError("Invalid result_id path.") + return result_dir + + def _result_dir(self, result_id: str, owner_session_id: str | None = None) -> Path: + if not _RESULT_ID_PATTERN.fullmatch(result_id): + raise ValueError("Invalid result_id.") + session_dir = self._session_dir(owner_session_id) + result_dir = (session_dir / result_id).resolve() + if not str(result_dir).startswith(str(session_dir) + os.sep): + raise ValueError("Invalid result_id path.") + return result_dir + + def _existing_result_dir( + self, result_id: str, owner_session_id: str | None = None + ) -> Path: + result_dir = self._result_dir(result_id, owner_session_id) + if (result_dir / _MANIFEST_NAME).is_file(): + return result_dir + legacy_dir = self._legacy_result_dir(result_id) + if (legacy_dir / _MANIFEST_NAME).is_file(): + return legacy_dir + raise FileNotFoundError(f"Result '{result_id}' was not found.") + + def write_csv_result( + self, + *, + tool: str, + columns: list[str], + rows: Iterable[str], + source: dict[str, Any] | None = None, + owner_session_id: str | None = None, + preview_rows: int | None = None, + page_size_rows: int | None = None, + ) -> StoredCsvResult: + self._ensure_root() + owner = _safe_owner_session_id(owner_session_id) + result_id = self._new_result_id() + result_dir = self._result_dir(result_id, owner) + result_dir.mkdir(parents=True, exist_ok=False) + + preview_limit = ( + self.settings.preview_rows if preview_rows is None else max(0, preview_rows) + ) + page_size = ( + self.settings.page_size_rows + if page_size_rows is None + else max(1, page_size_rows) + ) + + preview: list[str] = [] + shards: list[dict[str, Any]] = [] + row_count = 0 + byte_count = 0 + shard_index = -1 + shard_row_count = 0 + shard_byte_count = 0 + shard_start = 0 + shard_file = None + shard_path: Path | None = None + + def open_shard() -> None: + nonlocal shard_index, shard_row_count, shard_byte_count + nonlocal shard_start, shard_file, shard_path + shard_index += 1 + shard_row_count = 0 + shard_byte_count = 0 + shard_start = row_count + shard_path = result_dir / f"rows-{shard_index:05d}.jsonl" + shard_file = shard_path.open("w", encoding="utf-8") + + def close_shard() -> None: + nonlocal shard_file + if shard_file is None or shard_path is None: + return + shard_file.close() + shards.append( + { + "index": shard_index, + "file": shard_path.name, + "row_start": shard_start, + "row_count": shard_row_count, + "bytes": shard_byte_count, + } + ) + shard_file = None + + try: + open_shard() + for row in rows: + row_text = str(row) + encoded = json.dumps(row_text, ensure_ascii=False) + "\n" + encoded_bytes = len(encoded.encode("utf-8")) + if shard_row_count > 0 and ( + shard_row_count >= self.settings.shard_rows + or shard_byte_count + encoded_bytes > self.settings.shard_bytes + ): + close_shard() + open_shard() + + assert shard_file is not None + shard_file.write(encoded) + if len(preview) < preview_limit: + preview.append(row_text) + row_count += 1 + byte_count += encoded_bytes + shard_row_count += 1 + shard_byte_count += encoded_bytes + close_shard() + except Exception: Review Comment: **[P2] Remove the partial result directory when result generation fails** - The result directory and shard file are created before row iteration completes. - On quota errors or iterator failures, this handler closes only the current file and re-raises before writing `manifest.json`. - Listing, TTL cleanup, and quota cleanup discover entries through manifests, so the orphaned shard is invisible and remains on disk indefinitely. I reproduced a quota failure leaving `rows-00000.jsonl` while both listing and cleanup reported zero results. Please remove `result_dir` in this exception path, ideally after closing the shard file. ########## src/iotdb_mcp_server/services/metadata.py: ########## @@ -0,0 +1,398 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +import logging +import re + +from iotdb.Session import Session +from iotdb.table_session import TableSession +from iotdb.utils.SessionDataSet import SessionDataSet +from mcp.types import TextContent + +from iotdb_mcp_server.config import Config +from iotdb_mcp_server.result_store import result_store_from_export_path +from iotdb_mcp_server.runtime_policy import dynamic_env_bool +from iotdb_mcp_server.runtime_policy import dynamic_getenv +from iotdb_mcp_server.runtime_policy import strict_permission_enforcement +from iotdb_mcp_server.services.json_response import csv_result_payload_response +from iotdb_mcp_server.services.target_selection import ( + iotdb_target_response_context, + select_target_config, + table_session_pool, + tree_session_pool, +) + +_TREE_PATH_PATTERN = re.compile(r"^root(?:\.[A-Za-z_][A-Za-z0-9_]*|\.\*|\.\*\*)*$") +_TABLE_IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") + + +def _env_bool(name: str, default: bool) -> bool: + return dynamic_env_bool(name, default) + + +def _csv_set(value: str) -> set[str]: + return {item.strip() for item in value.split(",") if item.strip()} + + +def _assert_metadata_permission(config: Config) -> None: + if strict_permission_enforcement(): + if not _env_bool("IOTDB_ENABLE_METADATA_QUERY", True): + raise PermissionError( + "Metadata tools are disabled by strict MCP policy. " + "Set IOTDB_ENABLE_METADATA_QUERY=true to enable." + ) + + allowed_users = _csv_set( + dynamic_getenv("IOTDB_METADATA_ALLOWED_USERS", "*") or "*" + ) + if "*" not in allowed_users and config.user not in allowed_users: + raise PermissionError( + f"Current MCP user '{config.user}' is not allowed by IOTDB_METADATA_ALLOWED_USERS." + ) + + +def _normalize_sql(sql: str) -> str: + cleaned = sql.strip() + if not cleaned: + raise ValueError("Metadata SQL cannot be empty.") + if cleaned.endswith(";"): + cleaned = cleaned[:-1].strip() + if ";" in cleaned: + raise ValueError("Only a single SQL statement is allowed.") + return cleaned + + +def _validate_tree_path(path: str) -> str: + cleaned = path.strip() + if not cleaned: + raise ValueError("Tree path cannot be empty.") + if not _TREE_PATH_PATTERN.fullmatch(cleaned): + raise ValueError( + "Invalid tree path. Use path like root.sg, root.sg.dev, root.**, root.sg.*" + ) + return cleaned + + +def _validate_table_identifier(identifier: str) -> str: + cleaned = identifier.strip() + if not _TABLE_IDENTIFIER_PATTERN.fullmatch(cleaned): + raise ValueError( + "Invalid table identifier. Use letters, numbers, and underscore only." + ) + return cleaned + + +def _format_result( + res: SessionDataSet, + session_or_table_session: Session | TableSession, + tool_name: str, + export_path: str, + query_sql: str | None = None, + owner_session_id: str | None = None, + max_inline_rows: int | None = None, + page_size_rows: int | None = None, +) -> list[TextContent]: + columns = res.get_column_names() + + def rows(): + while res.has_next(): + row = res.next().get_fields() + yield ",".join(map(str, row)) + + try: + return csv_result_payload_response( + tool_name, + columns, + rows(), + result_store=result_store_from_export_path(export_path), + source={"query_sql": query_sql} if query_sql else None, + owner_session_id=owner_session_id, + max_inline_rows=max_inline_rows, + page_size_rows=page_size_rows, + ) + finally: + session_or_table_session.close() + + +def _ensure_prefix( + sql: str, allowed_prefixes: tuple[str, ...], action_name: str +) -> None: + upper = sql.upper() + if not upper.startswith(allowed_prefixes): + raise ValueError( + f"{action_name} only supports SQL starting with: {', '.join(allowed_prefixes)}" + ) + + +def register_metadata_tools(mcp, config: Config, logger: logging.Logger) -> None: + """Register metadata tools with per-call IoTDB target selection.""" + max_pool_size = 100 + tree_prefixes = ( + "SHOW DATABASES", + "SHOW TIMESERIES", + "SHOW DEVICES", + "SHOW CHILD PATHS", + "SHOW CHILD NODES", + "SHOW FUNCTIONS", + "COUNT TIMESERIES", + "COUNT NODES", + "COUNT DEVICES", + ) + table_prefixes = ("SHOW", "DESC", "DESCRIBE") + + def _require_target_dialect( + required_sql_dialect: str, + tool_name: str, + target_id: str | None, + target: dict[str, object] | None, + ) -> None: + select_target_config( + config, + target_id=target_id, + target=target, + required_sql_dialect=required_sql_dialect, + tool_name=tool_name, + ) + + @mcp.tool() + async def metadata_query( + query_sql: str, + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + max_inline_rows: int | None = None, + page_size_rows: int | None = None, + ) -> list[TextContent]: + """Execute metadata SQL against the selected IoTDB target.""" + selected_config = select_target_config( + config, target_id=target_id, target=target + ) + with iotdb_target_response_context(selected_config): + if selected_config.sql_dialect == "tree": + _, session_pool = tree_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + wait_timeout_in_ms=5000, + tool_name="metadata_query", + ) + session = None + try: + _assert_metadata_permission(selected_config) + sql = _normalize_sql(query_sql) + _ensure_prefix(sql, tree_prefixes, "metadata_query") + session = session_pool.get_session() + res = session.execute_query_statement(sql) + return _format_result( + res, + session, + "metadata_query", + selected_config.export_path, + sql, + owner_session_id=owner_session_id, + max_inline_rows=max_inline_rows, + page_size_rows=page_size_rows, + ) + except Exception as e: + if session: + session.close() + logger.error(f"Failed to execute metadata_query: {str(e)}") + raise + + _, session_pool = table_session_pool( + config, + target_id=selected_config.target_id, + max_pool_size=max_pool_size, + tool_name="metadata_query", + ) + table_session = None + try: + _assert_metadata_permission(selected_config) + sql = _normalize_sql(query_sql) + _ensure_prefix(sql, table_prefixes, "metadata_query") + table_session = session_pool.get_session() + res = table_session.execute_query_statement(sql) + return _format_result( + res, + table_session, + "metadata_query", + selected_config.export_path, + sql, + owner_session_id=owner_session_id, + max_inline_rows=max_inline_rows, + page_size_rows=page_size_rows, + ) + except Exception as e: + if table_session: + table_session.close() + logger.error(f"Failed to execute metadata_query: {str(e)}") + raise + + @mcp.tool() + async def list_timeseries( + path: str = "root.**", + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """List timeseries under a tree path pattern.""" + _require_target_dialect("tree", "list_timeseries", target_id, target) + query_sql = f"SHOW TIMESERIES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def list_devices( + path: str = "root.**", + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """List devices under a tree path pattern.""" + _require_target_dialect("tree", "list_devices", target_id, target) + query_sql = f"SHOW DEVICES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def list_child_paths( + path: str, + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """List child paths under a tree path.""" + _require_target_dialect("tree", "list_child_paths", target_id, target) + query_sql = f"SHOW CHILD PATHS {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def list_child_nodes( + path: str, + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """List child nodes under a tree path.""" + _require_target_dialect("tree", "list_child_nodes", target_id, target) + query_sql = f"SHOW CHILD NODES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def count_timeseries( + path: str = "root.**", + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """Count timeseries under a tree path pattern.""" + _require_target_dialect("tree", "count_timeseries", target_id, target) + query_sql = f"COUNT TIMESERIES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def count_devices( + path: str = "root.**", + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """Count devices under a tree path pattern.""" + _require_target_dialect("tree", "count_devices", target_id, target) + query_sql = f"COUNT DEVICES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def count_nodes( + path: str = "root", + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """Count nodes under a tree path.""" + _require_target_dialect("tree", "count_nodes", target_id, target) + query_sql = f"COUNT NODES {_validate_tree_path(path)}" + return await metadata_query( + query_sql, + target_id=target_id, + target=target, + owner_session_id=owner_session_id, + ) + + @mcp.tool() + async def list_tables( + target_id: str | None = None, + target: dict[str, object] | None = None, + owner_session_id: str | None = None, + ) -> list[TextContent]: + """List all tables in current table-model database.""" + _require_target_dialect("table", "list_tables", target_id, target) + return await metadata_query( Review Comment: **[P2] Avoid calling an object after it has been replaced by the FastMCP decorator** - The project declares `fastmcp>=2.8.1`. In FastMCP 2.8.1, `@mcp.tool()` returns a `FunctionTool`, not the original callable. - Therefore `list_tables()` reaches this line and fails with `TypeError: 'FunctionTool' object is not callable`; the same issue affects the other convenience tools that call `metadata_query` directly. - The current tests use a custom decorator that returns the original function, so they do not cover the minimum supported FastMCP behavior. Please move the shared implementation into an undecorated helper and have both MCP tools call that helper. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
