docs: add upgrading doc for v1 release

[Yuan325]

The new markdown doc outlines changes associated with Toolbox v1.0.0 release.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new comprehensive documentation page detailing the upgrade process to MCP Toolbox for Databases v1.0.0. The release stabilizes core APIs and standardizes protocol alignments, necessitating several breaking changes and deprecations. The new document guides users through critical updates to configurations and code, including endpoint changes, tool naming conventions, configuration schema adjustments, and the introduction of a new flat configuration format. It also highlights other notable improvements like enhanced error handling and updated telemetry.

Highlights

• New Versioning Policy: The project has adopted a standard versioning policy (Major, Minor, Patch) for releases, with clear definitions for each type of update.
• Endpoint Standardization: The legacy '/api' endpoint has been removed; all implementations must now exclusively use the '/mcp' endpoint.
• Strict Tool Naming Validation: Tool names are now strictly validated against SEP986 guidelines, permitting only alphanumeric characters, hyphens, underscores, and periods.
• Configuration Schema Updates: Several configuration schema changes were introduced, including the removal of the '--tools_file' CLI flag, the requirement for singular 'kind' values (e.g., 'source' instead of 'sources'), and the renaming of 'authSources' to 'authService'.
• Flat Configuration Format: A new streamlined 'flat' configuration format has been introduced, alongside a schema restructuring where the 'kind' field now declares the core primitive (e.g., 'source' or 'tool') and the 'type' field specifies the specific primitive type.
• Deprecated CLI Flags: Several CLI flags like '--tools-file', '--tools-files', and '--tools-folder' have been deprecated in favor of '--config', '--configs', and '--config-folder' respectively.
• Enhanced Error Handling: Error handling has been improved with strict categorization between Agent Errors (for LLM self-correction) and Client/Server Errors (for hard stops).
• Documentation Relocation: The official documentation has moved to a new domain: mcp-toolbox.dev.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new UPGRADING.md guide for the v1.0.0 release of the MCP Toolbox for Databases, outlining breaking changes, deprecations, and other updates. It also updates several documentation files to reflect a change from 'Kinds of X' to 'Types of X'. The review highlights several critical inconsistencies between the new upgrade documentation and the current codebase. Specifically, the /api endpoint is documented as removed but its code remains, CLI flag migrations are described but not implemented in the code, and configuration kind values are documented as singular while the parsing logic still expects plural forms. Additionally, the ipAddress field is documented as removed but is only deprecated in the code, and a documentation link needs to be a full URL.

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2832/

[averikitsch]

Thank you!

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2832/

[github-actions]

🚀 Cloudflare Preview Ready!

🔎 View Preview: https://pr-2832.toolbox-docs-6xc.pages.dev

(Note: Subsequent pushes to this PR will automatically update the preview at this same URL)

[github-actions]

🧨 Preview deployments removed.

Cloudflare Pages environments for pr-2832 have been deleted.

[github-actions]

🧨 Preview deployments removed.