datacloud-mcp-query: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides integration between Cursor IDE and Salesforce Data Cloud. It exposes tools for executing SQL queries, listing tables, and describing table structures through the MCP protocol using the FastMCP framework.

Setup and Development

Installation

# Install dependencies
pip install -r requirements.txt

Running the Server

Option 1: Using SF CLI Authentication (Recommended)

# Prerequisites: Authenticate with SF CLI
sf org login web --alias myorg

# Set required environment variable
export SF_ORG_ALIAS="myorg"

# Optional environment variables
export DEFAULT_LIST_TABLE_FILTER="%"  # default, SQL LIKE pattern

# Run the server
python server.py

Option 2: Using OAuth PKCE Authentication

# Set required environment variables
export SF_CLIENT_ID="your_client_id"
export SF_CLIENT_SECRET="your_client_secret"

# Optional environment variables
export SF_LOGIN_URL="login.salesforce.com"  # default
export SF_CALLBACK_URL="http://localhost:55556/Callback"  # default
export DEFAULT_LIST_TABLE_FILTER="%"  # default, SQL LIKE pattern

# Run the server
python server.py

Testing Individual Components

# Test the Data Cloud SQL client directly
python connect_api_dc_sql.py

# This will prompt for OAuth authentication and run a test query

Architecture

Four-Layer Design

The codebase follows a clean four-layer architecture with pluggable authentication:

1. MCP Server Layer (server.py)

   • Entry point for the MCP server using FastMCP framework
   • Defines three MCP tools: query(), list_tables(), describe_table()
   • Uses authentication abstraction via auth_provider interface
   • All SQL uses PostgreSQL dialect

2. Authentication Abstraction Layer

   • auth_interface.py: Defines AuthProvider protocol with get_token(), get_instance_url(), and is_available() methods
   • auth_factory.py: Auto-detection logic that selects appropriate authentication method
   • Implements authentication priority: SF CLI → OAuth → Error with setup instructions