@gokiteam/goki-dev 0.2.2 → 0.2.3

package/cli/NgrokManager.js

@@ -9,6 +9,7 @@ const NGROK_API = 'http://localhost:4040'
 const DATA_DIR = path.join(os.homedir(), '.goki-dev', 'data')
 const PID_FILE = path.join(DATA_DIR, 'ngrok.pid')
 const STATE_FILE = path.join(DATA_DIR, 'ngrok.json')
+const DOMAIN_FILE = path.join(DATA_DIR, 'ngrok-domain.txt')
 
 export class NgrokManager {
   // --- PID File Management ---
@@ -301,6 +302,12 @@ export class NgrokManager {
   // --- Domain Management ---
 
   static async loadDomain () {
+    // Check local domain file first (most reliable, survives tunnel failures)
+    try {
+      const domain = fs.readFileSync(DOMAIN_FILE, 'utf8').trim()
+      if (domain) return domain
+    } catch { /* file doesn't exist yet */ }
+    // Try dev-tools API
     try {
       const response = await fetch(`${DEV_TOOLS_API}/v1/webhooks/settings/get`, {
         method: 'POST',
@@ -311,17 +318,24 @@ export class NgrokManager {
       if (response.ok) {
         const result = await response.json()
         const domain = result.data?.settings?.ngrok_domain
-        if (domain) return domain
+        if (domain) {
+          // Persist locally for next time
+          this.ensureDataDir()
+          fs.writeFileSync(DOMAIN_FILE, domain.trim(), 'utf8')
+          return domain
+        }
       }
-    } catch {
-      // API failed, fall through to local file fallback
-    }
-    // Fallback: read from local state file
+    } catch { /* API not available */ }
+    // Last resort: check tunnel state file
     const state = this.readState()
     return state?.domain || null
   }
 
   static async saveDomain (domain) {
+    // Always save locally so it survives tunnel failures and API downtime
+    this.ensureDataDir()
+    fs.writeFileSync(DOMAIN_FILE, domain.trim(), 'utf8')
+    // Also save to dev-tools API (best-effort)
     try {
       await fetch(`${DEV_TOOLS_API}/v1/webhooks/settings/update`, {
         method: 'POST',
@@ -332,7 +346,7 @@ export class NgrokManager {
         signal: AbortSignal.timeout(3000)
       })
     } catch (error) {
-      Logger.warn(`Failed to save ngrok domain: ${error.message}`)
+      Logger.warn(`Failed to save ngrok domain to API: ${error.message}`)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gokiteam/goki-dev",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Unified local development platform for Goki services",
   "type": "module",
   "bin": {

package/src/api/firestore/Controllers.js

@@ -72,6 +72,20 @@ export const Controllers = {
     ctx.reply(result)
   },
 
+  async setDocument (ctx) {
+    const { traceId } = ctx.state
+    const { collectionPath, documentId, fields, projectId } = ctx.request.body
+    const result = await Logic.setDocument({ collectionPath, documentId, fields, projectId, traceId })
+    ctx.reply(result)
+  },
+
+  async createBatch (ctx) {
+    const { traceId } = ctx.state
+    const { collectionPath, documents, projectId } = ctx.request.body
+    const result = await Logic.createBatch({ collectionPath, documents, projectId, traceId })
+    ctx.reply(result)
+  },
+
   async executeQuery (ctx) {
     const { traceId } = ctx.state
     const { collectionPath, where, orderBy, limit, projectId } = ctx.request.body

package/src/api/firestore/Logic.js

@@ -1,4 +1,4 @@
-import { initializeApp, getApps, deleteApp } from 'firebase-admin/app'
+import { initializeApp, getApps } from 'firebase-admin/app'
 import { getFirestore } from 'firebase-admin/firestore'
 import { SqliteStore } from '../../singletons/SqliteStore.js'
 import { Application } from '../../configs/Application.js'
@@ -354,6 +354,79 @@ export const Logic = {
     }
   },
 
+  async setDocument (params) {
+    const { collectionPath, documentId, fields, traceId } = params
+    const projectId = resolveProjectId(params)
+    try {
+      const url = `${FIRESTORE_API}/v1/projects/${projectId}/databases/${DATABASE}/documents/${collectionPath}/${documentId}`
+      const response = await fetch(url, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ fields })
+      })
+      if (!response.ok) {
+        throw new Error(`Firestore API error: ${response.statusText}`)
+      }
+      const document = await response.json()
+      trackCollection(collectionPath)
+      return {
+        document,
+        traceId
+      }
+    } catch (error) {
+      return {
+        status: 'error',
+        message: error.message,
+        traceId
+      }
+    }
+  },
+
+  async createBatch (params) {
+    const { collectionPath, documents = [], traceId } = params
+    const projectId = resolveProjectId(params)
+    const BATCH_SIZE = 20
+    try {
+      const failedIds = []
+      let createdCount = 0
+      for (let i = 0; i < documents.length; i += BATCH_SIZE) {
+        const batch = documents.slice(i, i + BATCH_SIZE)
+        const results = await Promise.allSettled(
+          batch.map(doc =>
+            this.createDocument({
+              collectionPath,
+              projectId,
+              documentId: doc.documentId,
+              fields: doc.fields,
+              traceId
+            })
+          )
+        )
+        for (let j = 0; j < results.length; j++) {
+          const result = results[j]
+          if (result.status === 'fulfilled' && !result.value.status) {
+            createdCount++
+          } else {
+            const docId = batch[j].documentId || `index-${i + j}`
+            failedIds.push(docId)
+          }
+        }
+      }
+      return {
+        success: true,
+        createdCount,
+        failedIds,
+        traceId
+      }
+    } catch (error) {
+      return {
+        status: 'error',
+        message: error.message,
+        traceId
+      }
+    }
+  },
+
   async clearCollection (params) {
     const { collectionPath, projectId, traceId } = params
     try {

package/src/api/firestore/Router.js

@@ -11,6 +11,8 @@ v1.post('/documents/get', Controllers.getDocument)
 v1.post('/documents/create', Controllers.createDocument)
 v1.post('/documents/update', Controllers.updateDocument)
 v1.post('/documents/delete', Controllers.deleteDocument)
+v1.post('/documents/set', Controllers.setDocument)
+v1.post('/documents/create-batch', Controllers.createBatch)
 v1.post('/documents/delete-by-query', Controllers.deleteByQuery)
 v1.post('/documents/delete-by-prefix', Controllers.deleteByPrefix)
 v1.post('/documents/delete-batch', Controllers.deleteBatch)

package/src/api/firestore/Schemas.js

@@ -0,0 +1,160 @@
+import { Joi } from '@gokiteam/koa'
+
+const whereClause = Joi.object({
+  field: Joi.string().required(),
+  operator: Joi.string().valid('==', '!=', '<', '<=', '>', '>=', 'array-contains', 'in', 'array-contains-any').required(),
+  value: Joi.any().required()
+})
+
+const pageOptions = Joi.object({
+  limit: Joi.number().integer().min(1).max(10000).default(50),
+  offset: Joi.number().integer().min(0).default(0)
+}).optional()
+
+export const Schemas = {
+  listProjects: {
+    request: {
+      body: {}
+    }
+  },
+
+  listCollections: {
+    request: {
+      body: {
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  listDocuments: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        projectId: Joi.string().optional(),
+        page: pageOptions
+      }
+    }
+  },
+
+  getDocument: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentId: Joi.string().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  createDocument: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentId: Joi.string().optional(),
+        fields: Joi.object().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  setDocument: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentId: Joi.string().required(),
+        fields: Joi.object().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  updateDocument: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentId: Joi.string().required(),
+        fields: Joi.object().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  deleteDocument: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentId: Joi.string().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  createBatch: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documents: Joi.array().items(
+          Joi.object({
+            documentId: Joi.string().optional(),
+            fields: Joi.object().required()
+          })
+        ).min(1).max(500).required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  deleteByQuery: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        where: whereClause.required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  deleteByPrefix: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        prefix: Joi.string().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  deleteBatch: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        documentIds: Joi.array().items(Joi.string()).min(1).max(500).required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  executeQuery: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        where: Joi.array().items(whereClause).optional(),
+        orderBy: Joi.object({
+          field: Joi.string().required(),
+          direction: Joi.string().valid('ASCENDING', 'DESCENDING').default('ASCENDING')
+        }).optional(),
+        limit: Joi.number().integer().min(1).max(10000).default(50),
+        projectId: Joi.string().optional()
+      }
+    }
+  },
+
+  clearCollection: {
+    request: {
+      body: {
+        collectionPath: Joi.string().required(),
+        projectId: Joi.string().optional()
+      }
+    }
+  }
+}

package/src/mcp/tools/data.js

@@ -5,6 +5,7 @@ export function registerDataTools (server, apiClient) {
     'platform_stats',
     'Get platform dashboard statistics (topic count, message count, log entries, MQTT clients, etc.)',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/dashboard/stats')
@@ -19,6 +20,7 @@ export function registerDataTools (server, apiClient) {
     'platform_export',
     'Export all platform data (topics, subscriptions, messages, logs, etc.)',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/data/export')
@@ -31,11 +33,12 @@ export function registerDataTools (server, apiClient) {
 
   server.tool(
     'platform_import',
-    'Import platform data (optionally clearing existing data first)',
+    '[DESTRUCTIVE] Import platform data (optionally clearing existing data first). Ask the user for confirmation before calling this tool.',
     {
       data: z.record(z.any()).describe('Platform data object to import'),
       clearExisting: z.boolean().optional().describe('Whether to clear existing data before importing')
     },
+    { destructiveHint: true },
     async ({ data, clearExisting }) => {
       try {
         const body = { data }
@@ -50,8 +53,9 @@ export function registerDataTools (server, apiClient) {
 
   server.tool(
     'platform_clear',
-    'Clear all platform data (topics, messages, logs, traffic records)',
+    '[DESTRUCTIVE] Clear all platform data (topics, messages, logs, traffic records). Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/data/clear')
@@ -64,11 +68,12 @@ export function registerDataTools (server, apiClient) {
 
   server.tool(
     'platform_clear_services',
-    'Clear data for specific services. Useful for resetting test state without clearing everything.',
+    '[DESTRUCTIVE] Clear data for specific services. Useful for resetting test state without clearing everything. Ask the user for confirmation before calling this tool.',
     {
       services: z.array(z.string()).optional().describe('Optional list of service names to clear'),
       keepSystemData: z.boolean().optional().describe('Whether to keep system/infrastructure data')
     },
+    { destructiveHint: true },
     async ({ services, keepSystemData }) => {
       try {
         const body = {}

package/src/mcp/tools/docker.js

@@ -63,6 +63,7 @@ export function registerDockerTools (server, apiClient) {
     'docker_list_containers',
     'List all Docker containers on the goki-network with their status, ports, and uptime',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const { stdout } = await execAsync(
@@ -114,10 +115,11 @@ export function registerDockerTools (server, apiClient) {
 
   server.tool(
     'docker_stop_container',
-    'Stop a running Docker container by name',
+    '[DESTRUCTIVE] Stop a running Docker container by name. Ask the user for confirmation before calling this tool.',
     {
       containerName: z.string().describe('Name of the Docker container to stop')
     },
+    { destructiveHint: true },
     async ({ containerName }) => {
       try {
         await execAsync(`docker stop ${containerName}`)
@@ -131,10 +133,11 @@ export function registerDockerTools (server, apiClient) {
 
   server.tool(
     'docker_restart_container',
-    'Restart a Docker container by name',
+    '[DESTRUCTIVE] Restart a Docker container by name. Ask the user for confirmation before calling this tool.',
     {
       containerName: z.string().describe('Name of the Docker container to restart')
     },
+    { destructiveHint: true },
     async ({ containerName }) => {
       try {
         await execAsync(`docker restart ${containerName}`)
@@ -153,6 +156,7 @@ export function registerDockerTools (server, apiClient) {
       containerName: z.string().describe('Name of the Docker container'),
       lines: z.number().optional().describe('Number of recent log lines to retrieve (default 100)')
     },
+    { readOnlyHint: true },
     async ({ containerName, lines = 100 }) => {
       try {
         const { stdout, stderr } = await execAsync(`docker logs --tail ${lines} ${containerName} 2>&1`)

package/src/mcp/tools/firestore.js

@@ -5,6 +5,7 @@ export function registerFirestoreTools (server, apiClient) {
     'firestore_list_projects',
     'List configured Firestore emulator projects',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/firestore/projects/list')
@@ -21,6 +22,7 @@ export function registerFirestoreTools (server, apiClient) {
     {
       projectId: z.string().optional().describe('Firestore project ID')
     },
+    { readOnlyHint: true },
     async ({ projectId }) => {
       try {
         const data = await apiClient.post('/v1/firestore/collections/list', { projectId })
@@ -39,6 +41,7 @@ export function registerFirestoreTools (server, apiClient) {
       collectionPath: z.string().describe('Collection path'),
       page: z.object({ limit: z.number().optional(), offset: z.number().optional() }).optional().describe('Pagination options with limit and offset')
     },
+    { readOnlyHint: true },
     async ({ projectId, collectionPath, page }) => {
       try {
         const data = await apiClient.post('/v1/firestore/documents/list', { projectId, collectionPath, page })
@@ -57,6 +60,7 @@ export function registerFirestoreTools (server, apiClient) {
       collectionPath: z.string().describe('Collection path'),
       documentId: z.string().describe('Document ID')
     },
+    { readOnlyHint: true },
     async ({ projectId, collectionPath, documentId }) => {
       try {
         const data = await apiClient.post('/v1/firestore/documents/get', { projectId, collectionPath, documentId })
@@ -107,12 +111,13 @@ export function registerFirestoreTools (server, apiClient) {
 
   server.tool(
     'firestore_delete_document',
-    'Delete a Firestore document',
+    '[DESTRUCTIVE] Delete a Firestore document permanently. Ask the user for confirmation before calling this tool.',
     {
       projectId: z.string().optional().describe('Firestore project ID'),
       collectionPath: z.string().describe('Collection path'),
       documentId: z.string().describe('Document ID')
     },
+    { destructiveHint: true },
     async ({ projectId, collectionPath, documentId }) => {
       try {
         const data = await apiClient.post('/v1/firestore/documents/delete', { projectId, collectionPath, documentId })
@@ -123,6 +128,46 @@ export function registerFirestoreTools (server, apiClient) {
     }
   )
 
+  server.tool(
+    'firestore_set_document',
+    'Set (create or replace) a Firestore document by ID',
+    {
+      projectId: z.string().optional().describe('Firestore project ID'),
+      collectionPath: z.string().describe('Collection path'),
+      documentId: z.string().describe('Document ID'),
+      fields: z.record(z.any()).describe('Document fields in Firestore format')
+    },
+    async ({ projectId, collectionPath, documentId, fields }) => {
+      try {
+        const data = await apiClient.post('/v1/firestore/documents/set', { projectId, collectionPath, documentId, fields })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
+  server.tool(
+    'firestore_create_batch',
+    'Create multiple Firestore documents in a collection at once',
+    {
+      projectId: z.string().optional().describe('Firestore project ID'),
+      collectionPath: z.string().describe('Collection path'),
+      documents: z.array(z.object({
+        documentId: z.string().optional().describe('Document ID (auto-generated if omitted)'),
+        fields: z.record(z.any()).describe('Document fields in Firestore format')
+      })).describe('Array of documents to create')
+    },
+    async ({ projectId, collectionPath, documents }) => {
+      try {
+        const data = await apiClient.post('/v1/firestore/documents/create-batch', { projectId, collectionPath, documents })
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+      } catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+      }
+    }
+  )
+
   server.tool(
     'firestore_query',
     'Execute a query against a Firestore collection with optional where/orderBy/limit',
@@ -133,6 +178,7 @@ export function registerFirestoreTools (server, apiClient) {
       orderBy: z.array(z.any()).optional().describe('Array of orderBy clauses'),
       limit: z.number().optional().describe('Maximum number of results')
     },
+    { readOnlyHint: true },
     async ({ projectId, collectionPath, where, orderBy, limit }) => {
       try {
         const data = await apiClient.post('/v1/firestore/query/execute', { projectId, collectionPath, where, orderBy, limit })
@@ -145,11 +191,12 @@ export function registerFirestoreTools (server, apiClient) {
 
   server.tool(
     'firestore_clear_collection',
-    'Delete all documents in a Firestore collection',
+    '[DESTRUCTIVE] Delete ALL documents in a Firestore collection. This cannot be undone. Ask the user for confirmation before calling this tool.',
     {
       projectId: z.string().optional().describe('Firestore project ID'),
       collectionPath: z.string().describe('Collection path')
     },
+    { destructiveHint: true },
     async ({ projectId, collectionPath }) => {
       try {
         const data = await apiClient.post('/v1/firestore/collection/clear', { projectId, collectionPath })

package/src/mcp/tools/functions.js

@@ -45,6 +45,7 @@ export function registerFunctionsTools (server, apiClient) {
       limit: z.number().optional().describe('Maximum number of results'),
       offset: z.number().optional().describe('Offset for pagination')
     },
+    { readOnlyHint: true },
     async ({ triggerType, status, limit, offset }) => {
       try {
         const body = {}
@@ -69,6 +70,7 @@ export function registerFunctionsTools (server, apiClient) {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name')
     },
+    { readOnlyHint: true },
     async ({ id, name }) => {
       try {
         const body = {}
@@ -118,11 +120,12 @@ export function registerFunctionsTools (server, apiClient) {
 
   server.tool(
     'functions_delete',
-    'Delete a Cloud Function from the dev-tools emulator',
+    '[DESTRUCTIVE] Delete a Cloud Function from the dev-tools emulator. Ask the user for confirmation before calling this tool.',
     {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name')
     },
+    { destructiveHint: true },
     async ({ id, name }) => {
       try {
         const body = {}
@@ -158,11 +161,12 @@ export function registerFunctionsTools (server, apiClient) {
 
   server.tool(
     'functions_stop',
-    'Stop a running Cloud Function',
+    '[DESTRUCTIVE] Stop a running Cloud Function. Ask the user for confirmation before calling this tool.',
     {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name')
     },
+    { destructiveHint: true },
     async ({ id, name }) => {
       try {
         const body = {}
@@ -178,11 +182,12 @@ export function registerFunctionsTools (server, apiClient) {
 
   server.tool(
     'functions_restart',
-    'Restart a Cloud Function (stop then start)',
+    '[DESTRUCTIVE] Restart a Cloud Function (stop then start). Ask the user for confirmation before calling this tool.',
     {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name')
     },
+    { destructiveHint: true },
     async ({ id, name }) => {
       try {
         const body = {}
@@ -228,6 +233,7 @@ export function registerFunctionsTools (server, apiClient) {
       limit: z.number().optional().describe('Maximum number of results (default: 50)'),
       offset: z.number().optional().describe('Offset for pagination')
     },
+    { readOnlyHint: true },
     async ({ functionId, functionName, triggerType, limit, offset }) => {
       try {
         const body = {}
@@ -248,6 +254,7 @@ export function registerFunctionsTools (server, apiClient) {
     'functions_stats',
     'Get aggregate statistics for Cloud Functions (counts by trigger type, status, invocations)',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/functions/stats')
@@ -264,6 +271,7 @@ export function registerFunctionsTools (server, apiClient) {
     {
       name: z.string().describe('Function name')
     },
+    { readOnlyHint: true },
     async ({ name }) => {
       try {
         const data = await apiClient.post('/v1/functions/dependencies/read', { name })
@@ -301,6 +309,7 @@ export function registerFunctionsTools (server, apiClient) {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name')
     },
+    { readOnlyHint: true },
     async ({ id, name }) => {
       try {
         const body = {}
@@ -322,6 +331,7 @@ export function registerFunctionsTools (server, apiClient) {
       name: z.string().optional().describe('Function name'),
       filePath: z.string().describe('Relative file path within the function source directory')
     },
+    { readOnlyHint: true },
     async ({ id, name, filePath }) => {
       try {
         const body = { filePath }
@@ -359,12 +369,13 @@ export function registerFunctionsTools (server, apiClient) {
 
   server.tool(
     'functions_files_delete',
-    'Delete a file from a Cloud Function source directory',
+    '[DESTRUCTIVE] Delete a file from a Cloud Function source directory. Ask the user for confirmation before calling this tool.',
     {
       id: z.string().optional().describe('Function ID'),
       name: z.string().optional().describe('Function name'),
       filePath: z.string().describe('Relative file path within the function source directory')
     },
+    { destructiveHint: true },
     async ({ id, name, filePath }) => {
       try {
         const body = { filePath }

package/src/mcp/tools/httpTraffic.js

@@ -9,6 +9,7 @@ export function registerHttpTrafficTools (server, apiClient) {
       limit: z.number().optional().describe('Maximum number of records to return'),
       offset: z.number().optional().describe('Number of records to skip for pagination')
     },
+    { readOnlyHint: true },
     async ({ filter, limit, offset }) => {
       try {
         const body = {}
@@ -29,6 +30,7 @@ export function registerHttpTrafficTools (server, apiClient) {
     {
       id: z.string().describe('ID of the HTTP traffic entry to retrieve')
     },
+    { readOnlyHint: true },
     async ({ id }) => {
       try {
         const data = await apiClient.post('/v1/http-traffic/details', { id })
@@ -46,6 +48,7 @@ export function registerHttpTrafficTools (server, apiClient) {
       filter: z.record(z.any()).describe('Required filter criteria (method, targetHost, sourceService, statusCode, traceId, pathContains)'),
       timeout: z.number().optional().describe('Timeout in ms (default: 5000, max: 30000)')
     },
+    { readOnlyHint: true },
     async ({ filter, timeout }) => {
       try {
         const body = { filter }
@@ -60,8 +63,9 @@ export function registerHttpTrafficTools (server, apiClient) {
 
   server.tool(
     'http_traffic_clear',
-    'Clear all recorded HTTP traffic',
+    '[DESTRUCTIVE] Clear all recorded HTTP traffic. Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/http-traffic/clear')
@@ -76,6 +80,7 @@ export function registerHttpTrafficTools (server, apiClient) {
     'http_traffic_stats',
     'Get HTTP traffic statistics grouped by host, method, and error rates',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/http-traffic/stats')

package/src/mcp/tools/logging.js

@@ -5,6 +5,7 @@ export function registerLoggingTools (server, apiClient) {
     'logging_list_services',
     'List all services that have sent log entries to the dev-tools logging emulator',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/logging/services/list')
@@ -29,6 +30,7 @@ export function registerLoggingTools (server, apiClient) {
       limit: z.number().optional().describe('Max entries to return (default: 100, max: 1000)'),
       offset: z.number().optional().describe('Skip this many entries for pagination (default: 0)')
     },
+    { readOnlyHint: true },
     async ({ serviceName, severity, textContains, traceId, sinceTimestamp, untilTimestamp, compact, limit, offset }) => {
       try {
         const filter = {}
@@ -61,6 +63,7 @@ export function registerLoggingTools (server, apiClient) {
     {
       ids: z.array(z.string()).describe('Array of log entry IDs to retrieve (from the _id field in compact list results)')
     },
+    { readOnlyHint: true },
     async ({ ids }) => {
       try {
         const data = await apiClient.post('/v1/logging/entries/get', { ids })
@@ -73,8 +76,9 @@ export function registerLoggingTools (server, apiClient) {
 
   server.tool(
     'logging_clear',
-    'Clear all log entries from the dev-tools logging emulator',
+    '[DESTRUCTIVE] Clear all log entries from the dev-tools logging emulator. Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/logging/entries/clear')
@@ -91,6 +95,7 @@ export function registerLoggingTools (server, apiClient) {
     {
       filter: z.record(z.any()).optional().describe('Optional filter criteria to scope the export')
     },
+    { readOnlyHint: true },
     async ({ filter }) => {
       try {
         const body = {}
@@ -109,6 +114,7 @@ export function registerLoggingTools (server, apiClient) {
     {
       traceId: z.string().describe('The trace ID to look up')
     },
+    { readOnlyHint: true },
     async ({ traceId }) => {
       try {
         const data = await apiClient.post(`/v1/logging/trace/${traceId}`)
@@ -126,6 +132,7 @@ export function registerLoggingTools (server, apiClient) {
       filter: z.record(z.any()).describe('Filter criteria the log entry must match'),
       timeout: z.number().optional().describe('Maximum seconds to wait before timing out')
     },
+    { readOnlyHint: true },
     async ({ filter, timeout }) => {
       try {
         const body = { filter }
@@ -145,6 +152,7 @@ export function registerLoggingTools (server, apiClient) {
       traceId: z.string().optional().describe('Optional trace ID to scope the assertion to'),
       sinceTimestamp: z.string().optional().describe('Optional ISO timestamp — only check logs after this time')
     },
+    { readOnlyHint: true },
     async ({ traceId, sinceTimestamp }) => {
       try {
         const body = {}
@@ -162,6 +170,7 @@ export function registerLoggingTools (server, apiClient) {
     'logging_get_queue_stats',
     'Get Bull queue statistics including job counts and health status for the blackbox logs consumer',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/logging/queue-stats', {})

package/src/mcp/tools/mqtt.js

@@ -5,6 +5,7 @@ export function registerMqttTools (server, apiClient) {
     'mqtt_list_clients',
     'List all connected MQTT clients with their connection info',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/mqtt/clients/list')
@@ -22,6 +23,7 @@ export function registerMqttTools (server, apiClient) {
       filter: z.record(z.any()).optional().describe('Optional filter criteria for MQTT messages'),
       page: z.object({ limit: z.number().optional(), offset: z.number().optional() }).optional().describe('Optional pagination with limit and offset')
     },
+    { readOnlyHint: true },
     async ({ filter, page }) => {
       try {
         const body = {}

package/src/mcp/tools/postgres.js

@@ -5,6 +5,7 @@ export function registerPostgresTools (server, apiClient) {
     'postgres_test_connection',
     'Test the PostgreSQL database connection',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/postgres/connection/test')
@@ -19,6 +20,7 @@ export function registerPostgresTools (server, apiClient) {
     'postgres_list_databases',
     'List all PostgreSQL databases',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/postgres/databases/list')
@@ -33,6 +35,7 @@ export function registerPostgresTools (server, apiClient) {
     'postgres_list_schemas',
     'List all schemas in the current database',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/postgres/schemas/list')
@@ -49,6 +52,7 @@ export function registerPostgresTools (server, apiClient) {
     {
       schema: z.string().optional().describe('Schema name (defaults to public)')
     },
+    { readOnlyHint: true },
     async ({ schema }) => {
       try {
         const data = await apiClient.post('/v1/postgres/tables/list', { schema })
@@ -66,6 +70,7 @@ export function registerPostgresTools (server, apiClient) {
       table: z.string().describe('Table name'),
       schema: z.string().optional().describe('Schema name (defaults to public)')
     },
+    { readOnlyHint: true },
     async ({ table, schema }) => {
       try {
         const data = await apiClient.post('/v1/postgres/columns/list', { table, schema })
@@ -83,6 +88,7 @@ export function registerPostgresTools (server, apiClient) {
       table: z.string().describe('Table name'),
       page: z.object({ limit: z.number().optional(), offset: z.number().optional() }).optional().describe('Pagination options with limit and offset')
     },
+    { readOnlyHint: true },
     async ({ table, page }) => {
       try {
         const data = await apiClient.post('/v1/postgres/rows/list', { table, page })
@@ -95,11 +101,12 @@ export function registerPostgresTools (server, apiClient) {
 
   server.tool(
     'postgres_execute_query',
-    'Execute a raw SQL query against PostgreSQL',
+    '[DESTRUCTIVE] Execute a raw SQL query against PostgreSQL. Ask the user for confirmation before calling this tool.',
     {
       query: z.string().describe('SQL query to execute'),
       params: z.array(z.any()).optional().describe('Query parameters for parameterized queries')
     },
+    { destructiveHint: true },
     async ({ query, params }) => {
       try {
         const data = await apiClient.post('/v1/postgres/query/execute', { query, params })
@@ -118,6 +125,7 @@ export function registerPostgresTools (server, apiClient) {
       condition: z.record(z.any()).optional().describe('Condition to match against query results'),
       timeout: z.number().optional().describe('Timeout in milliseconds')
     },
+    { readOnlyHint: true },
     async ({ query, condition, timeout }) => {
       try {
         const data = await apiClient.post('/v1/postgres/rows/wait-for', { query, condition, timeout })

package/src/mcp/tools/pubsub.js

@@ -5,6 +5,7 @@ export function registerPubsubTools (server, apiClient) {
     'pubsub_list_topics',
     'List all Pub/Sub topics in the dev-tools emulator',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/pubsub/topics/list')
@@ -33,10 +34,11 @@ export function registerPubsubTools (server, apiClient) {
 
   server.tool(
     'pubsub_delete_topic',
-    'Delete a Pub/Sub topic from the dev-tools emulator',
+    '[DESTRUCTIVE] Delete a Pub/Sub topic from the dev-tools emulator. Ask the user for confirmation before calling this tool.',
     {
       topicName: z.string().describe('Name of the topic to delete')
     },
+    { destructiveHint: true },
     async ({ topicName }) => {
       try {
         const data = await apiClient.post('/v1/pubsub/topics/delete', { topicName })
@@ -54,6 +56,7 @@ export function registerPubsubTools (server, apiClient) {
       query: z.string().describe('Search query to match against topic names'),
       limit: z.number().optional().describe('Maximum number of suggestions to return')
     },
+    { readOnlyHint: true },
     async ({ query, limit }) => {
       try {
         const body = { query }
@@ -70,6 +73,7 @@ export function registerPubsubTools (server, apiClient) {
     'pubsub_list_subscriptions',
     'List all Pub/Sub subscriptions in the dev-tools emulator',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/pubsub/subscriptions/list')
@@ -99,10 +103,11 @@ export function registerPubsubTools (server, apiClient) {
 
   server.tool(
     'pubsub_delete_subscription',
-    'Delete a Pub/Sub subscription from the dev-tools emulator',
+    '[DESTRUCTIVE] Delete a Pub/Sub subscription from the dev-tools emulator. Ask the user for confirmation before calling this tool.',
     {
       subscriptionName: z.string().describe('Name of the subscription to delete')
     },
+    { destructiveHint: true },
     async ({ subscriptionName }) => {
       try {
         const data = await apiClient.post('/v1/pubsub/subscriptions/delete', { subscriptionName })
@@ -140,6 +145,7 @@ export function registerPubsubTools (server, apiClient) {
       subscriptionName: z.string().describe('Subscription to pull messages from'),
       maxMessages: z.number().optional().describe('Maximum number of messages to pull')
     },
+    { readOnlyHint: true },
     async ({ subscriptionName, maxMessages }) => {
       try {
         const body = { subscriptionName }
@@ -160,6 +166,7 @@ export function registerPubsubTools (server, apiClient) {
       searchIn: z.array(z.string()).optional().describe('Optional list of fields to search in (e.g. ["data", "attributes", "topic"])'),
       filter: z.record(z.any()).optional().describe('Optional additional filter criteria')
     },
+    { readOnlyHint: true },
     async ({ query, searchIn, filter }) => {
       try {
         const body = { query }
@@ -180,6 +187,7 @@ export function registerPubsubTools (server, apiClient) {
       filter: z.record(z.any()).optional().describe('Optional filter criteria (e.g. by topic, time range)'),
       page: z.object({ limit: z.number().optional(), offset: z.number().optional() }).optional().describe('Optional pagination with limit and offset')
     },
+    { readOnlyHint: true },
     async ({ filter, page }) => {
       try {
         const body = {}
@@ -195,11 +203,12 @@ export function registerPubsubTools (server, apiClient) {
 
   server.tool(
     'pubsub_clear_history',
-    'Clear Pub/Sub message history. Optionally keep a number of recent messages or clear only a specific topic.',
+    '[DESTRUCTIVE] Clear Pub/Sub message history. Optionally keep a number of recent messages or clear only a specific topic. Ask the user for confirmation before calling this tool.',
     {
       keepCount: z.number().optional().describe('Number of recent messages to keep'),
       topic: z.string().optional().describe('Only clear history for this topic')
     },
+    { destructiveHint: true },
     async ({ keepCount, topic }) => {
       try {
         const body = {}
@@ -217,6 +226,7 @@ export function registerPubsubTools (server, apiClient) {
     'pubsub_history_stats',
     'Get statistics about Pub/Sub message history including counts per topic and total volume',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/pubsub/history/stats')
@@ -234,6 +244,7 @@ export function registerPubsubTools (server, apiClient) {
       filter: z.record(z.any()).describe('Filter criteria with jsonPath and/or predicate to match incoming messages'),
       timeout: z.number().optional().describe('Maximum seconds to wait before timing out')
     },
+    { readOnlyHint: true },
     async ({ filter, timeout }) => {
       try {
         const body = { filter }
@@ -252,6 +263,7 @@ export function registerPubsubTools (server, apiClient) {
     {
       filter: z.record(z.any()).describe('Filter criteria: { topic (string), since (ISO timestamp), dataContains (string), attributesMatch (object) }')
     },
+    { readOnlyHint: true },
     async ({ filter }) => {
       try {
         const data = await apiClient.post('/v1/pubsub/messages/assert-published', { filter })
@@ -285,6 +297,7 @@ export function registerPubsubTools (server, apiClient) {
     {
       projectName: z.string().optional().describe('Optional project name to filter by')
     },
+    { readOnlyHint: true },
     async ({ projectName }) => {
       try {
         const body = {}
@@ -299,11 +312,12 @@ export function registerPubsubTools (server, apiClient) {
 
   server.tool(
     'pubsub_registry_unregister',
-    'Unregister topics for a project from the persistent Pub/Sub registry',
+    '[DESTRUCTIVE] Unregister topics for a project from the persistent Pub/Sub registry. Ask the user for confirmation before calling this tool.',
     {
       projectName: z.string().describe('Project name to unregister topics from'),
       topicNames: z.array(z.string()).describe('Array of topic name strings to unregister')
     },
+    { destructiveHint: true },
     async ({ projectName, topicNames }) => {
       try {
         const data = await apiClient.post('/v1/pubsub/registry/unregister', { projectName, topicNames })

package/src/mcp/tools/redis.js

@@ -5,6 +5,7 @@ export function registerRedisTools (server, apiClient) {
     'redis_test_connection',
     'Test the Redis connection',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/redis/connection/test')
@@ -19,6 +20,7 @@ export function registerRedisTools (server, apiClient) {
     'redis_info',
     'Get Redis server info including memory usage and db size',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/redis/info')
@@ -37,6 +39,7 @@ export function registerRedisTools (server, apiClient) {
       cursor: z.string().optional().describe('Cursor for pagination'),
       count: z.number().optional().describe('Approximate number of keys to return per scan')
     },
+    { readOnlyHint: true },
     async ({ pattern, cursor, count }) => {
       try {
         const data = await apiClient.post('/v1/redis/keys/scan', { pattern, cursor, count })
@@ -53,6 +56,7 @@ export function registerRedisTools (server, apiClient) {
     {
       key: z.string().describe('Redis key name')
     },
+    { readOnlyHint: true },
     async ({ key }) => {
       try {
         const data = await apiClient.post('/v1/redis/keys/get', { key })
@@ -69,6 +73,7 @@ export function registerRedisTools (server, apiClient) {
     {
       key: z.string().describe('Redis key name')
     },
+    { readOnlyHint: true },
     async ({ key }) => {
       try {
         const data = await apiClient.post('/v1/redis/keys/ttl', { key })
@@ -81,10 +86,11 @@ export function registerRedisTools (server, apiClient) {
 
   server.tool(
     'redis_delete_key',
-    'Delete a specific Redis key',
+    '[DESTRUCTIVE] Delete a specific Redis key. Ask the user for confirmation before calling this tool.',
     {
       key: z.string().describe('Redis key name')
     },
+    { destructiveHint: true },
     async ({ key }) => {
       try {
         const data = await apiClient.post('/v1/redis/keys/delete', { key })
@@ -115,8 +121,9 @@ export function registerRedisTools (server, apiClient) {
 
   server.tool(
     'redis_delete_all',
-    'Delete all Redis keys (FLUSHDB)',
+    '[DESTRUCTIVE] Delete all Redis keys (FLUSHDB). Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/redis/keys/delete-all')
@@ -134,6 +141,7 @@ export function registerRedisTools (server, apiClient) {
       condition: z.record(z.any()).describe('Condition to match against the key value'),
       timeout: z.number().optional().describe('Timeout in milliseconds')
     },
+    { readOnlyHint: true },
     async ({ condition, timeout }) => {
       try {
         const data = await apiClient.post('/v1/redis/keys/wait-for', { condition, timeout })

package/src/mcp/tools/services.js

@@ -3,6 +3,7 @@ export function registerServicesTools (server, apiClient) {
     'services_list',
     'List all dev-tools platform services and their status',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/services/list')
@@ -17,6 +18,7 @@ export function registerServicesTools (server, apiClient) {
     'services_status',
     'Get detailed status of all services',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/services/status')
@@ -29,8 +31,9 @@ export function registerServicesTools (server, apiClient) {
 
   server.tool(
     'services_restart',
-    'Restart dev-tools services',
+    '[DESTRUCTIVE] Restart dev-tools services. Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/services/restart')
@@ -57,8 +60,9 @@ export function registerServicesTools (server, apiClient) {
 
   server.tool(
     'scheduler_stop',
-    'Stop the scheduler tick',
+    '[DESTRUCTIVE] Stop the scheduler tick. Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/scheduler/tick/stop')
@@ -73,6 +77,7 @@ export function registerServicesTools (server, apiClient) {
     'scheduler_status',
     'Get scheduler tick status (running/stopped, interval)',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/scheduler/tick/status')
@@ -113,8 +118,9 @@ export function registerServicesTools (server, apiClient) {
 
   server.tool(
     'gateway_stop',
-    'Stop the app gateway service',
+    '[DESTRUCTIVE] Stop the app gateway service. Ask the user for confirmation before calling this tool.',
     {},
+    { destructiveHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/gateway/stop')
@@ -129,6 +135,7 @@ export function registerServicesTools (server, apiClient) {
     'gateway_status',
     'Get the app gateway status',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/gateway/status')
@@ -157,6 +164,7 @@ export function registerServicesTools (server, apiClient) {
     'gateway_health_check',
     'Run health checks on all gateway endpoints',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/gateway/healthCheck')

package/src/mcp/tools/snapshots.js

@@ -21,11 +21,12 @@ export function registerSnapshotTools (server, apiClient) {
 
   server.tool(
     'snapshots_restore',
-    'Restore development environment from a snapshot. This will stop microservices, restore data, and restart them.',
+    '[DESTRUCTIVE] Restore development environment from a snapshot. This will stop microservices, restore data, and restart them. Ask the user for confirmation before calling this tool.',
     {
       snapshotId: z.string().describe('Snapshot ID to restore from (e.g., "e2e_2026-02-26_10-30-45")'),
       restartServices: z.boolean().optional().describe('Whether to restart microservices after restore (default: true)')
     },
+    { destructiveHint: true },
     async ({ snapshotId, restartServices }) => {
       try {
         const body = { snapshotId }
@@ -42,6 +43,7 @@ export function registerSnapshotTools (server, apiClient) {
     'snapshots_list',
     'List all available snapshots with their metadata',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/snapshots/list', {})
@@ -58,6 +60,7 @@ export function registerSnapshotTools (server, apiClient) {
     {
       snapshotId: z.string().describe('Snapshot ID to get details for')
     },
+    { readOnlyHint: true },
     async ({ snapshotId }) => {
       try {
         const data = await apiClient.post('/v1/snapshots/details', { snapshotId })
@@ -70,10 +73,11 @@ export function registerSnapshotTools (server, apiClient) {
 
   server.tool(
     'snapshots_delete',
-    'Delete a snapshot and its files',
+    '[DESTRUCTIVE] Delete a snapshot and its files. Ask the user for confirmation before calling this tool.',
     {
       snapshotId: z.string().optional().describe('Snapshot ID to delete. If omitted, deletes all snapshots.')
     },
+    { destructiveHint: true },
     async ({ snapshotId }) => {
       try {
         const body = {}

package/src/mcp/tools/webhooks.js

@@ -27,6 +27,7 @@ export function registerWebhooksTools (server, apiClient) {
     'webhooks_list',
     'List all registered webhooks',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/webhooks/list')
@@ -39,10 +40,11 @@ export function registerWebhooksTools (server, apiClient) {
 
   server.tool(
     'webhooks_remove',
-    'Remove a registered webhook by its prefix',
+    '[DESTRUCTIVE] Remove a registered webhook by its prefix. Ask the user for confirmation before calling this tool.',
     {
       prefix: z.string().describe('URL prefix of the webhook to remove')
     },
+    { destructiveHint: true },
     async ({ prefix }) => {
       try {
         const data = await apiClient.post('/v1/webhooks/remove', { prefix })
@@ -73,6 +75,7 @@ export function registerWebhooksTools (server, apiClient) {
     'webhooks_tunnel_status',
     'Get ngrok tunnel status (connected/disconnected, public URL)',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/webhooks/tunnel/status')
@@ -87,6 +90,7 @@ export function registerWebhooksTools (server, apiClient) {
     'webhooks_settings_get',
     'Get current webhook/ngrok settings',
     {},
+    { readOnlyHint: true },
     async () => {
       try {
         const data = await apiClient.post('/v1/webhooks/settings/get')