FreeOnePlus opened a new issue, #189: URL: https://github.com/apache/doris-mcp-server/issues/189
## Apache Doris MCP Server 1.0.0 **Release date:** 2026-08-01 **Release manager:** @FreeOnePlus (Yijia Su) **Release tag:** [`1.0.0`](https://github.com/apache/doris-mcp-server/releases/tag/1.0.0) **Protocol baseline:** MCP `2026-07-28` **Minimum Doris version:** `3.0.0` ## Executive summary Apache Doris MCP Server 1.0.0 establishes the project's first versioned public contract for exposing Apache Doris capabilities to MCP Hosts and AI agents. The release replaces the pre-1.0 collection of unrelated top-level tools with one capability-aware, read-only architecture built around: - eight stable top-level Doris domains; - forty-seven exact child capabilities; - progressive discovery with bounded manifests; - runtime Doris version, feature, provider, and permission evidence; - deterministic schemas, authorization identifiers, and error envelopes; - MCP `2026-07-28` over Streamable HTTP and stdio; - fail-closed query, transport, authentication, and capability boundaries. The MCP protocol contract is generally available. The Python package retains its Beta deployment classifier because Doris-backed OAuth state is currently process-local and several distributed deployment shapes remain deliberately constrained. ## Why 1.0 changes the architecture Earlier releases exposed many independent tools directly to the Host. That model becomes increasingly expensive and unstable as Doris adds catalog, query, observability, ingestion, search, governance, lakehouse, and semantic capabilities. A large flat `tools/list` consumes model context, makes tool selection harder, and cannot accurately represent differences between Doris versions, deployment modes, providers, or user permissions. Version 1.0 therefore defines a stable two-level contract: 1. The Host registers a small, deterministic set of domain tools. 2. Calling a domain with an empty object progressively discloses its currently authorized child capabilities, exact schemas, and runtime availability. 3. The Host calls the same domain with the selected `child_tool`, exact `arguments`, and optional `manifest_version`. 4. The Server revalidates authorization, availability, manifest generation, arguments, and output before returning a bounded result. Tool selection remains deterministic: the Server does not use probabilistic intent classification to hide or guess tools. The model sees the complete domain map at the top level and receives the complete authorized child map for the chosen domain on discovery. ## Product and component architecture ```mermaid flowchart LR H["MCP Host / AI Agent"] T["stdio or Streamable HTTP"] S["Transport security and authentication"] P["MCP 2026-07-28 protocol layer"] D["Domain manifest and dispatcher"] C["Route-aware capability detector"] R["Read-only domain runtimes"] A["Authorization and query guard"] M["Connection and route manager"] DB["Apache Doris FE / BE / metadata APIs"] O["Optional providers: Ossie, lineage, ADBC"] H --> T --> S --> P --> D D --> C D --> A --> R --> M --> DB C --> M O --> C O --> R ``` The implementation keeps the following responsibilities separate: - **Host:** registers the public tools, chooses a domain, consumes the child manifest, submits exact arguments, and rediscoveries after a stale-manifest response. - **Transport and protocol:** normalize stdio and Streamable HTTP onto the same low-level MCP SDK v2 server, enforce MCP schemas, paginate list operations, and sanitize protocol errors. - **Security:** establish the request identity, validate tokens or OAuth credentials, map exact scopes, enforce Host/Origin/proxy rules, and preserve Doris as the final data authorization boundary. - **Domain control plane:** expose the stable top-level catalog, filter child discovery and execution by exact authorization, resolve availability, and dispatch one exact child. - **Capability plane:** probe the connected Doris route, normalize its three-part version, inspect runtime features/providers, and create a bounded capability snapshot. - **Execution plane:** validate identifiers and read-only SQL, execute bounded metadata/query/HTTP calls, normalize results, mask configured data, and classify failures. - **Apache Doris:** remains the system of record for metadata, query execution, audit evidence, workload state, storage state, and row/column/data access permissions. ## End-to-end request and data flow ### 1. Server initialization 1. Configuration is parsed and validated before the Server accepts traffic. 2. The security manager, connection manager, resources, tools, and prompts are initialized. 3. The same MCP server contract is bound to stdio or Streamable HTTP. 4. The tool exposure mode is fixed for the process lifetime. Changing it requires a Server restart and Host reconnect. ### 2. Top-level discovery 1. The Host sends `tools/list`. 2. The protocol layer authorizes the list operation and validates the complete tool catalog against bounded JSON Schema rules. 3. In the default `hierarchical` mode, the Server returns eight stable domain tools. Their short descriptions explain the domain coverage without repeating all child schemas. 4. List responses use signed, expiring cursors when pagination is required. ### 3. Domain discovery 1. The Host calls a domain with `{}`. 2. Exact discovery scopes filter the domain's children. An unauthorized child is not disclosed. 3. The capability detector resolves the current request route and probes only the necessary bounded evidence. 4. Doris version detection parses real values such as `Doris version doris-3.0.3-rc03-43f06a5e26 (Cloud Mode)` and reduces the capability key to `3.0.3`; RC/GA labels, commit hashes, and deployment hints remain diagnostic evidence only. 5. Version ranges, SQL/HTTP probes, configured providers, deployment mode, and permission evidence are combined into an authoritative `Availability` object for each child. 6. The manifest returns the exact child name, description, input/output schemas, availability, reason code, and a deterministic `manifest_version`. 7. Discoverable but unavailable children remain visible with `callable=false`, so the Host can explain why an operation cannot currently run. ### 4. Child execution 1. The Host calls the same domain with `child_tool`, `arguments`, and the discovered `manifest_version`. 2. The dispatcher rechecks exact discovery and execution authorization. 3. A changed capability/provider/route generation produces `CHILD_MANIFEST_STALE` and directs the Host to rediscover. 4. A non-callable child produces `CHILD_CAPABILITY_UNAVAILABLE` with a stable reason code; the Server never attempts a speculative backend call. 5. Child arguments are validated against the disclosed schema. 6. The selected read-only runtime validates identifiers, SQL shape, parameter shape, row/byte/time limits, and provider requirements. 7. Doris executes with the request-specific route and credentials. Doris RBAC remains the final authorization decision for visible catalogs, objects, rows, columns, and functions. 8. Results are normalized into a deterministic envelope with request ID, duration, source, truncation state, warnings, and structured data. 9. Output Schema is validated before the response crosses the MCP boundary. ## Public tool contract ### Exposure modes - **`hierarchical` (default):** exposes the eight stable domain tools below. Empty-object discovery returns the authorized child manifest. - **`flat` (compatibility fallback):** exposes the same forty-seven children as collision-free names such as `doris_query_execute_query`. Flat mode is for Hosts that cannot perform progressive disclosure; it does not restore pre-1.0 names. Both modes use the same catalog, availability rules, authorization policies, schemas, dispatcher, runtimes, and result envelopes. ### `doris_catalog` — 5 children - `list_catalogs` — list internal and external catalogs. - `list_databases` — list databases in an exact catalog. - `list_tables` — list tables and views with bounded filtering/pagination. - `get_table_context` — return composable `basic`, `schema`, `comments`, and `indexes` sections; the schema section is mandatory and optional sections report partial availability explicitly. - `get_table_size` — inspect bounded partition/table size evidence. ### `doris_query` — 7 children - `execute_query` — run one bounded read-only SQL statement. - `explain_query` — inspect a read-only query plan. - `get_query_profile` — retrieve bounded query profile evidence. - `diagnose_query_performance` — return deterministic performance findings. - `list_slow_queries` — inspect bounded audit-backed slow-query evidence. - `get_adbc_connection_info` — inspect ADBC/Flight SQL readiness without exposing secrets. - `execute_adbc_query` — run a bounded read-only query through the optional ADBC provider. ### `doris_cluster` — 11 children - `get_cluster_overview` - `list_cluster_nodes` - `list_active_tasks` - `get_monitoring_metrics` - `get_memory_stats` - `get_cache_status` - `get_compaction_status` - `get_workload_group_status` - `get_compute_group_status` - `analyze_resource_growth` - `get_runtime_capabilities` This domain unifies version-aware FE/BE metadata, system tables, HTTP evidence, task views, workload groups, compute groups, cache, compaction, and the current capability snapshot. ### `doris_pipeline` — 5 children - `get_ingestion_status` — inspect batch, stream, routine, and insert jobs. - `diagnose_ingestion` — produce deterministic ingestion diagnostics. - `get_materialized_view_status` — inspect MV jobs, tasks, and compute context. - `monitor_data_freshness` — return bounded freshness evidence. - `analyze_data_dependencies` — infer bounded runtime dependencies from audit evidence. ### `doris_search` — 4 children - `search_data` — execute bounded inverted, vector, or hybrid search when the connected Doris route supports it. - `preview_text_analysis` — preview tokenizer/analyzer behavior. - `inspect_search_indexes` — inspect inverted and ANN index metadata. - `diagnose_search_query` — explain and diagnose a search query. ### `doris_governance` — 8 children - `analyze_columns` - `analyze_table_storage` - `get_lineage_capability_status` - `trace_column_lineage` - `analyze_data_access_patterns` - `get_recent_audit_logs` - `list_udfs` - `get_auth_mapping_status` Doris 4.0.6 and later may use a queryable native-lineage companion provider. Before 4.0.6, bounded audit SQL inference is the primary lineage path. On 4.0.6 and later it becomes an explicit degraded fallback when the native provider is absent or unavailable. Native delivery is asynchronous and best effort, and every response reports the active evidence path. ### `doris_lakehouse` — 3 children - `inspect_external_catalog` - `inspect_lakehouse_table` - `inspect_variant_column` The domain covers external catalog metadata, lakehouse lifecycle evidence, and version-aware Variant inspection without pretending that every feature exists on every Doris patch. ### `doris_semantic` — 4 children - `list_semantic_models` - `get_semantic_model_summary` - `get_semantic_context` - `get_semantic_mapping_status` This optional, default-off domain is a read-only Apache Ossie consumer. It requires explicit provider configuration and exact `model_ref` selection. The Server does not infer a semantic model from the prompt and does not compile or execute semantic expressions. Doris MCP Server remains an MCP execution and grounding layer, not a semantic modeling repository. ## Capability detection and availability Capability discovery combines independent evidence rather than relying on a version string alone: - normalized Doris `major.minor.patch` version and cluster version vector; - deployment mode and mixed-version state; - route-specific SQL metadata probes; - bounded FE/BE HTTP probes; - optional provider readiness and provider generation; - exact request identity and Doris privilege visibility; - configured feature flags and safety policy. Snapshots are private to the resolved Doris route and are cached for a bounded TTL. A bounded stale snapshot may be used only under the configured stale policy; otherwise detection fails closed. Route or provider changes alter the manifest generation so a Host cannot unknowingly execute against an obsolete capability description. Availability is structured and authoritative. Human-readable descriptions may include a dynamic status prefix, but callers must rely on fields such as `status`, `callable`, `reason_code`, version evidence, and provider evidence. ## MCP protocol and transport contract - MCP `2026-07-28` is the modern protocol baseline. - Streamable HTTP and stdio share one low-level SDK v2 Server contract. - Streamable HTTP uses stateless request handling. - The isolated `2025-11-25` HTTP migration adapter is default-off at `/mcp/legacy` and never restores pre-1.0 tool names. - Resources, tools, and prompts list operations are bounded and paginated. - Pagination and explicit state handles are signed, scoped, and expiring. - Tool input and structured output schemas are compiled and validated. - Trace context is propagated only after sanitization and remains bounded. - Subscription/change-event capabilities are not advertised without a real change-event source. - Product name and version identity are deterministic across transports. ## Security and permission model ### Authentication modes The Server supports separately configured boundaries for: - static bearer tokens; - JWT validation; - external OAuth 2.0/OIDC access-token validation; - Doris-backed OAuth for request-specific Doris user credentials; - unauthenticated local development only when explicitly configured. External OAuth and Doris-backed OAuth cannot be enabled together. Doris-backed OAuth requires HTTP transport and a single worker in 1.0 because authorization codes, access tokens, and user connection state are process-local. ### Layered authorization 1. **Transport access:** bind-address, Host, Origin, proxy, and TLS policy. 2. **MCP operation scope:** exact authorization for list/read/call operations. 3. **Domain discovery scope:** exact domain and child discovery grants. 4. **Child execution scope:** exact `child:call:<domain>:<child>` grants. 5. **Provider allowlist:** Doris OAuth and custom providers expose only reviewed capabilities. 6. **Doris RBAC:** the selected Doris identity remains the final data plane authority. Discovery permission never implies execution permission. Unauthorized child names are returned as not found rather than leaking the presence of hidden capabilities. ### Query and data safety - The built-in 1.0 catalog is read-only. - `doris_admin` is reserved but is not registered. - SQL parsing accepts one read-only query shape and rejects write/management operations, stacked statements, unsafe identifiers, and invalid parameters. - Query timeout, row count, result bytes, input lengths, collection sizes, and diagnostic depth are bounded. - Configured sensitive data masking is applied before results leave the Server. - Secrets, credentials, tokens, connection strings, and backend errors are redacted from logs and MCP error payloads. - Custom tool providers are explicit, installed, and allowlisted; they are not silently merged into the built-in 8/47 contract. - ADBC execution fails closed on token-bound routes because the current Flight client is process-global. ## Reliability and operational behavior - **Fail-closed initialization:** invalid authentication, proxy, secret, or provider configuration prevents unsafe startup. - **Route-aware connection management:** global, static-token, and Doris OAuth user routes have explicit priority and isolated pool lifecycle. - **Multi-FE support:** configured FE candidates can fail over while preserving request routing evidence. - **Readiness separation:** liveness reports process health; readiness reflects whether the Server can safely serve Doris-backed operations. - **Deterministic errors:** domain errors distinguish invalid arguments, unavailable capabilities, stale manifests, timeouts, execution failures, and authorization failures, including explicit retryability. - **Bounded fallback:** native features may use only documented fallback paths; the response reports degraded operation instead of presenting fallback evidence as native. - **Result integrity:** successful child outputs must satisfy the declared JSON Schema before they cross the protocol boundary. - **Auditability:** calls carry request IDs, durations, sources, truncation state, warnings, and sanitized trace context. - **Stable registration:** changing from a catalog question to a cluster question requires calling another already registered domain, not dynamically re-registering MCP tools. ## Doris compatibility and certification The project minimum is Doris `3.0.0`. The 1.0 target patch set is: - `3.0.3` - `3.1.4` - `4.0.5` - `4.0.6` - `4.0.7` - `4.1.0` - `4.1.1` - `4.1.2` - `4.1.3` Only normalized three-part versions participate in capability ranges and certification. RC/GA suffixes do not create separate capability buckets. Doris `4.0.5` is the first evidence-backed certified target. Other target patches remain `target_uncertified` until they pass the same real-cluster gate. An uncertified target is not automatically unusable: runtime capability discovery remains authoritative for the connected cluster. ## Breaking changes from pre-1.0 releases - Pre-1.0 direct tool names are removed without an alias window. - Hierarchical exposure is the default. - Flat mode uses formal names such as `doris_query_execute_query`. - Exact domain/child scope identifiers replace legacy wildcard guesses. - `get_table_context` consolidates five pre-1.0 table metadata calls into four explicit sections. - ADBC is part of the query domain rather than a separate top-level domain. - Semantic calls require an explicit `model_ref`. - Hosts must rediscover after `CHILD_MANIFEST_STALE`. - The legacy HTTP adapter is isolated, default-off, and does not restore the old tool surface. See the [1.0 migration guide](https://github.com/apache/doris-mcp-server/blob/master/docs/migration-1.0.0.md) and the generated [8/47 tool registry](https://github.com/apache/doris-mcp-server/blob/master/docs/tool-registry.md). ## Verification and release gates The 1.0 contract is protected by: - warnings-as-errors unit, security, integration, and deployment tests; - domain-specific coverage floors; - Ruff, Mypy, Bandit, and lock-file validation; - source distribution, wheel build, and clean-wheel installation; - official MCP `2026-07-28` stateless conformance; - stdio and Streamable HTTP contract tests; - hierarchical and flat exposure tests; - cross-process 8-domain/47-child stability tests; - real Apache Doris read-only regression tests; - package and generated-catalog drift checks. The release tag was prepared in [#187](https://github.com/apache/doris-mcp-server/pull/187). Post-tag [#188](https://github.com/apache/doris-mcp-server/pull/188) migrated the real Doris regression suite to the 1.0 hierarchical/flat contract without changing the public 8/47 surface. ## Documentation system work The root README files will become concise, bilingual entry points. Detailed material will be maintained under `docs/` in paired English and Simplified Chinese documents covering: - getting started and Host connection; - architecture and end-to-end data flow; - tool domains and progressive disclosure; - MCP protocol behavior; - authentication, authorization, and query safety; - deployment, reliability, and troubleshooting; - configuration reference and integrations; - migration, release notes, and contributor workflows. This issue remains the detailed 1.0 release record. The documentation pull request will be linked here when it is available. ## Known limitations - `doris_admin` is reserved and unavailable in 1.0. - Doris-backed OAuth is process-local and supports one worker only. - ADBC is unavailable on token-bound request routes. - Ossie integration is optional, read-only grounding; it neither authors models nor executes semantic expressions. - Native lineage requires a queryable companion provider and is asynchronous, best effort. - Audit-derived lineage is bounded inference, not proof of complete lineage. - Runtime support and release certification are distinct; only `4.0.5` is certified at this release boundary. ## Contributors Thanks to everyone who contributed code, review, testing, issue reports, and release validation for the 1.0 line, including: - @FreeOnePlus - @maktala - @mortalBibo - @catpineapple - @heroyin - @dependabot ## Related implementation pull requests The 1.0 architecture was delivered incrementally in [#141](https://github.com/apache/doris-mcp-server/pull/141) through [#188](https://github.com/apache/doris-mcp-server/pull/188), including bounded MCP lists and schemas, explicit state handles, OAuth scope hardening, trace propagation, route-aware connections, version/capability detection, the domain catalog and dispatcher, all eight domain runtimes, Host budgets, patch certification, release preparation, and real Doris validation. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
