WIP gRPC client and DC token exchange

.gitignore

@@ -143,3 +143,9 @@ poetry.toml
 
 # LSP config files
 pyrightconfig.json
+
+# Generated Protocol Buffer files
+generated/
+*_pb2.py
+*_pb2.pyi
+*_pb2_grpc.py

Makefile

@@ -0,0 +1,113 @@
+# Makefile for DataCloud MCP Query Project
+# This Makefile provides convenient commands for building and managing the project
+
+.PHONY: help install protos clean clean-protos test run dev-install all
+
+# Default target - show help
+help:
+	@echo "DataCloud MCP Query - Makefile Commands"
+	@echo "========================================"
+	@echo ""
+	@echo "Available targets:"
+	@echo "  make install       - Install Python dependencies"
+	@echo "  make dev-install   - Install dependencies and compile protos"
+	@echo "  make protos        - Compile Protocol Buffer files"
+	@echo "  make clean-protos  - Remove generated Protocol Buffer files"
+	@echo "  make clean         - Clean all generated files and caches"
+	@echo "  make test          - Run tests (if available)"
+	@echo "  make run           - Run the MCP server"
+	@echo "  make all           - Install dependencies and compile protos"
+	@echo ""
+
+# Install Python dependencies
+install:
+	@echo "Installing Python dependencies..."
+	pip install -r requirements.txt
+
+# Install dependencies and compile protos (for development)
+dev-install: install protos
+	@echo "Development setup complete!"
+
+# Compile Protocol Buffer files
+protos:
+	@echo "Compiling Protocol Buffer files..."
+	@python compile_protos.py
+
+# Clean generated Protocol Buffer files
+clean-protos:
+	@echo "Removing generated Protocol Buffer files..."
+	rm -rf generated/
+	@echo "Generated proto files removed."
+
+# Clean all generated files and caches
+clean: clean-protos
+	@echo "Cleaning Python cache files..."
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	find . -type f -name "*.pyo" -delete 2>/dev/null || true
+	find . -type f -name "*.pyd" -delete 2>/dev/null || true
+	find . -type f -name ".coverage" -delete 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	@echo "Cleanup complete!"
+
+# Run tests (placeholder - update when tests are available)
+test:
+	@echo "Running tests..."
+	@if [ -d "tests" ]; then \
+		python -m pytest tests/; \
+	else \
+		echo "No tests directory found. Add tests to enable testing."; \
+	fi
+
+# Run the MCP server
+run:
+	@echo "Starting MCP server..."
+	@if [ -f "server.py" ]; then \
+		python server.py; \
+	else \
+		echo "server.py not found!"; \
+		exit 1; \
+	fi
+
+# Build everything
+all: dev-install
+	@echo "Project setup complete!"
+
+# Check if dependencies are installed
+check-deps:
+	@echo "Checking dependencies..."
+	@python -c "import grpc_tools.protoc" 2>/dev/null || \
+		(echo "Error: grpcio-tools not installed. Run 'make install' first." && exit 1)
+	@python -c "import google.protobuf" 2>/dev/null || \
+		(echo "Error: protobuf not installed. Run 'make install' first." && exit 1)
+	@echo "All dependencies are installed."
+
+# Compile protos with dependency check
+safe-protos: check-deps protos
+
+# Show current proto files
+list-protos:
+	@echo "Proto files in the project:"
+	@find protos -name "*.proto" -type f | sort
+
+# Validate proto files (requires protoc)
+validate-protos:
+	@echo "Validating proto files..."
+	@for proto in $$(find protos -name "*.proto" -type f); do \
+		echo "  Checking $$proto..."; \
+		python -m grpc_tools.protoc --proto_path=protos $$proto --descriptor_set_out=/dev/null || exit 1; \
+	done
+	@echo "All proto files are valid!"
+
+# Watch for changes and recompile (requires watchdog)
+watch:
+	@echo "Watching for proto file changes..."
+	@echo "Note: This requires 'pip install watchdog'"
+	@which watchmedo >/dev/null 2>&1 || (echo "Error: watchdog not installed. Run 'pip install watchdog'" && exit 1)
+	watchmedo shell-command \
+		--patterns="*.proto" \
+		--recursive \
+		--command='make protos' \
+		protos

PROTO_BUILD.md

@@ -0,0 +1,195 @@
+# Protocol Buffer Build System
+
+This project includes Protocol Buffer (protobuf) definitions for the DataCloud HyperService API. This document explains how to compile and use these proto files in Python.
+
+## Prerequisites
+
+The required dependencies are listed in `requirements.txt`:
+- `protobuf>=4.25.0` - Protocol Buffer runtime
+- `grpcio-tools>=1.60.0` - Protocol Buffer compiler for Python
+- `grpcio>=1.60.0` - gRPC runtime
+
+Install all dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Building Proto Files
+
+### Using the Makefile (Recommended)
+
+The easiest way to compile proto files is using the provided Makefile:
+
+```bash
+# Compile proto files
+make protos
+
+# Clean and recompile
+make clean-protos && make protos
+
+# Install dependencies and compile protos
+make dev-install
+
+# List all proto files
+make list-protos
+
+# Validate proto files
+make validate-protos
+```
+
+### Using the Python Script
+
+You can also use the Python script directly:
+
+```bash
+python compile_protos.py
+```
+
+This script will:
+1. Find all `.proto` files in the `protos/` directory
+2. Compile them to Python code using `grpc_tools.protoc`
+3. Generate type stubs (`.pyi` files) for better IDE support
+4. Fix import paths to work with the project structure
+5. Create `__init__.py` files for proper Python packaging
+
+## Generated Files
+
+After compilation, the generated files will be in the `generated/` directory:
+
+```
+generated/
+├── __init__.py
+└── salesforce/
+    ├── __init__.py
+    └── hyperdb/
+        ├── __init__.py
+        ├── grpc/
+        │   ├── __init__.py
+        │   └── v1/
+        │       ├── __init__.py
+        │       ├── error_details_pb2.py
+        │       ├── error_details_pb2.pyi
+        │       ├── error_details_pb2_grpc.py
+        │       ├── hyper_service_pb2.py
+        │       ├── hyper_service_pb2.pyi
+        │       └── hyper_service_pb2_grpc.py
+        └── v1/
+            ├── __init__.py
+            ├── query_status_pb2.py
+            ├── query_status_pb2.pyi
+            ├── sql_type_pb2.py
+            └── sql_type_pb2.pyi
+```
+
+## Using the Generated Code
+
+### Import the modules
+
+You can import the generated modules in your Python code:
+
+```python
+# Import from the top-level generated package
+from generated import (
+    error_details_pb2,
+    hyper_service_pb2,
+    hyper_service_pb2_grpc,
+    query_status_pb2,
+    sql_type_pb2
+)
+
+# Or import from the specific package paths
+from generated.salesforce.hyperdb.grpc.v1 import hyper_service_pb2
+from generated.salesforce.hyperdb.grpc.v1 import hyper_service_pb2_grpc
+```
+
+### Example Usage
+
+```python
+# Create a QueryParam message
+query_param = hyper_service_pb2.QueryParam(
+    query="SELECT * FROM Account LIMIT 10",
+    output_format=hyper_service_pb2.OutputFormat.JSON_ARRAY,
+    transfer_mode=hyper_service_pb2.QueryParam.TransferMode.SYNC
+)
+
+# Create an ErrorInfo message
+error_info = error_details_pb2.ErrorInfo(
+    primary_message="Query failed",
+    sqlstate="42000",
+    customer_detail="Invalid SQL syntax"
+)
+
+# Use with gRPC client (example)
+import grpc
+channel = grpc.insecure_channel('localhost:50051')
+stub = hyper_service_pb2_grpc.HyperServiceStub(channel)
+# response = stub.ExecuteQuery(query_param)
+```
+
+## Proto File Structure
+
+The project includes the following proto files:
+
+- **`hyper_service.proto`**: Main service definition for HyperService with RPC methods:
+  - `ExecuteQuery`: Submit and execute a query
+  - `GetQueryInfo`: Get information about a query
+  - `GetQueryResult`: Retrieve query results
+  - `CancelQuery`: Cancel a running query
+
+- **`error_details.proto`**: Error detail messages for rich error handling
+  - `ErrorInfo`: Detailed error information
+  - `TextPosition`: Position information for errors in SQL text
+
+- **`query_status.proto`**: Query status related messages
+
+- **`sql_type.proto`**: SQL type definitions
+
+## Development Tips
+
+1. **Auto-rebuild on changes**: If you have `watchdog` installed, you can watch for proto file changes:
+   ```bash
+   pip install watchdog
+   make watch
+   ```
+
+2. **Type hints**: The generated `.pyi` files provide type hints for better IDE support
+
+3. **Import fixes**: The build script automatically fixes import paths to use `generated.salesforce.*` instead of absolute `salesforce.*` imports
+
+## Troubleshooting
+
+### Import Errors
+
+If you encounter import errors like "No module named 'salesforce'", ensure:
+1. The proto files have been compiled: `make protos`
+2. The `generated` directory exists and contains the compiled files
+3. You're importing from `generated.*` not directly from `salesforce.*`
+
+### Compilation Errors
+
+If compilation fails:
+1. Check that all dependencies are installed: `pip install -r requirements.txt`
+2. Ensure the proto files are valid: `make validate-protos`
+3. Check the error output for specific issues with proto syntax
+
+### Clean Build
+
+If you're having issues, try a clean rebuild:
+```bash
+make clean
+make dev-install
+```
+
+## Git Ignore
+
+The generated files are excluded from version control via `.gitignore`:
+- `generated/` - The entire generated directory
+- `*_pb2.py` - Generated Python protobuf files
+- `*_pb2.pyi` - Generated type stub files
+- `*_pb2_grpc.py` - Generated gRPC service files
+
+## Further Information
+
+- [Protocol Buffers Documentation](https://developers.google.com/protocol-buffers)
+- [gRPC Python Documentation](https://grpc.io/docs/languages/python/)
+- [Salesforce Data Cloud SQL Reference](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/)

README.md

@@ -17,7 +17,13 @@ This MCP server provides a seamless integration between Cursor and Salesforce Da
    ```bash
    pip install -r requirements.txt
    ```
-3. Connect to the MCP server in Cursor:
+3. Build the Protocol Buffer files:
+   ```bash
+   make protos
+   # Or: python compile_protos.py
+   ```
+   For more details on the proto build system, see [PROTO_BUILD.md](PROTO_BUILD.md).
+4. Connect to the MCP server in Cursor:
    - Open Cursor IDE.
    - Go to **Cursor Settings** → **MCP**.
    - Click on **Add new global MCP server**.