Spring AI and Java MCP ChatBot Prototype

[fuzhaoyuan]

Add Spring AI integration with database query tools for REST API and MCP protocol

Overview

This PR integrates Spring AI into cBioPortal to enable AI-powered natural language querying of the cancer genomics database. The implementation is built on our existing backend infrastructure and supports two deployment modes.

Usage

MCP Server Mode

1. Fill out the ClickHouse database connection info in application-mcp.properties
2. Build the MCP server JAR:
   mvn clean package -Pmcp -DskipTests
3. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

  {
    "mcpServers": {
      "cbioportal-assistant": {
        "command": "java",
        "args": [
          "-jar",
          "/path/to/cbioportal/target/cbioportal-mcp-server-exec.jar",
          "--spring.profiles.active=mcp,clickhouse"
        ]
      }
    }
  }

4. Restart Claude Desktop and start chatting with natural language queries. It does take a bit longer to start because it contains the whole backend.

REST API Mode

1. Set your Anthropic API key and preferred model in application.properties:

spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY:}
spring.ai.anthropic.chat.options.model=claude-sonnet-4-20250514

2. Start cBioPortal with the AI profile:
   mvn spring-boot:run -Dspring-boot.run.profiles=clickhouse
3. Send a chat request:
   curl -X POST http://localhost:8080/api/ai/chat \ -H "Content-Type: application/json" \ -d '{"message": "How many cancer studies are in the database?"}'
4. For streaming responses:
   curl -N http://localhost:8080/api/ai/chat/stream \ -H "Content-Type: application/json" \ -d '{"message": "Show me the top 5 mutation types"}'

What's Implemented

Core AI Tools

• DatabaseQueryTools: Execute read-only SQL SELECT queries against ClickHouse with automatic validation, result limiting, and formatted output
• DatabaseSchemaTools: Retrieve table schemas and list available tables
• Security: Only SELECT queries allowed, configurable row limits (default 100, max 1000)

REST API Mode

• /api/ai/chat endpoint for conversational database queries
• Streaming responses using Server-Sent Events (SSE)
• Conversation memory with InMemoryChatMemory for multi-turn conversations
• Built on Spring AI ChatClient with Claude Sonnet 4

MCP Server Mode

• Standalone executable JAR for Model Context Protocol integration
• Works with Claude Desktop and other MCP-compatible clients
• Optimized for fast startup (web server disabled, minimal component scanning)
• Proper stdio handling: logs to stderr, MCP JSON on stdout

Advantages

• Leverages existing infrastructure (CustomDataSourceConfiguration, ClickHouse connections, database schemas)
• Zero additional infrastructure required, runs within cBioPortal backend
• Flexible deployment: same tools work via REST API or MCP protocol
• Production-ready security with read-only queries and input validation
• Optimized performance with HikariCP connection pooling and streaming responses

Technical Details

• Framework: Spring AI 1.0.3 with Anthropic Claude integration
• Database: ClickHouse JDBC 0.6.2 with HikariCP
• Logging: Logback configuration for MCP protocol compatibility
• Build: Maven profile mcp for standalone packaging

Testing Status

• MCP server tested with Claude Desktop
• REST API streaming and memory features implemented but require testing