@bridgenet-tech/spear-data 1.5.0

package/dist/tools/sql-query.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { getPostgres } from "../db.js";
+const InputSchema = z.object({
+    sql: z.string()
+        .min(1, "SQL query is required")
+        .describe("A read-only SQL SELECT query to run against the Spear database"),
+    target: z.enum(["local", "cloud"])
+        .default("cloud")
+        .describe("Which database to query: 'local' (Docker) or 'cloud' (Neon)"),
+    limit: z.number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(100)
+        .describe("Maximum rows to return (default 100, max 1000)")
+}).strict();
+// Extract table names from FROM/JOIN clauses
+function extractTables(sql) {
+    const pattern = /\b(?:FROM|JOIN)\s+((?:"?\w+"?)(?:\."?\w+"?)?)/gi;
+    const tables = new Set();
+    let match;
+    while ((match = pattern.exec(sql)) !== null) {
+        const full = match[1].replace(/"/g, '').toLowerCase();
+        const table = full.includes('.') ? full.split('.').pop() : full;
+        tables.add(table);
+    }
+    return [...tables].sort();
+}
+// Validate that SQL is read-only
+function validateReadOnly(sql) {
+    const normalized = sql.trim().replace(/--.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "").trim();
+    const firstWord = normalized.split(/\s+/)[0]?.toUpperCase();
+    const allowed = ["SELECT", "WITH", "EXPLAIN"];
+    if (!firstWord || !allowed.includes(firstWord)) {
+        return `Only SELECT, WITH, and EXPLAIN statements are allowed. Got: ${firstWord ?? "(empty)"}`;
+    }
+    // Block dangerous patterns even in subqueries
+    const dangerous = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|COPY|EXECUTE)\b/i;
+    if (dangerous.test(normalized)) {
+        return "Write operations are not allowed. This server is read-only.";
+    }
+    return null;
+}
+export function registerSqlQuery(server) {
+    server.registerTool("spear_sql_query", {
+        title: "SQL Query",
+        description: `Run a read-only SQL SELECT query against the Spear PSA database (Postgres).
+
+Returns query results with full transparency metadata: target database, execution time, row count, tables referenced, and the SQL that ran.
+
+Core tables:
+- tickets: 150K+ service tickets with status, priority, SLA fields, AI fields, embeddings
+- ticket_notes: 2.4M+ technician notes, activity records, and automated entries per ticket
+- ticket_note_chunks: ~300K+ chunked note groups per ticket for semantic search
+- teams_message_chunks: Microsoft Teams TechTeam channel messages chunked for semantic search, with channel names, authors, timestamps
+- organizations: ~700 client companies with tier, location, active status
+- contacts: ~6K client contacts linked to organizations
+- agents: ~77 technicians/resources with roles and active status
+- assets: ~7.5K managed devices with serial numbers, types, organizations
+- contracts: ~1.5K service contracts with types, status, organizations
+- projects: ~223 projects linked to organizations
+- tasks: ~3.3K project tasks
+- time_entries: ~3.3K time records with hours, dates, agents, tickets
+
+Audit and lookup tables:
+- ticket_audit_log: tracks every status, priority, agent, and queue change on tickets (who changed what, when, old/new values — essential for workflow analysis)
+- ticket_statuses, ticket_priorities, ticket_types, ticket_sources, ticket_queues: lookup/reference tables
+- sync_state: pipeline sync tracking
+- sla_policies: SLA policy definitions
+
+Key columns for business intelligence:
+- tickets: status, priority, ticket_type, source, sla_response_due_at, sla_resolution_due_at, sla_response_breached, sla_resolution_breached, ai_category, ai_summary, created_at, completed_date
+- tickets: organization_id → organizations, assigned_agent_id → agents, contact_id → contacts
+- ticket_audit_log: ticket_id, field_name, old_value, new_value, changed_at, changed_by (reveals automated workflows and manual interventions)
+
+Common patterns:
+- Ticket volume by org: SELECT o.name, COUNT(*) FROM tickets t JOIN organizations o ON o.id = t.organization_id GROUP BY o.name ORDER BY count DESC
+- Agent workload: SELECT agent_name, COUNT(*) FROM tickets WHERE status NOT IN ('Complete','Closed') GROUP BY assigned_agent_id
+- SLA breaches: SELECT * FROM tickets WHERE sla_resolution_breached = true ORDER BY created_at DESC
+
+Use spear_schema to see full table structures. Only SELECT, WITH (CTE), and EXPLAIN are allowed.`,
+        inputSchema: InputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async (params) => {
+        // Validate read-only
+        const error = validateReadOnly(params.sql);
+        if (error) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: ${error}` }]
+            };
+        }
+        // Add LIMIT if not present
+        let sql = params.sql.trim();
+        if (!/\bLIMIT\b/i.test(sql)) {
+            sql = sql.replace(/;?\s*$/, ` LIMIT ${params.limit}`);
+        }
+        const start = performance.now();
+        try {
+            const db = getPostgres(params.target);
+            const rows = await db.unsafe(sql);
+            const ms = Math.round(performance.now() - start);
+            const result = {
+                _meta: {
+                    source: "postgres",
+                    target: params.target,
+                    execution_ms: ms,
+                    row_count: rows.length,
+                    tables_referenced: extractTables(sql),
+                    sql
+                },
+                rows: rows
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            };
+        }
+        catch (e) {
+            const ms = Math.round(performance.now() - start);
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            _meta: { source: "postgres", target: params.target, execution_ms: ms, sql },
+                            error: e.message
+                        }, null, 2)
+                    }]
+            };
+        }
+    });
+}
+//# sourceMappingURL=sql-query.js.map

package/dist/tools/sql-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-query.js","sourceRoot":"","sources":["../../src/tools/sql-query.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bridgenet-tech/spear-data",
+  "version": "1.5.0",
+  "description": "Read-only MCP server for Spear PSA data exploration — Postgres + pgvector",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "spear-data": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "psa",
+    "autotask",
+    "postgres",
+    "pgvector"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bridgenet-tech/spear.git",
+    "directory": "mcp/spear-data"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "postgres": "^3.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.2"
+  }
+}