MCP4Parquet

Common workspace README for the Parquet MCP server and Python MCP client.

Overview

This workspace contains two projects that run together:

• mcp-server: Spring Boot MCP server that discovers Parquet files and exposes dynamic tools/resources.
• mcp-client: Python CLI client that connects to the MCP endpoint and queries tools using OpenAI.

Default endpoint:

• http://127.0.0.1:8092/mcp

Workspace Structure

• mcp-server/ Java Spring Boot MCP server
• mcp-client/ Python MCP client CLI

Architecture Diagram

flowchart LR
  U[User Prompt] --> C[mcp-client\nPython CLI]
  C -->|MCP HTTP| E[MCP endpoint]
  C -->|LLM API| O[OpenAI]

  subgraph S[mcp-server]
    E --> Q[ParquetQueryService]
    E --> R[ParquetToolRegistryService]
    W[ParquetDirectoryWatcher] -->|startup and file events| R
  end

  P[Parquet files] -->|create modify delete parquet| W
  Q -->|duckdb query and summarize| P
  R -->|register and unregister| E
  R -->|notify tool and resource list changes| C

Prerequisites

• Java 21+
• Maven 3.9+
• Python 3.11+
• uv
• OpenAI API key
• Optional: Node.js (for MCP Inspector)

Quick Start

1. Start the server

From workspace root:

cd mcp-server
mvn spring-boot:run

Wait until the MCP endpoint is available:

http://127.0.0.1:8092/mcp

2. Start the client

In a second terminal:

cd mcp-client
uv sync
uv run mcp-client --list-tools

Run a sample query:

uv run mcp-client --query "Show available parquet files and row counts"

3. Optional interactive mode

cd mcp-client
uv run mcp-client

Type quit to exit.

Configuration

Server configuration

Edit:

• mcp-server/src/main/resources/application.properties
• mcp-server/src/main/resources/application-local.properties

Main properties:

• server.port (default 8092)
• spring.ai.mcp.server.protocol (STREAMABLE)
• app.parquet.directory
• app.parquet.query.limit

Client configuration

Create mcp-client/.env with:

OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1
MCP_LOCALHOST_PORT=8092
MCP_SERVER_URL=http://127.0.0.1:8092/mcp
LOG_LEVEL=INFO
OPENAI_MAX_RETRIES=3
OPENAI_RETRY_BASE_SECONDS=1.5
OPENAI_TRUST_ENV=true

Windows Helper Scripts

• mcp-server/server-mcp-inspector.bat
• mcp-client/run-client.bat

Troubleshooting

• No tools listed in client:
  • Ensure server is running and reachable at /mcp.
  • Verify Parquet files exist in configured server directory.
• OpenAI errors:
  • Check OPENAI_API_KEY, network/proxy settings, and model availability.
• Connection errors:
  • Confirm both client and server are using the same host/port.

Project-Specific Documentation

• Server docs: mcp-server/README.md
• Client docs: mcp-client/README.md