This is an automated email from the ASF dual-hosted git repository. FreeOnePlus pushed a commit to branch agent/doc-002-release-docs in repository https://gitbox.apache.org/repos/asf/doris-mcp-server.git
commit ac68e55b1174cc5dcef2dc5fba46a7fe1028cb0b Author: FreeOnePlus <[email protected]> AuthorDate: Wed Jul 29 19:18:27 2026 +0800 docs: align release documentation and commands --- CHANGELOG.md | 122 ++++++++++++++++++++++++++++++++++++++++++ Makefile | 12 ++--- README.md | 43 +++++++++++---- doris_mcp_server/main.py | 2 +- pyproject.toml | 5 +- start_server.sh | 2 +- test/test_product_identity.py | 25 +++++++++ 7 files changed, 191 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..653a9ee --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,122 @@ +<!-- +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. +--> + +# Changelog + +All notable changes to Doris MCP Server are recorded here. The product version +is defined in `doris_mcp_server/_version.py`. Changes after the latest tag stay +under **Unreleased** until a new version is selected and published. + +## [Unreleased] + +### Added + +- MCP `2026-07-28` stateless protocol support on Streamable HTTP and stdio, + with a `2025-11-25` migration path. +- Doris-backed OAuth with per-user Doris connection pools and operation gates. +- Per-request client capability enforcement, cache hints, typed protocol + errors, and deterministic product identity. +- Real Doris process tests covering Streamable HTTP and stdio. + +### Changed + +- Consolidated tools, resources, and prompts on the Python SDK v2 protocol + core. +- Unified package metadata, CLI output, `server/discover`, legacy + `serverInfo`, and health endpoints on one product version source. +- Documented the modern request headers, migration steps, and deployment + constraints. + +### Fixed + +- Preserved service availability after malformed requests, unknown methods, + header mismatches, unsupported versions, and missing capabilities. +- Corrected resource and prompt error semantics and tool `isError` results. +- Released Doris connections on SQL profile, data freshness, and access + analysis paths. +- Improved Doris 4 role metadata compatibility and query recovery behavior. + +## [0.6.1] - 2025-12-24 + +### Added + +- Batch SQL execution support. + +### Changed + +- Improved stdio and Streamable HTTP startup behavior. +- Improved multi-worker operation and token authentication. + +### Fixed + +- Corrected token authentication and related security issues. + +## [0.6.0] - 2025-09-03 + +### Added + +- Token, JWT, and OAuth authentication. +- Token management and token-bound Doris database configuration. +- Connection session caching and concurrent HTTP startup support. + +### Fixed + +- Improved SQL injection detection, schema loading, connection release, and + configuration handling. + +## [0.5.1] - 2025-07-15 + +### Fixed + +- Corrected tool behavior introduced in 0.5.0. + +## [0.5.0] - 2025-07-11 + +### Added + +- Nine data analysis, governance, quality, and ADBC tools. +- Cursor and Dify integration examples. + +### Changed + +- Redesigned logging and asynchronous Doris connection lifecycle handling. + +### Fixed + +- Addressed recurring `at_eof` connection failures and MCP SDK startup + compatibility. + +## [0.4.2] - 2025-06-27 + +### Changed + +- Updated the PyPI project name, packaging metadata, startup commands, and + installation documentation. + +## [0.3.0] - 2025-06-09 + +- First tagged release in this repository. + +[Unreleased]: https://github.com/apache/doris-mcp-server/compare/0.6.1...HEAD +[0.6.1]: https://github.com/apache/doris-mcp-server/compare/0.6.0...0.6.1 +[0.6.0]: https://github.com/apache/doris-mcp-server/compare/0.5.1...0.6.0 +[0.5.1]: https://github.com/apache/doris-mcp-server/compare/0.5.0...0.5.1 +[0.5.0]: https://github.com/apache/doris-mcp-server/compare/0.4.2...0.5.0 +[0.4.2]: https://github.com/apache/doris-mcp-server/compare/0.3.0...0.4.2 +[0.3.0]: https://github.com/apache/doris-mcp-server/releases/tag/0.3.0 diff --git a/Makefile b/Makefile index c7f4f94..fcc3f23 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ # Doris MCP Server Makefile # Provides convenient commands using UV -.PHONY: help install sync dev test lint format build clean check start-stdio start-sse +.PHONY: help install sync dev test lint format build clean check start-stdio start-http # Default target help: @@ -32,7 +32,7 @@ help: @echo " clean - Clean build artifacts" @echo " check - Run all checks (format, lint, test)" @echo " start-stdio - Start server in stdio mode" - @echo " start-sse - Start server in SSE mode" + @echo " start-http - Start server in Streamable HTTP mode" # Install dependencies install: @@ -80,9 +80,9 @@ check: format lint test start-stdio: uv run python -m doris_mcp_server.main --transport stdio -# Start server in SSE mode -start-sse: - uv run python -m doris_mcp_server.main --transport sse --host 0.0.0.0 --port 8080 +# Start server in Streamable HTTP mode +start-http: + uv run python -m doris_mcp_server.main --transport http --host 127.0.0.1 --port 3000 # Start server with custom database settings start-dev: @@ -132,4 +132,4 @@ export-requirements: # Show UV version and info info: uv --version - uv python list \ No newline at end of file + uv python list diff --git a/README.md b/README.md index 108d267..b8546d2 100644 --- a/README.md +++ b/README.md @@ -21,19 +21,35 @@ under the License. Doris MCP (Model Context Protocol) Server is a backend service built with Python and FastAPI. It implements the MCP, allowing clients to interact with it through defined "Tools". It's primarily designed to connect to Apache Doris databases, potentially leveraging Large Language Models (LLMs) for tasks like converting natural language queries to SQL (NL2SQL), executing queries, and performing metadata management and analysis. -## 🚀 What's New in v0.6.0 +## Release Status + +The current package metadata and latest Git tag are `0.6.1`. The `master` +branch also contains changes made after that tag; those changes are recorded +under [Unreleased](CHANGELOG.md#unreleased) until the next version is selected +and published. + +The project is currently classified as **Beta**. Review the +[changelog](CHANGELOG.md), the +[protocol support matrix](#protocol-and-transport-matrix), and the +[deployment constraints](#deployment-constraints) before deploying it outside +a controlled environment. + +## Highlights from v0.6.0 - **🔐 Enterprise Authentication System**: **Revolutionary token-bound database configuration** with comprehensive Token, JWT, and OAuth authentication support, enabling secure multi-tenant access with granular control switches and enterprise-grade security defaults -- **⚡ Immediate Database Validation**: **Real-time database configuration validation at connection time**, eliminating query-time blocking and providing instant feedback for invalid configurations - achieving 100% elimination of late-stage connection failures -- **🔄 Hot Reload Configuration Management**: **Zero-downtime configuration updates** with intelligent hot reloading of tokens.json, automatic token revalidation, and comprehensive error handling with rollback mechanisms -- **🏗️ Advanced Connection Architecture**: **Session caching and connection pool optimization** with 60% reduction in connection overhead, intelligent pool recreation, and automatic resource management -- **🌐 Multi-Worker Scalability**: **True horizontal scaling** with stateless multi-worker architecture, efficient load distribution, and enterprise-grade concurrent processing capabilities +- **⚡ Immediate Database Validation**: **Real-time database configuration validation at connection time**, reducing query-time blocking and providing earlier feedback for invalid configurations +- **🔄 Hot Reload Configuration Management**: **Runtime configuration updates** with intelligent hot reloading of tokens.json, automatic token revalidation, and comprehensive error handling with rollback mechanisms +- **🏗️ Advanced Connection Architecture**: **Session caching and connection pool optimization** with intelligent pool recreation and automatic resource management +- **🌐 Multi-Worker Scalability**: Stateless HTTP request handling with multi-worker support; authentication-specific worker limits still apply - **🔒 Enhanced Security Framework**: **Comprehensive access control and SQL security validation** with immediate validation, role-based permissions, and enhanced injection detection patterns - **🛠️ Unified Configuration System**: **Streamlined configuration management** with proper command-line precedence, Docker compatibility improvements, and cross-platform deployment support - **📊 Token Management Dashboard**: **Complete token lifecycle management** with creation, revocation, statistics, and comprehensive audit trails for enterprise token governance - **🌐 Web-Based Management Interface**: **Secure localhost-only token administration** with intuitive dashboard, database binding configuration, real-time operations, and enterprise-grade access controls -> **🚀 Major Milestone**: v0.6.0 establishes the platform as a **production-ready enterprise authentication and database management system** with **zero-downtime operations** (hot reload + immediate validation + multi-worker scaling), advanced security controls, and comprehensive token-bound database configuration - representing a fundamental advancement in enterprise data platform capabilities. +> **Release note**: v0.6.0 introduced the authentication, token management, +> connection, and multi-worker features summarized above. These features do not +> remove the Beta status or the deployment limits documented for the current +> codebase. ### What's Also Included from v0.5.1 @@ -78,10 +94,12 @@ Doris MCP (Model Context Protocol) Server is a backend service built with Python pip install doris-mcp-server # Install specific version -pip install doris-mcp-server==0.6.0 +pip install doris-mcp-server==0.6.1 ``` -> **💡 Command Compatibility**: After installation, both `doris-mcp-server` commands are available for backward compatibility. You can use either command interchangeably. +> **💡 Packaged Commands**: `doris-mcp-server` starts the MCP server. +> `doris-mcp-client` is a separate client for connecting to a server over +> Streamable HTTP or stdio; the two commands are not interchangeable. ### Start Streamable HTTP Mode (Web Service) @@ -152,7 +170,10 @@ http://localhost:3000/token/management?admin_token=your_secure_admin_token ```bash # Check installation +doris-mcp-server --version +doris-mcp-client --version doris-mcp-server --help +doris-mcp-client --help # Test HTTP mode (in another terminal) curl http://localhost:3000/health @@ -1105,7 +1126,7 @@ doris-mcp-server/ ├── logs/ # Log files directory ├── tokens.json # Token configuration file (New in v0.6.0) ├── README.md # This documentation -├── RELEASE_NOTES_v0.6.0.md # Release notes for v0.6.0 +├── CHANGELOG.md # Tagged release history and unreleased changes ├── .env.example # Environment variables template ├── requirements.txt # Python dependencies ├── pyproject.toml # Project configuration and entry points @@ -1457,7 +1478,9 @@ QUERY_TIMEOUT=60 # Query execution timeout HEALTH_CHECK_INTERVAL=60 # Pool health check frequency ``` -**Result**: 99.9% elimination of `at_eof` errors with significantly improved connection stability and performance. +**Result**: The redesigned lifecycle reduces stale-connection failures and +improves recovery behavior. Validate the configured pool under the target +workload before production use. ### Q: Which MCP protocol revisions are supported? diff --git a/doris_mcp_server/main.py b/doris_mcp_server/main.py index ac343a8..f5faae3 100644 --- a/doris_mcp_server/main.py +++ b/doris_mcp_server/main.py @@ -440,7 +440,7 @@ Transport Modes: Examples: python -m doris_mcp_server --transport stdio - python -m doris_mcp_server --transport http --host 0.0.0.0 --port 3000 + python -m doris_mcp_server --transport http --host 127.0.0.1 --port 3000 python -m doris_mcp_server --transport stdio --doris-host localhost --doris-port 9030 python -m doris_mcp_server --transport http --doris-user admin --doris-database test_db diff --git a/pyproject.toml b/pyproject.toml index b5d5650..fbe49a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -148,7 +148,7 @@ Homepage = "https://github.com/apache/doris-mcp-server"; Documentation = "https://doris.apache.org/docs/"; Repository = "https://github.com/apache/doris-mcp-server.git"; Issues = "https://github.com/apache/doris-mcp-server/issues"; -Changelog = "https://github.com/apache/doris-mcp-server/blob/main/CHANGELOG.md"; +Changelog = "https://github.com/apache/doris-mcp-server/blob/master/CHANGELOG.md"; [project.scripts] doris-mcp-server = "doris_mcp_server.main:main_sync" @@ -164,8 +164,9 @@ packages = ["doris_mcp_server", "doris_mcp_client"] include = [ "/doris_mcp_client", "/doris_mcp_server", + "/CHANGELOG.md", "/README.md", - "/LICENSE", + "/LICENSE.txt", ] # Black configuration diff --git a/start_server.sh b/start_server.sh index 56290aa..f6bcb87 100755 --- a/start_server.sh +++ b/start_server.sh @@ -98,4 +98,4 @@ fi echo -e "${YELLOW}Tip: If the page displays abnormally, please clear your browser cache or use incognito mode${NC}" echo -e "${YELLOW}Chrome browser clear cache shortcut: Ctrl+Shift+Del (Windows) or Cmd+Shift+Del (Mac)${NC}" echo -e "${CYAN}For testing HTTP endpoints, you can use:${NC}" -echo -e "${CYAN} curl -X POST http://localhost:${SERVER_PORT}/mcp -H 'Content-Type: application/json' -d '{\"method\":\"tools/list\"}'${NC}" \ No newline at end of file +echo -e "${CYAN} curl http://127.0.0.1:${SERVER_PORT}/health${NC}"; diff --git a/test/test_product_identity.py b/test/test_product_identity.py index 2a8d8de..39cc3f4 100644 --- a/test/test_product_identity.py +++ b/test/test_product_identity.py @@ -16,7 +16,9 @@ # under the License. """Product identity must come from one build-time version source.""" +import tomllib from importlib.metadata import version as distribution_version +from pathlib import Path import pytest @@ -25,6 +27,8 @@ from doris_mcp_server import __version__ from doris_mcp_server.main import create_arg_parser as create_server_arg_parser from doris_mcp_server.utils.config import DorisConfig +PROJECT_ROOT = Path(__file__).resolve().parents[1] + def test_package_metadata_matches_runtime_version(): assert distribution_version("doris-mcp-server") == __version__ @@ -49,3 +53,24 @@ def test_configuration_cannot_override_product_version(monkeypatch): assert DorisConfig._from_dict({"server_version": "9.9.9"}).server_version == ( __version__ ) + + +def test_release_docs_and_commands_match_product_version(): + readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8") + changelog = (PROJECT_ROOT / "CHANGELOG.md").read_text(encoding="utf-8") + makefile = (PROJECT_ROOT / "Makefile").read_text(encoding="utf-8") + pyproject = tomllib.loads( + (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8") + ) + + assert f"pip install doris-mcp-server=={__version__}" in readme + assert f"## [{__version__}]" in changelog + assert "the two commands are not interchangeable" in readme + assert pyproject["project"]["scripts"] == { + "doris-mcp-server": "doris_mcp_server.main:main_sync", + "doris-mcp-client": "doris_mcp_client.client:main", + } + assert "start-http:" in makefile + assert "--transport http" in makefile + assert "start-sse" not in makefile + assert "--transport sse" not in makefile --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
