Skip to content

mcp-tools.md

Latest commit

 

History

History
199 lines (131 loc) · 8.23 KB

mcp-tools.md

File metadata and controls

199 lines (131 loc) · 8.23 KB

MCP Tool Guide

This guide helps you understand what the Deephaven MCP tools can do and how to use them effectively with AI assistants like GitHub Copilot.

Note: The AI assistant can see the full tool schemas automatically. This guide focuses on when and how to use each tool.

Quick Reference

Category Tools Purpose
Server Management connectToServer, listServers Connect to and list configured servers
Connections listConnections Check active connections
Code Execution runCode, runCodeFromUri Execute Python/Groovy code
Variables listVariables, openVariablePanels Query and interact with variables
Table Data & Stats getTableData, getTableStats, getColumnStats Fetch and analyze table data
Remote File Sources addRemoteFileSources, listRemoteFileSources, removeRemoteFileSources Manage server file source paths
Logging getLogs, showOutputPanel Access and view logs

Server Management

Listing and Connecting to Servers

Use listServers to see what Deephaven servers are configured in your VS Code settings. This is useful when you need to check server status or see what's available.

Use connectToServer to create a connection to a configured server. You need a connection before you can run code.

Common patterns:

"Connect to my Deephaven localhost" → AI uses listServers to find it, then connectToServer
"Connect to my analytics DH server" → AI uses listServers to match a server label containing "analytics", then connectToServer
"What servers do I have configured?" → AI uses listServers
"Is my Deephaven server running?" → AI uses listServers to check status

Notes:

  • Servers must be configured in VS Code settings first (see Configuration).
  • Community servers auto-start if they're pip-managed.
  • The AI can find servers by URL or label when connecting.
  • Connecting to Enterprise servers creates a new worker.

Running Code

Execute Code Snippets or Files

Use runCode when you want to execute code directly (like "run this Python snippet").

Use runCodeFromUri when working with files in your workspace (like "run this file" or "run lines 10-20").

Auto-connection: If you're not connected, runCode will try to connect automatically to a running server.

Common patterns:

"Create a table with 1000 rows" → AI generates code and uses runCode
"Run a Python script to create a simple ticking table" → AI generates code and uses runCode
"Run my analysis.py file" → AI uses runCodeFromUri
"Execute just the data loading part" → AI uses runCodeFromUri with selection

Notes:

  • Language is detected from the file extension or specified explicitly.
  • Variables created by the code are returned in the response.

Checking Connections

See What's Connected

Use listConnections to see active connections and their status.

Common patterns:

"What Deephaven connections are active?" → AI uses listConnections
"Is my DH server still connected?" → AI uses listConnections with URL filter
"Run this against my acme-server connection" → AI uses listConnections to find the URL for "acme-server"

Useful for:

  • Debugging connection issues.
  • Checking if code is currently running.
  • Resolving connection names to URLs.

Working with Variables

List and Open Variable Panels

Use listVariables to see all panel variables available on a connection. This returns variable metadata including IDs, titles, and types.

Use openVariablePanels to open UI panels for specific variables (tables, plots, etc.). Requires variable objects with both id and title from listVariables or code execution responses.

Common patterns:

"What variables are available?" → AI uses listVariables
"Show me all the tables" → AI uses listVariables, filters by type "Table"
"Open the sales_data table" → AI uses listVariables to find it, then openVariablePanels
"Reopen the panels I closed earlier" → AI uses listVariables to find variables, then openVariablePanels

Notes:

  • Variables are automatically opened as panels after code execution, so openVariablePanels is typically used to reopen panels that were closed or for variables that weren't initially opened.
  • listVariables only returns variables that support panels (tables, plots, etc.), not scalar values or functions.
  • Panel URLs are included in responses for UI verification.

Table Data & Statistics

Fetch and Analyze Table Data

Use getTableData to fetch paginated data from a table. Returns actual row data with configurable limit and offset for pagination.

Use getTableStats to get schema information and basic statistics like row count, column names, types, and descriptions.

Use getColumnStats to get detailed statistics for a specific column (min, max, average, unique values, etc.).

Common patterns:

"Show me the first 10 rows" → AI uses getTableData with limit=10
"What columns are in this table?" → AI uses getTableStats
"Get statistics for the price column" → AI uses getColumnStats with columnName="price"
"How many rows are in my table?" → AI uses getTableStats (includes rowCount)
"What's the average value in the sales column?" → AI uses getColumnStats

Notes:

  • Prefer variableId (from runCode or listVariables) over tableName when available.
  • getTableData supports pagination via limit and offset parameters (max 10,000 rows per request).
  • Statistics are computed on-demand and may take time for large tables.
  • All tools work with both static and ticking (real-time) tables.

Remote File Sources

Manage Server File Paths

Remote file sources allow the Deephaven server to access source files during code execution (e.g., for Python imports or file reading).

Use addRemoteFileSources to add workspace folders as remote file sources on a connection.

Use listRemoteFileSources to see which folders are currently registered as remote file sources.

Use removeRemoteFileSources to unregister folders when they're no longer needed.

Common patterns:

"Add my workspace folder as a remote source" → AI uses addRemoteFileSources
"What remote file sources are configured?" → AI uses listRemoteFileSources
"Remove the old data folder from sources" → AI uses removeRemoteFileSources
"Let the server access my local Python modules" → AI uses addRemoteFileSources

Useful for:

  • Enabling server-side Python imports from local files.
  • Allowing Deephaven to read data files from your workspace.
  • Setting up development workflows with local code.

Notes:

  • Only works with Enterprise (DHE) servers.
  • Folders must be within the workspace.
  • Files are synced to the server when registered.

Accessing Logs

View Extension Output

Use getLogs to retrieve log history programmatically. Specify "server" for server logs or "debug" for detailed diagnostics.

Use showOutputPanel to open the VS Code Output panel in the UI.

Common patterns:

"Show me the server logs" → AI uses getLogs with logType="server"
"What errors happened?" → AI uses getLogs with logType="debug"
"Open the output panel" → AI uses showOutputPanel

Useful for:

  • Debugging connection issues.
  • Investigating code execution errors.
  • Seeing what happened during operations.

Getting Help

If tools aren't working as expected:

  1. Use getLogs to see what errors occurred.
  2. Verify your server configuration in VS Code settings.
  3. Check that the MCP server is enabled (deephaven.mcp.enabled).
  4. Check the VS Code Output panel (View → Output → Deephaven) for error messages.