Skip to content

Refactor IoTDB MCP Server and migrate agent enhancements - #18

Open
Alchuang22-dev wants to merge 1 commit into
apache:mainfrom
Alchuang22-dev:main
Open

Refactor IoTDB MCP Server and migrate agent enhancements#18
Alchuang22-dev wants to merge 1 commit into
apache:mainfrom
Alchuang22-dev:main

Conversation

@Alchuang22-dev

Copy link
Copy Markdown

Description

This PR migrates the IoTDB MCP Server enhancements previously maintained under
lib/iotdb_mcp_server in the TimeSeek repository into the standalone
iotdb-mcp-server repository.

The migration follows the Apache project plan to separate reusable library
components from TimeSeek-specific plugin and orchestration code. It also
restructures the server into domain-oriented modules to improve maintainability,
security, and extensibility.

Content

Features

  • Split the monolithic MCP server into modules for:
    • Database management
    • Query and metadata operations
    • Table and time-series management
    • TTL management
    • UDF execution
    • AINode discovery and model inference
    • SQL execution and write operations
  • Add support for registering and dynamically selecting multiple IoTDB targets.
  • Add reusable Tree and Table session pools with target-aware lifecycle management.
  • Add an iotdb-target-cli command for operating on verified IoTDB targets.
  • Add per-target last-known-good credential handling.
  • Add runtime policy configuration and SQL permission inspection.
  • Add configurable permission controls for DDL, write, model, UDF, and SQL operations.
  • Add batch SQL execution with:
    • Parameterized SQL templates
    • Concurrency limits
    • Per-item and batch result quotas
    • Configurable error handling
  • Add file-backed result storage with pagination, cleanup, listing, and deletion tools.
  • Add AINode availability probing and model inference validation.
  • Add UDF-based data-quality validation support.
  • Add Tree SQL shape validation and runtime diagnostics.
  • Add tests for target routing, credential caching, result storage, batch SQL execution,
    target lifecycle management, and the target CLI.
  • Update the English and Chinese documentation, packaging configuration, and deployment
    configuration.

Fixes

  • Preserve credentials independently for each verified IoTDB target.
  • Improve connection-pool reuse and cleanup when targets are changed or reloaded.
  • Correct target selection and routing for read-only and database-specific operations.
  • Improve MCP startup and shutdown behavior.
  • Preserve explicitly configured empty passwords without treating them as missing values.
  • Keep CSV and Excel export filename validation and path-traversal protection.
  • Add result-size controls to prevent large query responses from exhausting the MCP
    context.
  • Improve error responses by returning structured diagnostic and target information.

Migration Notes

  • The minimum supported Python version is now Python 3.11.
  • The server implementation is now organized under
    src/iotdb_mcp_server/services. Integrations importing implementation details from the
    previous monolithic server.py should migrate to the corresponding service module.
  • The iotdb-mcp-server entry point remains available.
  • A new iotdb-target-cli entry point is provided for target lifecycle operations.
  • Existing single-target environment variables remain supported as the fallback
    configuration.
  • Multi-target deployments can configure a target registry and select a target for each
    request.
  • Runtime permissions are more restrictive and configurable. Deployments using DDL,
    write, model, UDF, or unrestricted SQL operations should review the corresponding
    policy environment variables.
  • Query results may be stored in the file-backed result store when they exceed inline
    response limits. Clients should use the result pagination tools to retrieve the
    remaining rows.
  • CSV and Excel export behavior remains supported, including filename and path security
    validation.
  • The original TimeSeek source directory has not been removed in this PR. It should be
    removed after TimeSeek plugins and packaging have been updated to depend on the
    standalone repository.

Validation performed:

51 tests passed
14 subtests passed
git diff --check passed
tested in Codex/Claude Code/OpenCode(and with TimeSeek Plugin)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant