@quarri/claude-data-tools 1.1.1 → 1.2.1

package/README.md

@@ -1,98 +1,163 @@
-# Quarri Claude Code Plugin
+# Quarri Claude Plugin
 
 Natural language data analysis with Quarri. Query databases, create visualizations, and get insights using plain English.
 
 ## Installation
 
-### Via Claude Code Marketplace
+### Claude Code
 
 ```bash
 claude /install quarri
 ```
 
-### Manual Installation
+Or manually add to your Claude Code configuration:
+
+```json
+{
+  "mcpServers": {
+    "quarri": {
+      "command": "npx",
+      "args": ["@quarri/claude-data-tools"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+1. **Authenticate first** (one-time setup):
 
 ```bash
-npm install -g @quarri/claude-data-tools
+# New users - create a free trial account
+npx @quarri/claude-data-tools signup
+
+# Existing users - log in
+npx @quarri/claude-data-tools auth
 ```
 
-Then add to your Claude Code configuration:
+2. **Add to Claude Desktop config**:
+
+   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "quarri": {
-      "command": "quarri-mcp"
+      "command": "npx",
+      "args": ["@quarri/claude-data-tools"]
     }
   }
 }
 ```
 
+3. **Restart Claude Desktop**
+
 ## Authentication
 
-On first use, you'll be prompted to authenticate:
+### New Users
+
+Create a free trial account:
+
+```bash
+npx @quarri/claude-data-tools signup
+```
 
-### Existing Quarri Users
+You'll receive a verification email to complete signup.
+
+### Existing Users
+
+```bash
+npx @quarri/claude-data-tools auth
+```
 
 1. Enter your email address
 2. Check your email for a 6-digit verification code
 3. Enter the code to complete authentication
 
-### New Users (with invitation)
-
-1. Select "invite" when prompted
-2. Enter your email address
-3. Enter the invitation token from your admin's email
-4. Your account will be created automatically
+Credentials are stored securely in `~/.quarri/credentials`.
 
 ## Features
 
-### 47 Tools for Data Analysis
-
-**Sub-Agents (12):**
-- `quarri_query_agent` - Generate SQL from natural language
-- `quarri_explain_agent` - Explain SQL queries
-- `quarri_chart_agent` - Generate visualizations
-- `quarri_metric_builder_agent` - Define metrics interactively
-- `quarri_planning_agent` - Create analysis plans
-- `quarri_insight_agent` - Generate actionable insights
-- `quarri_stats_agent` - Statistical analysis
-- `quarri_staging_agent` - Stage raw data
-- `quarri_modeling_agent` - Design data models
-- `quarri_transformers_agent` - Generate transformation SQL
-- `quarri_extraction_agent` - Create data pipelines
-- `quarri_query_with_analysis` - Full analysis pipeline
-
-**Data Tools (8):**
-- `quarri_execute_sql` - Run SQL queries
-- `quarri_get_schema` - View database schema
-- `quarri_search_values` - Semantic search
-- `quarri_get_metrics`, `quarri_create_metric`, `quarri_approve_metric`
-- `quarri_get_metric_detail`, `quarri_search_metrics`
-
-**Configuration (8):**
-- `quarri_list_agent_prompts`, `quarri_update_agent_prompt`
-- `quarri_list_rules`, `quarri_create_rule`, `quarri_update_rule`, `quarri_delete_rule`
-- `quarri_vectorize_column_values`, `quarri_list_searchable_columns`
-
-**Canvas (5):**
-- `quarri_list_canvases`, `quarri_get_canvas`
-- `quarri_create_chart_panel`, `quarri_update_chart_panel`
-- `quarri_export_canvas`
-
-**Team (3):**
-- `quarri_list_teams`, `quarri_get_team_filters`, `quarri_get_team_restrictions`
-
-**Extraction (7):**
-- `quarri_list_extraction_sources`, `quarri_configure_extraction`
-- `quarri_discover_tables`, `quarri_propose_transformation`
-- `quarri_upload_csv`, `quarri_generate_quarri_schema`, `quarri_list_raw_tables`
-
-**Debug (3):**
-- `quarri_read_server_logs`, `quarri_query_repl_activity`, `quarri_read_fly_logs`
-
-**Session (2):**
-- `quarri_list_databases`, `quarri_select_database`
+### Interactive UI Components (MCP Apps)
+
+Quarri returns rich, interactive UI components for data display:
+
+- **Data Tables** - Sortable, paginated query results
+- **Charts** - Interactive Plotly visualizations
+- **Schema Explorer** - Visual database structure
+- **Metrics Cards** - KPI displays with status badges
+- **Logs View** - Syntax-highlighted log entries
+- **Code View** - Syntax-highlighted source code
+
+These render automatically in Claude Desktop and Claude Code when using supported tools.
+
+### 39 Tools for Data Analysis
+
+**Data Tools:**
+- `quarri_execute_sql` - Run SQL queries → interactive data table
+- `quarri_get_schema` - View database schema → schema explorer
+- `quarri_search_values` - Semantic search → search results
+- `quarri_get_metrics` - List defined metrics → metrics list
+- `quarri_create_metric` - Define new metrics
+- `quarri_approve_metric` - Approve pending metrics
+- `quarri_get_metric_detail` - Metric details → metric card
+- `quarri_search_metrics` - Search metrics → metrics list
+
+**Configuration:**
+- `quarri_list_agent_prompts` - View agent prompts → prompts list
+- `quarri_update_agent_prompt` - Update prompts
+- `quarri_list_rules` - Query generation rules → rules list
+- `quarri_create_rule`, `quarri_update_rule`, `quarri_delete_rule`
+- `quarri_vectorize_column_values` - Enable semantic search
+- `quarri_list_searchable_columns` - View searchable columns → columns list
+
+**Team & Security:**
+- `quarri_list_teams` - Organization teams → teams list
+- `quarri_get_team_filters` - Row-level security → filters view
+- `quarri_get_team_restrictions` - Column restrictions → restrictions view
+
+**Data Extraction:**
+- `quarri_list_extraction_sources` - Data sources → sources list
+- `quarri_configure_extraction` - Configure sources
+- `quarri_discover_tables` - Discover tables → tables list
+- `quarri_propose_transformation` - Propose transforms
+- `quarri_upload_csv` - Upload CSV files
+- `quarri_generate_quarri_schema` - Generate schema config
+- `quarri_list_raw_tables` - Raw tables → tables list
+
+**Connectors:**
+- `quarri_get_connector_code` - View connector code → code view
+- `quarri_get_connector_logs` - Connector logs → logs view
+- `quarri_log_analysis_run` - Log analysis runs
+- `quarri_schedule_extraction` - Schedule extractions
+- `quarri_store_generated_code` - Save connector code
+- `quarri_update_connector_code` - Update connector code
+
+**Debug:**
+- `quarri_read_server_logs` - Server logs → logs view
+- `quarri_query_repl_activity` - Activity history → activity list
+- `quarri_read_fly_logs` - Production logs → logs view
+
+**Session:**
+- `quarri_auth_status` - Check auth → auth status card
+- `quarri_trial_status` - Trial info → trial status card
+- `quarri_list_databases` - Available databases
+- `quarri_select_database` - Switch database
+
+### Skills (Slash Commands)
+
+Quarri includes intelligent skills for common workflows:
+
+- `/quarri-query` - Natural language to SQL
+- `/quarri-analyze` - Full analysis pipeline
+- `/quarri-chart` - Generate visualizations
+- `/quarri-insights` - Statistical insights
+- `/quarri-metric` - Define metrics interactively
+- `/quarri-explain` - Explain SQL queries
+- `/quarri-extract` - Create data pipelines
+- `/quarri-diagnose` - Debug connector issues
+- `/quarri-guide` - Quarri usage guide
 
 ## Usage Examples
 
@@ -102,64 +167,58 @@ On first use, you'll be prompted to authenticate:
 What were our top 10 products by revenue last month?
 ```
 
-Claude will use `quarri_query_with_analysis` to:
-1. Generate SQL from your question
-2. Execute the query
-3. Perform statistical analysis
-4. Generate a chart
-5. Provide key insights
+Claude will generate SQL, execute it, and return results in an interactive data table.
 
-### Create a Metric
+### Create a Visualization
 
 ```
-Help me define a metric for customer lifetime value
+/quarri-chart Show monthly revenue trend for 2024
 ```
 
-Claude will guide you through defining the metric using `quarri_metric_builder_agent`.
+Returns an interactive Plotly chart rendered in the conversation.
 
-### Configure Semantic Search
+### Define a Metric
 
 ```
-Enable semantic search on the product_name column
+/quarri-metric Help me define customer lifetime value
 ```
 
-Claude will use `quarri_vectorize_column_values` to enable natural language search.
+Guides you through defining a reusable metric with SQL template.
+
+### Configure Semantic Search
 
-## Configuration
+```
+Enable semantic search on the product_name column
+```
 
-Credentials are stored in `~/.quarri/credentials` with secure permissions (0600).
+Uses `quarri_vectorize_column_values` to enable natural language search on column values.
 
-### Environment Variables
+## Environment Variables
 
 - `QUARRI_API_URL` - API endpoint (default: https://app.quarri.ai)
 
 ## Development
 
-### Building
-
 ```bash
+# Install dependencies
 npm install
-npm run build
-```
 
-### Testing
+# Build
+npm run build
 
-```bash
+# Run tests
 npm test
-```
-
-### Local Development
 
-```bash
+# Local development
 npm run dev
 ```
 
-## License
-
-MIT
-
 ## Support
 
 - GitHub Issues: https://github.com/djayatillake/quarri-claude-plugin/issues
 - Documentation: https://docs.quarri.ai
 - Email: support@quarri.ai
+
+## License
+
+MIT

package/dist/index.js

@@ -13,15 +13,17 @@ const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const client_js_1 = require("./api/client.js");
 const token_store_js_1 = require("./auth/token-store.js");
 const definitions_js_1 = require("./tools/definitions.js");
+const resources_js_1 = require("./ui/resources.js");
 // Initialize API client
 const client = new client_js_1.QuarriApiClient();
-// Initialize MCP server
+// Initialize MCP server with resources capability
 const server = new index_js_1.Server({
     name: 'quarri',
     version: '1.0.0',
 }, {
     capabilities: {
         tools: {},
+        resources: {},
     },
 });
 /**
@@ -56,6 +58,40 @@ Not authenticated with Quarri.
 After authenticating, restart Claude Code to pick up the credentials.
 `.trim();
 }
+/**
+ * Handle list resources request
+ */
+server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => {
+    return {
+        resources: resources_js_1.UI_RESOURCES.map((resource) => ({
+            uri: resource.uri,
+            name: resource.name,
+            description: resource.description,
+            mimeType: resource.mimeType,
+        })),
+    };
+});
+/**
+ * Handle read resource request
+ */
+server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    const resource = resources_js_1.UI_RESOURCES.find((r) => r.uri === uri);
+    if (!resource) {
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
+    }
+    // Resources are populated dynamically by tool responses
+    // This handler returns an empty template
+    return {
+        contents: [
+            {
+                uri: resource.uri,
+                mimeType: resource.mimeType,
+                text: JSON.stringify({ type: resource.name, data: null }),
+            },
+        ],
+    };
+});
 /**
  * Handle list tools request
  */
@@ -65,6 +101,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            ...(tool._meta && { _meta: tool._meta }),
         })),
     };
 });
@@ -78,14 +115,23 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         const credentials = (0, token_store_js_1.loadCredentials)();
         const selected = (0, token_store_js_1.getSelectedDatabase)();
         if (!credentials) {
+            const unauthData = {
+                authenticated: false,
+                message: 'Not authenticated. Run: npx @quarri/claude-data-tools auth',
+            };
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            authenticated: false,
-                            message: 'Not authenticated. Run: npx @quarri/claude-data-tools auth',
-                        }, null, 2),
+                        text: JSON.stringify(unauthData, null, 2),
+                    },
+                    {
+                        type: 'resource',
+                        resource: {
+                            uri: 'ui://quarri/auth-status',
+                            mimeType: 'application/vnd.quarri.auth-status+json',
+                            text: JSON.stringify((0, resources_js_1.renderAuthStatus)({ authenticated: false })),
+                        },
                     },
                 ],
             };
@@ -93,19 +139,34 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         const expiresAt = new Date(credentials.expiresAt);
         const isExpired = expiresAt < new Date();
         const expiresIn = Math.round((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+        const authData = {
+            authenticated: !isExpired,
+            email: credentials.email,
+            role: credentials.role,
+            databases: credentials.databases.map(d => d.display_name || d.database_name),
+            selectedDatabase: selected,
+            tokenExpires: credentials.expiresAt,
+            expiresInDays: isExpired ? 'EXPIRED' : expiresIn,
+        };
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({
-                        authenticated: !isExpired,
-                        email: credentials.email,
-                        role: credentials.role,
-                        databases: credentials.databases.map(d => d.display_name || d.database_name),
-                        selectedDatabase: selected,
-                        tokenExpires: credentials.expiresAt,
-                        expiresInDays: isExpired ? 'EXPIRED' : expiresIn,
-                    }, null, 2),
+                    text: JSON.stringify(authData, null, 2),
+                },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: 'ui://quarri/auth-status',
+                        mimeType: 'application/vnd.quarri.auth-status+json',
+                        text: JSON.stringify((0, resources_js_1.renderAuthStatus)({
+                            authenticated: !isExpired,
+                            email: credentials.email,
+                            role: credentials.role,
+                            databases: credentials.databases.map(d => d.display_name || d.database_name),
+                            expiresInDays: isExpired ? 'EXPIRED' : expiresIn,
+                        })),
+                    },
                 },
             ],
         };
@@ -177,35 +238,62 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         }
         const data = result.data;
         if (!data || !data.is_trial) {
+            const nonTrialData = {
+                is_trial: false,
+                message: 'This is not a trial account.',
+                database: data?.display_name || data?.database_name,
+            };
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            is_trial: false,
-                            message: 'This is not a trial account.',
-                            database: data?.display_name || data?.database_name,
-                        }, null, 2),
+                        text: JSON.stringify(nonTrialData, null, 2),
+                    },
+                    {
+                        type: 'resource',
+                        resource: {
+                            uri: 'ui://quarri/trial-status',
+                            mimeType: 'application/vnd.quarri.trial-status+json',
+                            text: JSON.stringify((0, resources_js_1.renderTrialStatus)({
+                                is_trial: false,
+                                organization: data?.display_name || data?.database_name,
+                            })),
+                        },
                     },
                 ],
             };
         }
+        const trialData = {
+            is_trial: true,
+            organization: data.display_name,
+            days_remaining: data.days_remaining,
+            expires_at: data.expires_at,
+            data_limit_gb: data.data_limit_gb,
+            signup_type: data.signup_type,
+            upgrade_contact: data.upgrade_contact,
+            message: data.days_remaining && data.days_remaining <= 2
+                ? `⚠️ Your trial expires in ${data.days_remaining} day(s). Contact ${data.upgrade_contact} to upgrade.`
+                : `Trial active with ${data.days_remaining} days remaining.`,
+        };
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({
-                        is_trial: true,
-                        organization: data.display_name,
-                        days_remaining: data.days_remaining,
-                        expires_at: data.expires_at,
-                        data_limit_gb: data.data_limit_gb,
-                        signup_type: data.signup_type,
-                        upgrade_contact: data.upgrade_contact,
-                        message: data.days_remaining && data.days_remaining <= 2
-                            ? `⚠️ Your trial expires in ${data.days_remaining} day(s). Contact ${data.upgrade_contact} to upgrade.`
-                            : `Trial active with ${data.days_remaining} days remaining.`,
-                    }, null, 2),
+                    text: JSON.stringify(trialData, null, 2),
+                },
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: 'ui://quarri/trial-status',
+                        mimeType: 'application/vnd.quarri.trial-status+json',
+                        text: JSON.stringify((0, resources_js_1.renderTrialStatus)({
+                            is_trial: true,
+                            organization: data.display_name,
+                            days_remaining: data.days_remaining,
+                            expires_at: data.expires_at,
+                            data_limit_gb: data.data_limit_gb,
+                        })),
+                    },
                 },
             ],
         };
@@ -252,15 +340,127 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             isError: true,
         };
     }
+    // Build response with text and optional UI resource
+    const content = [
+        {
+            type: 'text',
+            text: formatToolResponse(name, result),
+        },
+    ];
+    // Add UI resource if available for this tool
+    const uiResourceContent = buildUIResource(name, result);
+    if (uiResourceContent) {
+        content.push(uiResourceContent);
+    }
+    return { content };
+});
+/**
+ * Build UI resource for a tool response
+ */
+function buildUIResource(toolName, result) {
+    const uiResource = (0, resources_js_1.getToolUIResource)(toolName);
+    if (!uiResource)
+        return null;
+    let rendered = null;
+    switch (toolName) {
+        case 'quarri_execute_sql':
+            if (result.rows && Array.isArray(result.rows)) {
+                const rows = result.rows;
+                const columns = result.columns || (rows.length > 0 ? Object.keys(rows[0]) : []);
+                rendered = (0, resources_js_1.renderDataTable)(rows, columns);
+            }
+            break;
+        case 'quarri_get_schema':
+            if (result.tables && Array.isArray(result.tables)) {
+                rendered = (0, resources_js_1.renderSchemaExplorer)(result.tables);
+            }
+            break;
+        case 'quarri_search_values':
+            if (result.results && Array.isArray(result.results)) {
+                rendered = (0, resources_js_1.renderSearchResults)(result.results);
+            }
+            break;
+        case 'quarri_get_metrics':
+        case 'quarri_search_metrics':
+            if (result.metrics && Array.isArray(result.metrics)) {
+                rendered = (0, resources_js_1.renderMetricsList)(result.metrics);
+            }
+            break;
+        case 'quarri_get_metric_detail':
+            if (result.id) {
+                rendered = (0, resources_js_1.renderMetricDetail)(result);
+            }
+            break;
+        case 'quarri_list_agent_prompts':
+            if (result.prompts && Array.isArray(result.prompts)) {
+                rendered = (0, resources_js_1.renderPromptsList)(result.prompts);
+            }
+            break;
+        case 'quarri_list_rules':
+            if (result.rules && Array.isArray(result.rules)) {
+                rendered = (0, resources_js_1.renderRulesList)(result.rules);
+            }
+            break;
+        case 'quarri_list_searchable_columns':
+            if (result.columns && Array.isArray(result.columns)) {
+                rendered = (0, resources_js_1.renderColumnsList)(result.columns);
+            }
+            break;
+        case 'quarri_list_teams':
+            if (result.teams && Array.isArray(result.teams)) {
+                rendered = (0, resources_js_1.renderTeamsList)(result.teams);
+            }
+            break;
+        case 'quarri_get_team_filters':
+            if (result.filters && Array.isArray(result.filters)) {
+                rendered = (0, resources_js_1.renderTeamFilters)(result.filters);
+            }
+            break;
+        case 'quarri_get_team_restrictions':
+            if (result.restrictions && Array.isArray(result.restrictions)) {
+                rendered = (0, resources_js_1.renderTeamRestrictions)(result.restrictions);
+            }
+            break;
+        case 'quarri_list_extraction_sources':
+            if (result.sources && Array.isArray(result.sources)) {
+                rendered = (0, resources_js_1.renderSourcesList)(result.sources);
+            }
+            break;
+        case 'quarri_discover_tables':
+        case 'quarri_list_raw_tables':
+            if (result.tables && Array.isArray(result.tables)) {
+                rendered = (0, resources_js_1.renderTablesList)(result.tables);
+            }
+            break;
+        case 'quarri_read_server_logs':
+        case 'quarri_read_fly_logs':
+        case 'quarri_get_connector_logs':
+            if (result.logs && Array.isArray(result.logs)) {
+                rendered = (0, resources_js_1.renderLogsView)(result.logs);
+            }
+            break;
+        case 'quarri_query_repl_activity':
+            if (result.activities && Array.isArray(result.activities)) {
+                rendered = (0, resources_js_1.renderActivityList)(result.activities);
+            }
+            break;
+        case 'quarri_get_connector_code':
+            if (result.code && typeof result.code === 'string') {
+                rendered = (0, resources_js_1.renderCodeView)(result.code, result.language || 'python');
+            }
+            break;
+    }
+    if (!rendered)
+        return null;
     return {
-        content: [
-            {
-                type: 'text',
-                text: formatToolResponse(name, result),
-            },
-        ],
+        type: 'resource',
+        resource: {
+            uri: uiResource.uri,
+            mimeType: uiResource.mimeType,
+            text: JSON.stringify(rendered),
+        },
     };
-});
+}
 /**
  * Format error response for better readability
  */