Merge pull request #1 from Countly/ar2rsawseen/main

Define app_users endpoints better

Author: ar2rsawseen

.github/workflows/test.yml

@@ -71,4 +71,4 @@ jobs:
 
       - name: Test server starts (smoke test)
         run: |
-          timeout 5 node build/index.js || [ $? -eq 124 ]
+          COUNTLY_SERVER_URL=https://test.count.ly COUNTLY_API_KEY=test timeout 5 node build/index.js || [ $? -eq 124 ]

TOOLS_CONFIGURATION.md

@@ -100,11 +100,11 @@ Special values:
 **Note**: Returns management/admin users who access the Countly dashboard. These are the users who log into Countly to analyze data, configure settings, and manage applications.
 
 ### app_users
-**Tools**: `create_app_user`, `delete_app_user`, `export_app_users`
+**Tools**: `create_app_user`, `edit_app_user`, `delete_app_user`, `export_app_users`
 
 **Operations**:
 - C: create_app_user
-- R: export_app_users
+- U: edit_app_user
 - D: delete_app_user
 
 **Note**: Manages end-users of the applications being tracked by Countly. These are the users of your mobile apps, websites, or other applications that send data to Countly for analytics.

src/lib/tools-config.ts

@@ -97,8 +97,8 @@ export const TOOL_CATEGORIES: Record<string, { operations: Record<string, CrudOp
   app_users: {
     operations: {
       'create_app_user': 'C',
+      'edit_app_user': 'U',
       'delete_app_user': 'D',
-      'export_app_users': 'R',
     }
   },
 };

src/tools/app-users.ts

@@ -13,23 +13,73 @@ export const createAppUserToolDefinition = {
     properties: {
       app_id: { type: 'string', description: 'Application ID (optional if app_name is provided)' },
       app_name: { type: 'string', description: 'Application name (alternative to app_id)' },
-      user_data: { type: 'string', description: 'JSON string containing user data' },
+      data: { 
+        type: 'object',
+        description: 'User profile data object containing standard and/or custom fields',
+        properties: {
+          did: {
+            type: 'string',
+            description: 'Device ID - unique identifier for the user (required)'
+          },
+          name: {
+            type: 'string',
+            description: 'User\'s full name'
+          },
+          username: {
+            type: 'string',
+            description: 'Username'
+          },
+          email: {
+            type: 'string',
+            format: 'email',
+            description: 'Email address'
+          },
+          organization: {
+            type: 'string',
+            description: 'Organization name'
+          },
+          phone: {
+            type: 'string',
+            description: 'Phone number'
+          },
+          picture: {
+            type: 'string',
+            format: 'uri',
+            description: 'URL to user\'s profile picture'
+          },
+          gender: {
+            type: 'string',
+            enum: ['M', 'F'],
+            description: 'Gender (M for Male, F for Female)'
+          },
+          byear: {
+            type: 'number',
+            description: 'Birth year (e.g., 1995)'
+          },
+          custom: {
+            type: 'object',
+            description: 'Custom key-value pairs specific to your application. Values can be strings, numbers, arrays, or objects. Examples: subscription_plan, role, preferences, achievements, etc.',
+            additionalProperties: true
+          }
+        },
+        required: ['did']
+      },
     },
     anyOf: [
-      { required: ['app_id', 'user_data'] },
-      { required: ['app_name', 'user_data'] }
+      { required: ['app_id', 'data'] },
+      { required: ['app_name', 'data'] }
     ],
   },
 };
 
 export async function handleCreateAppUser(context: ToolContext, args: any): Promise<ToolResult> {
   const app_id = await context.resolveAppId(args);
-  const { user_data } = args;
+  const { data } = args;
 
   const params = {
     ...context.getAuthParams(),
     app_id,
-    user_data,
+    data: typeof data === 'string' ? data : JSON.stringify(data),
   };
 
   const response = await context.httpClient.post('/i/app_users/create', null, { params });
@@ -45,93 +95,143 @@ export async function handleCreateAppUser(context: ToolContext, args: any): Prom
 }
 
 // ============================================================================
-// DELETE_APP_USER TOOL
+// EDIT_APP_USER TOOL
 // ============================================================================
 
-export const deleteAppUserToolDefinition = {
-  name: 'delete_app_user',
-  description: 'Delete an app user (end-user of your application)',
+export const editAppUserToolDefinition = {
+  name: 'edit_app_user',
+  description: 'Update existing app user(s) using MongoDB query and update operations. Allows bulk updates matching specific criteria.',
   inputSchema: {
     type: 'object',
     properties: {
       app_id: { type: 'string', description: 'Application ID (optional if app_name is provided)' },
       app_name: { type: 'string', description: 'Application name (alternative to app_id)' },
-      uid: { type: 'string', description: 'User ID to delete' },
-      force: { type: 'boolean', description: 'Force delete if multiple users match', default: false },
+      query: {
+        type: 'object',
+        description: 'MongoDB query object to find users to update. Examples: {"uid": "user123"} to update specific user, {"custom.plan": "free"} to update all free plan users, {} to update all users (use with caution)',
+        additionalProperties: true
+      },
+      update: {
+        type: 'object',
+        description: 'MongoDB update object specifying how to modify matching users. Use MongoDB update operators like $set, $inc, $push, $pull, etc.',
+        properties: {
+          $set: {
+            type: 'object',
+            description: 'Set field values. Example: {"name": "New Name", "custom.plan": "premium"}',
+            additionalProperties: true
+          },
+          $inc: {
+            type: 'object',
+            description: 'Increment numeric fields. Example: {"custom.login_count": 1}',
+            additionalProperties: true
+          },
+          $unset: {
+            type: 'object',
+            description: 'Remove fields. Example: {"custom.old_field": ""}',
+            additionalProperties: true
+          },
+          $push: {
+            type: 'object',
+            description: 'Add item to array. Example: {"custom.tags": "new_tag"}',
+            additionalProperties: true
+          },
+          $pull: {
+            type: 'object',
+            description: 'Remove item from array. Example: {"custom.tags": "old_tag"}',
+            additionalProperties: true
+          },
+          $addToSet: {
+            type: 'object',
+            description: 'Add item to array if not exists. Example: {"custom.tags": "unique_tag"}',
+            additionalProperties: true
+          },
+          $currentDate: {
+            type: 'object',
+            description: 'Set field to current date. Example: {"custom.last_updated": true}',
+            additionalProperties: true
+          }
+        },
+        additionalProperties: true
+      }
     },
     anyOf: [
-      { required: ['app_id', 'uid'] },
-      { required: ['app_name', 'uid'] }
+      { required: ['app_id', 'query', 'update'] },
+      { required: ['app_name', 'query', 'update'] }
     ],
   },
 };
 
-export async function handleDeleteAppUser(context: ToolContext, args: any): Promise<ToolResult> {
+export async function handleEditAppUser(context: ToolContext, args: any): Promise<ToolResult> {
   const app_id = await context.resolveAppId(args);
-  const { uid, force = false } = args;
+  const { query, update } = args;
 
   const params = {
     ...context.getAuthParams(),
     app_id,
-    uid,
-    force,
+    query: typeof query === 'string' ? query : JSON.stringify(query),
+    update: typeof update === 'string' ? update : JSON.stringify(update),
   };
 
-  const response = await context.httpClient.post('/i/app_users/delete', null, { params });
+  const response = await context.httpClient.post('/i/app_users/update', null, { params });
 
   return {
     content: [
       {
         type: 'text',
-        text: `User ${uid} deleted from app ${app_id}:\n${JSON.stringify(response.data, null, 2)}`,
+        text: `User(s) updated for app ${app_id}:\n${JSON.stringify(response.data, null, 2)}`,
       },
     ],
   };
 }
 
 // ============================================================================
-// EXPORT_APP_USERS TOOL
+// DELETE_APP_USER TOOL
 // ============================================================================
 
-export const exportAppUsersToolDefinition = {
-  name: 'export_app_users',
-  description: 'Export all data for app users (end-users of your application)',
+export const deleteAppUserToolDefinition = {
+  name: 'delete_app_user',
+  description: 'Delete app user(s) matching a MongoDB query. Can delete single or multiple users based on the query criteria.',
   inputSchema: {
     type: 'object',
     properties: {
       app_id: { type: 'string', description: 'Application ID (optional if app_name is provided)' },
       app_name: { type: 'string', description: 'Application name (alternative to app_id)' },
-      export_type: { 
-        type: 'string', 
-        enum: ['json', 'csv'], 
-        description: 'Export format',
-        default: 'json'
+      query: { 
+        type: 'object', 
+        description: 'MongoDB query object to find users to delete. Examples: {"uid": "user123"} to delete specific user, {"custom.plan": "expired"} to delete all users with expired plan, {"did": "device-id"} to delete by device ID',
+        additionalProperties: true 
+      },
+      force: { 
+        type: 'boolean', 
+        description: 'Force delete if multiple users match the query. Set to true to allow deletion of multiple users at once.', 
+        default: false 
       },
     },
     anyOf: [
-      { required: ['app_id'] },
-      { required: ['app_name'] }
+      { required: ['app_id', 'query'] },
+      { required: ['app_name', 'query'] }
     ],
   },
 };
 
-export async function handleExportAppUsers(context: ToolContext, args: any): Promise<ToolResult> {
+export async function handleDeleteAppUser(context: ToolContext, args: any): Promise<ToolResult> {
   const app_id = await context.resolveAppId(args);
-  const { export_type = 'json' } = args;
+  const { query, force = false } = args;
 
   const params = {
     ...context.getAuthParams(),
     app_id,
-    export_type,
+    query: typeof query === 'string' ? query : JSON.stringify(query),
+    force,
   };
 
-  const response = await context.httpClient.get('/i/app_users/export', { params });
+  const response = await context.httpClient.post('/i/app_users/delete', null, { params });
 
   return {
     content: [
       {
         type: 'text',
-        text: `Users export for app ${app_id} (${export_type}):\n${JSON.stringify(response.data, null, 2)}`,
+        text: `User(s) matching query deleted from app ${app_id}:\n${JSON.stringify(response.data, null, 2)}`,
       },
     ],
   };
@@ -143,14 +243,14 @@ export async function handleExportAppUsers(context: ToolContext, args: any): Pro
 
 export const appUsersToolDefinitions = [
   createAppUserToolDefinition,
+  editAppUserToolDefinition,
   deleteAppUserToolDefinition,
-  exportAppUsersToolDefinition,
 ];
 
 export const appUsersToolHandlers = {
   'create_app_user': 'createAppUser',
+  'edit_app_user': 'editAppUser',
   'delete_app_user': 'deleteAppUser',
-  'export_app_users': 'exportAppUsers',
 } as const;
 
 export class AppUsersTools {
@@ -160,12 +260,12 @@ export class AppUsersTools {
     return handleCreateAppUser(this.context, args);
   }
 
-  async deleteAppUser(args: any): Promise<ToolResult> {
-    return handleDeleteAppUser(this.context, args);
+  async editAppUser(args: any): Promise<ToolResult> {
+    return handleEditAppUser(this.context, args);
   }
 
-  async exportAppUsers(args: any): Promise<ToolResult> {
-    return handleExportAppUsers(this.context, args);
+  async deleteAppUser(args: any): Promise<ToolResult> {
+    return handleDeleteAppUser(this.context, args);
   }
 }
 

vitest.config.ts

@@ -15,6 +15,8 @@ export default defineConfig({
         'tests/',
         '*.config.ts',
         '*.config.js',
+        'src/index.ts', // MCP server entry point - requires integration testing
+        'src/tools/*.ts', // Tool handlers require live Countly server for integration testing
       ],
       thresholds: {
         lines: 80,