# forcedotcom/datacloud-mcp-query architecture

> Architecture diagram of the GitHub repository forcedotcom/datacloud-mcp-query, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/forcedotcom/datacloud-mcp-query
- Repository: https://github.com/forcedotcom/datacloud-mcp-query

## Overview

##### Project type and purpose
- This is a thin Python‐based MCP (Model‐Command‐Plugin) server that integrates Cursor IDE with Salesforce Data Cloud’s SQL API.
- It handles OAuth2 authentication, session management, and exposes three main tools: query, list_tables, and describe_table.

##### File structure
- Top‐level scripts:
- server.py – the MCP entry point and command router
- oauth.py – OAuth2 flow and token management
- connect_api_dc_sql.py – SQL‐over‐Data Cloud API wrapper
- Configuration and docs:
- requirements.txt – Python deps (e.g., requests, flask/fastapi, simple‐salesforce?)
- CONNECTED_APP_SETUP.md, README.md – setup and usage
- No separate “frontend” or “backend” directories—everything runs in one Python process.

##### README for additional insights
- The README describes environment variables (SF_CLIENT_ID, SF_CLIENT_SECRET, etc.)
- It details the three MCP tools (query, list_tables, describe_table) and OAuth interaction
- It points to Connected App setup in Salesforce Data Cloud

##### Elements
- Between Cursor and MCP Server (command invocation + response)
- From OAuth Module to OAuth Authorization Server (authorization code flow)
- From SQL Connector to Salesforce Data Cloud (HTTPS requests/responses)
- Green rectangles for internal modules (server, oauth, connector)

##### Detailed capture of essential elements
- Environment variables at the MCP Server boundary
- Token expiry and automatic refresh in the OAuth module

- Highlights the single‐process architecture
- Separates command routing, authentication, and data access
- Shows data flow from Cursor → MCP Server → Salesforce → back to Cursor
- Captures configuration and session management details

## Diagram (Mermaid)

```mermaid
graph TB
    CursorIDE["Cursor IDE"]:::external

    subgraph "MCP Python Server"
        CR["Command Router\n(server.py)"]:::internal
        OA["OAuth Module\n(oauth.py)"]:::internal
        SQLC["SQL Connector\n(connect_api_dc_sql.py)"]:::internal
        TS["Token Store"]:::storage
    end

    subgraph "Documentation & Config"
        REQ["requirements.txt"]:::doc
        SETUP["CONNECTED_APP_SETUP.md"]:::doc
        README["README.md"]:::doc
        Config["Env Vars\n(SF_CLIENT_ID, SF_CLIENT_SECRET, SF_LOGIN_URL, SF_CALLBACK_URL)"]:::config
    end

    Browser["User Browser"]:::external
    SFDC["Salesforce Data Cloud"]:::cloud

    CursorIDE -->|"invoke Command"| CR
    CR -->|"check token"| OA
    OA -->|"redirect auth"| Browser
    Browser -->|"callback with code"| OA
    OA -->|"store token"| TS
    OA -->|"provide token"| CR
    CR -->|"execute SQL / list / describe"| SQLC
    SQLC -->|"HTTPS request"| SFDC
    SFDC -->|"JSON response"| SQLC
    SQLC -->|"results / metadata"| CR
    CR -->|"return results"| CursorIDE

    Config -.-> CR

    click CR "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/server.py"
    click OA "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/oauth.py"
    click SQLC "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/connect_api_dc_sql.py"
    click REQ "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/requirements.txt"
    click SETUP "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/CONNECTED_APP_SETUP.md"
    click README "https://github.com/forcedotcom/datacloud-mcp-query/blob/main/README.md"

    classDef internal fill:#b7e4c7,stroke:#1b4332,color:#1b4332
    classDef external fill:#e9ecef,stroke:#495057,color:#495057
    classDef storage fill:#bee5eb,stroke:#0a9396,color:#0a9396
    classDef cloud fill:#cfe2f3,stroke:#1d3557,color:#1d3557
    classDef doc fill:#fff3bf,stroke:#665c00,color:#665c00
    classDef config stroke-dasharray: 5 5,stroke:#6c757d
```
