Feature: add mcp server for Cloudberry

[yangs16]

Fixes #1068

What does this PR do?

Add the MCP server for Cloudberry database to facilitate the integration with modern LLM clients

Type of Change

• Bug fix (non-breaking change)
• New feature (non-breaking change)
• Breaking change (fix or feature with breaking changes)
• Documentation update

Checklist

• Followed contribution guide
• Added/updated documentation
• Reviewed code for security implications
• Requested review from cloudberry committers

---

[github-actions]

Hi, @yangs16 welcome!🎊 Thanks for taking the effort to make our project better! 🙌 Keep making such awesome contributions!

[tuhaihe]

Thanks @yangs16 for your great work! For the license check, will help check it later.

[yjhjstz]

can you provide usage in mcp-server/README.md ?

[yangs16]

can you provide usage in mcp-server/README.md ?

To integrate the CloudBerry MCP Server with popular LLM clients, follow these steps (refer to lines 160–296 for detailed configuration):

Integration Methods:

1. HTTP Mode

• Start the MCP server in HTTP mode.
• Configure the LLM client with:
  • Server URL (e.g., http://localhost:port)
  • Transport method: http-streamable

2. Stdio Mode

• Set the correct startup command in the LLM client to launch the server directly.

Choose the method that best fits your workflow. For full details, refer to the configuration guide in the specified section.

[tuhaihe]

[WARNING] Files with unapproved licenses:
  mcp-server/src/cbmcp/__init__.py
  mcp-server/pyproject.toml
  mcp-server/run_tests.sh
  mcp-server/dotenv.example
  mcp-server/tests/test_cbmcp.py
  mcp-server/tests/test_database_tools.py
  mcp-server/pytest.ini

These files don't have the unapproved licenses or have been added as the excluded items in the pom.xml file.

How to fix

• For the .py files, we can add the standard ASF license header, like this:

  cloudberry/contrib/pax_storage/src/api/python3/setup.py

  Lines 1 to 18 in 793971e

  	#!/usr/bin/env python
  	# -*- coding: utf-8 -*-
  	# 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.

• For mcp-server/pyproject.toml, mcp-server/run_tests.sh, mcp-server/pytest.ini and mcp-server/dotenv.example can add the license header as follows:

# 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.

[tuhaihe]

Hi @yangs16 thanks for your great work. Just left some comments for a better reference.

[tuhaihe]

I have built and run the Cloudberry MCP server under the Cloudberry demo environment. It would be better to add the following guide to the README.md for a quick demo.

If something is wrong, please correct me. Thanks!

## Quick Start with Cloudberry Demo Cluster

This section shows how to quickly set up and test the Cloudberry MCP Server using a local Cloudberry demo cluster. This is ideal for development and testing purposes. 

Assume you already have a running [Cloudberry demo cluster](https://cloudberry.apache.org/docs/deployment/set-demo-cluster) and install & build MCP server as described above.

1. Configure local connections in `pg_hba.conf`

**Note**: This configuration is for demo purposes only. Do not use `trust` authentication in production environments.

```bash
[gpadmin@cdw]$ vi ~/cloudberry/gpAux/gpdemo/datadirs/qddir/demoDataDir-1/pg_hba.conf
```

Add the following lines to the end of the pg_hba.conf:

```
# IPv4 local connections
host    all     all     127.0.0.1/32    trust
# IPv6 local connections
host    all     all     ::1/128         trust
```

After modifying `pg_hba.conf`, reload the configuration parameters:
```bash
[gpadmin@cdw]$ gpstop -u
```

2. Create environment configuration

Create a `.env` in the project root directory:

```
# Database Configuration (Demo cluster defaults)
DB_HOST=localhost
DB_PORT=7000
DB_NAME=postgres
DB_USER=gpadmin
# No password required for demo cluster

# Server Configuration
MCP_HOST=localhost
MCP_PORT=8000
MCP_DEBUG=false
```

3. Start the MCP server

```bash
MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m cbmcp.server
```

You should see output indicating the server is running:
```
[09/17/25 14:07:50] INFO     Starting MCP server 'Apache Cloudberry MCP Server' with transport        server.py:1572
                             'streamable-http' on http://0.0.0.0:8000/mcp/
```

4. Configure your MCP client.

Add the following server configuration to your MCP client:

- Server Type: Streamable-HTTP
- URL: http://[YOUR_HOST_IP]:8000/mcp

Replace `[YOUR_HOST_IP]` with your actual host IP address.

[tuhaihe]

LGTM. Thanks @yangs16 for your great work!

[yangs16]

README.md updated with the notes for quick start.

[my-ship-it]

LGTM

[tuhaihe]

Will squash the commits into one when merging this PR.