@north7/entraaware 0.0.4 → 0.0.6

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 North7 (EntraAware)
+Portions copyright (c) 2025 Merill Fernando
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -1,27 +1,29 @@
 # EntraAware MCP Server
 
-A simple, lightweight Model Context Protocol (MCP) server for querying Microsoft Entra (Azure AD) data.
+A lightweight Model Context Protocol (MCP) server for querying Microsoft Entra (Azure AD) and Azure Resource Management data.
 
 ## What is EntraAware?
 
-EntraAware is an MCP Server allows AI assistants to directly access your Microsoft Entra (Azure AD) tenant data through the Microsoft Graph API. With EntraAware, you can ask natural language questions about your Entra environment.
+EntraAware is an MCP Server that allows AI assistants to directly access your Microsoft Entra (Azure AD) tenant data through the Microsoft Graph API and Azure Resource Management API. With EntraAware, you can ask natural language questions or make structured API calls to your Microsoft cloud environments.
+
+This project is inspired by and builds upon the [Lokka-Microsoft](https://github.com/lokkamcp/microsoft) MCP server (MIT license).
 
 ## Setup
 
 ### Prerequisites
 
 - Microsoft Entra (Azure AD) tenant
-- Application registration with appropriate Graph API permissions
+- Application registration with appropriate Graph API permissions and Azure Resource Management permissions
 - Node.js 18 or higher
 
 ### Installation
 
 ```bash
 # Install globally
-npm install -g @uniquk/entraaware
+npm install -g @north7/entraaware
 
 # Or use with npx (no installation needed)
-npx @uniquk/entraaware
+npx @north7/entraaware
 ```
 
 ### Configuration
@@ -56,37 +58,87 @@ Replace the environment variables with your own:
 
 ## Usage
 
-Once configured, you can use EntraAware through VS Code by typing:
+Once configured, you can use EntraAware through a compatible MCP client (like VS Code with the MCP extension).
 
-```
-ask EntraAware>
-```
+### Available Tools
 
-The EntraAware MCP tool provides a single function that automatically detects the right Graph API endpoint based on keywords in your question:
+EntraAware provides three MCP tools:
 
-```json
+#### 1. askEntra
+
+Direct access to Microsoft Graph API for accurate Entra (Azure AD) data.
+
+```javascript
+// Example usage
 {
-  "question": "Show me all conditional access policies"
+  "path": "/users", 
+  "method": "get",
+  "select": "displayName,userPrincipalName,id",
+  "top": 10
+}
+
+// Advanced filtering
+{
+  "path": "/users",
+  "method": "get",
+  "filter": "startsWith(displayName,'J')",
+  "consistencyLevel": "eventual"
 }
 ```
 
-### Example Queries
+#### 2. askAzure
+
+Direct access to Azure Resource Management API for managing Azure resources.
+
+```javascript
+// List subscriptions
+{
+  "path": "/subscriptions",
+  "method": "get"
+}
 
+// List all resource groups in a subscription
+{
+  "path": "/resourceGroups",
+  "method": "get",
+  "subscriptionId": "your-subscription-id",
+  "apiVersion": "2021-04-01"
+}
+
+// Use predefined operations
+{
+  "operation": "listResources",
+  "subscriptionId": "your-subscription-id"
+}
 ```
-// Get organization details
-Show me details about my organization
 
-// Get conditional access policies
-List all conditional access policies
+#### 3. Lokka-Microsoft (Compatibility Layer)
+
+A compatibility layer for the Lokka-Microsoft MCP server to ensure backward compatibility.
 
-// Get information about a specific user
-Find user john.doe@example.com
+```javascript
+// Query Graph API
+{
+  "apiType": "graph",
+  "path": "/users",
+  "method": "get"
+}
 
-// Get all groups
-Show me all groups
+// Query Azure API
+{
+  "apiType": "azure",
+  "path": "/subscriptions",
+  "method": "get",
+  "apiVersion": "2022-12-01"
+}
 ```
 
-## References
+## License
+
+MIT License - See LICENSE file for details.
+
+## Acknowledgements
 
+- This project is inspired by and builds upon the [Lokka-Microsoft](https://github.com/merill/lokka) MCP server.
 - [Microsoft Graph API Documentation](https://learn.microsoft.com/en-us/graph/api/overview)
-- [EntraAware npm package](https://www.npmjs.com/package/@uniquk/entraaware)
+- [Azure Resource Management API Documentation](https://learn.microsoft.com/en-us/rest/api/azure/)

package/build/index.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+/**
+ * EntraAware MCP Server
+ *
+ * Portions of this code are adapted from the Lokka-Microsoft MCP Server (MIT License)
+ * Original repository: https://github.com/merill/lokka
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -11,13 +17,14 @@ let azureCredential = null;
 // Create server instance
 const server = new McpServer({
     name: "EntraAware",
-    version: "0.0.3",
+    version: "0.0.6",
     capabilities: {
         resources: {},
         tools: {},
     },
 });
 // SHARED UTILITIES
+// The following credential handling utilities are adapted from Lokka-Microsoft
 function getCredentials() {
     const tenantId = process.env.TENANT_ID;
     const clientId = process.env.CLIENT_ID;
@@ -27,6 +34,52 @@ function getCredentials() {
     }
     return { tenantId, clientId, clientSecret };
 }
+// Helper to fetch the latest API version for a given resource provider and resource type
+async function getLatestApiVersion(providerNamespace, resourceType) {
+    try {
+        // Get Azure credential
+        const credential = getAzureCredential();
+        // Get access token
+        const tokenResponse = await credential.getToken("https://management.azure.com/.default");
+        if (!tokenResponse?.token)
+            throw new Error("Failed to acquire Azure access token");
+        // Prepare request options
+        const headers = {
+            'Authorization': `Bearer ${tokenResponse.token}`,
+            'Content-Type': 'application/json'
+        };
+        // Make request to list provider details
+        const url = `https://management.azure.com/providers/${providerNamespace}?api-version=2021-04-01`;
+        const response = await fetch(url, { method: 'GET', headers });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch API versions: ${response.status}`);
+        }
+        const providerData = await response.json();
+        // If resourceType is specified, find that specific type
+        if (resourceType) {
+            const resourceTypeInfo = providerData.resourceTypes.find((rt) => rt.resourceType.toLowerCase() === resourceType.toLowerCase());
+            if (resourceTypeInfo && resourceTypeInfo.apiVersions && resourceTypeInfo.apiVersions.length > 0) {
+                // Return the first (most recent) API version
+                return resourceTypeInfo.apiVersions[0];
+            }
+        }
+        else {
+            // Otherwise, just return a stable API version for the provider
+            // Providers typically have their most recent versions first
+            if (providerData.apiVersions && providerData.apiVersions.length > 0) {
+                return providerData.apiVersions[0];
+            }
+        }
+        // If we get here, we couldn't find a good API version
+        throw new Error(`Could not find API version for ${providerNamespace}${resourceType ? '/' + resourceType : ''}`);
+    }
+    catch (error) {
+        console.error(`Error fetching API versions: ${error instanceof Error ? error.message : String(error)}`);
+        // Return a default fallback version - you might want to customize this per provider
+        return '2021-04-01';
+    }
+}
+// This Azure credential handling approach is similar to Lokka-Microsoft
 function getAzureCredential() {
     if (!azureCredential) {
         try {
@@ -50,6 +103,7 @@ function getAzureCredential() {
     }
     return azureCredential;
 }
+// Response formatting utilities inspired by Lokka-Microsoft
 function formatApiResponse(apiType, method, path, result) {
     return {
         content: [
@@ -80,7 +134,25 @@ function formatErrorResponse(err, apiType) {
         ],
     };
 }
+// Process OData parameters for Graph API
+function processODataParams({ queryParams = {}, select, filter, expand, orderBy, top, count }) {
+    const processedParams = { ...queryParams };
+    if (select)
+        processedParams['$select'] = select;
+    if (filter)
+        processedParams['$filter'] = filter;
+    if (expand)
+        processedParams['$expand'] = expand;
+    if (orderBy)
+        processedParams['$orderby'] = orderBy;
+    if (top !== undefined)
+        processedParams['$top'] = top.toString();
+    if (count)
+        processedParams['$count'] = 'true';
+    return processedParams;
+}
 // MICROSOFT GRAPH API TOOL
+// This tool implementation is inspired by and adapted from Lokka-Microsoft's Graph API handling
 server.tool("askEntra", "Direct access to Microsoft Graph API for accurate Entra (Azure AD) data", {
     path: z.string().describe("The Graph API URL path (e.g. '/users/{id}/memberOf', '/directoryRoles')"),
     method: z.enum(["get", "post", "put", "patch", "delete"]).default("get").describe("HTTP method to use"),
@@ -97,51 +169,38 @@ server.tool("askEntra", "Direct access to Microsoft Graph API for accurate Entra
     top: z.number().optional().describe("Shorthand for $top query parameter"),
     count: z.boolean().optional().describe("Shorthand for $count=true to include count of items"),
 }, async ({ path, method, queryParams = {}, body, apiVersion, fetchAllPages, consistencyLevel, select, filter, expand, orderBy, top, count }) => {
-    console.error(`[askEntra] Processing request: ${method} ${path}`);
     try {
         // Process shorthand query parameters
-        const processedParams = { ...queryParams };
-        if (select)
-            processedParams['$select'] = select;
-        if (filter)
-            processedParams['$filter'] = filter;
-        if (expand)
-            processedParams['$expand'] = expand;
-        if (orderBy)
-            processedParams['$orderby'] = orderBy;
-        if (top !== undefined)
-            processedParams['$top'] = top.toString();
-        if (count)
-            processedParams['$count'] = 'true';
-        console.error(`[askEntra] Getting Azure credential`);
-        // Initialize or get Azure credential
-        const credential = getAzureCredential();
-        console.error(`[askEntra] Initializing Graph client`);
-        // Initialize Graph client if not already done
+        const processedParams = processODataParams({
+            queryParams,
+            select,
+            filter,
+            expand,
+            orderBy,
+            top,
+            count
+        });
+        // Initialize client on demand
         if (!graphClient) {
+            const credential = getAzureCredential();
             const authProvider = new TokenCredentialAuthenticationProvider(credential, {
                 scopes: ["https://graph.microsoft.com/.default"],
             });
             graphClient = Client.initWithMiddleware({ authProvider });
-            console.error(`[askEntra] Graph client initialized`);
         }
         // Build request with API path and version
-        console.error(`[askEntra] Creating request for ${path} with version ${apiVersion}`);
         let request = graphClient.api(path).version(apiVersion);
         // Add query parameters
         if (Object.keys(processedParams).length > 0) {
-            console.error(`[askEntra] Adding query parameters: ${JSON.stringify(processedParams)}`);
             request = request.query(processedParams);
         }
         // Add consistency level header if provided
         if (consistencyLevel) {
-            console.error(`[askEntra] Adding consistency level: ${consistencyLevel}`);
             request = request.header('ConsistencyLevel', consistencyLevel);
         }
         // Handle pagination for GET requests
         let result;
         if (method === 'get' && fetchAllPages) {
-            console.error(`[askEntra] Executing GET with pagination`);
             const firstPage = await request.get();
             // If no pagination needed, return first page
             if (!firstPage["@odata.nextLink"]) {
@@ -152,7 +211,6 @@ server.tool("askEntra", "Direct access to Microsoft Graph API for accurate Entra
                 const allItems = [...(firstPage.value || [])];
                 let nextLink = firstPage["@odata.nextLink"];
                 while (nextLink) {
-                    console.error(`[askEntra] Fetching next page: ${nextLink}`);
                     const nextPage = await graphClient.api(nextLink).get();
                     if (nextPage.value)
                         allItems.push(...nextPage.value);
@@ -168,7 +226,6 @@ server.tool("askEntra", "Direct access to Microsoft Graph API for accurate Entra
         }
         else {
             // Execute appropriate method
-            console.error(`[askEntra] Executing ${method} request`);
             switch (method) {
                 case 'get':
                     result = await request.get();
@@ -188,18 +245,14 @@ server.tool("askEntra", "Direct access to Microsoft Graph API for accurate Entra
                     break;
             }
         }
-        console.error(`[askEntra] Successfully executed request`);
         return formatApiResponse('Entra', method, path, result);
     }
     catch (err) {
-        console.error(`[askEntra] ERROR: ${err instanceof Error ? err.message : String(err)}`);
-        if (err instanceof Error && err.stack) {
-            console.error(`[askEntra] Stack trace: ${err.stack}`);
-        }
         return formatErrorResponse(err, 'Entra');
     }
 });
 // AZURE RESOURCE MANAGEMENT API TOOL
+// This tool implementation is inspired by and adapted from Lokka-Microsoft's Azure API handling
 server.tool("askAzure", "Direct access to Azure Resource Management API for managing Azure resources", {
     path: z.string().describe("The Azure API path (e.g. '/subscriptions', '/resourceGroups/{name}')"),
     method: z.enum(["get", "post", "put", "patch", "delete"]).default("get").describe("HTTP method to use"),
@@ -220,20 +273,35 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
     resourceGroupName: z.string().optional().describe("Resource group name for resource operations"),
     resourceName: z.string().optional().describe("Resource name for resource operations"),
 }, async ({ path, method, apiVersion, subscriptionId, body, queryParams = {}, fetchAllPages, operation = "custom", providerNamespace, resourceType, resourceGroupName, resourceName }) => {
-    console.error(`[askAzure] Processing request: ${operation} - ${method} ${path}`);
     try {
         // Default API versions for common resource types
         const defaultApiVersions = {
             'resources': '2021-04-01',
             'resourceGroups': '2021-04-01',
-            'subscriptions': '2021-01-01',
+            'subscriptions': '2022-12-01',
             'providers': '2021-04-01',
             'deployments': '2021-04-01',
             'Microsoft.Compute/virtualMachines': '2023-03-01',
             'Microsoft.Storage/storageAccounts': '2023-01-01',
             'Microsoft.Network/virtualNetworks': '2023-04-01',
-            'Microsoft.KeyVault/vaults': '2023-02-01'
+            'Microsoft.KeyVault/vaults': '2023-02-01',
+            'Microsoft.Billing/billingAccounts': '2024-04-01',
+            'Microsoft.CostManagement/query': '2023-03-01'
         };
+        // Set default API version for common paths if not provided
+        if (!apiVersion && !queryParams['api-version']) {
+            if (path === '/subscriptions') {
+                apiVersion = defaultApiVersions['subscriptions']; // Default API version for listing subscriptions
+            }
+        }
+        let extractedProviderNamespace = null;
+        // Try to extract provider namespace from the path if not explicitly provided
+        if (!providerNamespace && path.includes('/providers/')) {
+            const match = path.match(/\/providers\/([^\/]+)/);
+            if (match && match[1]) {
+                extractedProviderNamespace = match[1];
+            }
+        }
         // Handle predefined operations
         if (operation !== "custom") {
             const requiredSubscriptionId = !['listResourceProviders', 'getResourceProvider', 'registerResourceProvider'].includes(operation);
@@ -281,7 +349,21 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
                     path = `/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/${providerNamespace}/${resourceType}/${resourceName}`;
                     method = 'put';
                     const providerResourceKey = `${providerNamespace}/${resourceType}`;
-                    apiVersion = apiVersion || defaultApiVersions[providerResourceKey] || '2021-04-01';
+                    // Try to get the API version for this resource type
+                    if (!apiVersion) {
+                        // First check our default versions
+                        apiVersion = defaultApiVersions[providerResourceKey];
+                        // If not found in defaults, try to fetch it dynamically
+                        if (!apiVersion && providerNamespace) {
+                            try {
+                                apiVersion = await getLatestApiVersion(providerNamespace, resourceType);
+                            }
+                            catch (error) {
+                                console.error(`Error fetching API version: ${error instanceof Error ? error.message : String(error)}`);
+                                apiVersion = '2021-04-01'; // Fall back to a safe default
+                            }
+                        }
+                    }
                     break;
                 case 'deployTemplate':
                     if (!resourceGroupName)
@@ -301,16 +383,46 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
                     path = `/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/${providerNamespace}/${resourceType}/${resourceName}`;
                     method = 'delete';
                     const deleteResourceKey = `${providerNamespace}/${resourceType}`;
-                    apiVersion = apiVersion || defaultApiVersions[deleteResourceKey] || '2021-04-01';
+                    // Try to get the API version for this resource type
+                    if (!apiVersion) {
+                        // First check our default versions
+                        apiVersion = defaultApiVersions[deleteResourceKey];
+                        // If not found in defaults, try to fetch it dynamically
+                        if (!apiVersion && providerNamespace) {
+                            try {
+                                apiVersion = await getLatestApiVersion(providerNamespace, resourceType);
+                            }
+                            catch (error) {
+                                console.error(`Error fetching API version: ${error instanceof Error ? error.message : String(error)}`);
+                                apiVersion = '2021-04-01'; // Fall back to a safe default
+                            }
+                        }
+                    }
                     break;
             }
         }
+        else if (extractedProviderNamespace && !apiVersion && !queryParams['api-version']) {
+            // For custom operations, try to get the API version based on the path
+            try {
+                // Try to extract resource type from path if possible
+                let extractedResourceType;
+                const resourceTypeMatch = path.match(/\/providers\/[^\/]+\/([^\/]+)\/?/);
+                if (resourceTypeMatch && resourceTypeMatch[1]) {
+                    extractedResourceType = resourceTypeMatch[1];
+                }
+                // Fetch the latest API version
+                apiVersion = await getLatestApiVersion(extractedProviderNamespace, extractedResourceType);
+            }
+            catch (error) {
+                console.error(`Error fetching API version from path: ${error instanceof Error ? error.message : String(error)}`);
+                // Don't set a default here, let the error handling below catch it
+            }
+        }
         // Ensure API version is provided
         if (!apiVersion && !queryParams['api-version']) {
             throw new Error("Azure Resource Management API requires an 'apiVersion' parameter");
         }
         // Get Azure credential
-        console.error(`[askAzure] Getting Azure credential`);
         const credential = getAzureCredential();
         // Construct the base URL and path
         const baseUrl = "https://management.azure.com";
@@ -322,12 +434,10 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
         const params = new URLSearchParams(queryParams);
         if (apiVersion)
             params.set('api-version', apiVersion);
-        console.error(`[askAzure] Requesting token for Azure Resource Management API`);
         // Get access token
         const tokenResponse = await credential.getToken("https://management.azure.com/.default");
         if (!tokenResponse?.token)
             throw new Error("Failed to acquire Azure access token");
-        console.error(`[askAzure] Successfully acquired token`);
         // Prepare request options
         const headers = {
             'Authorization': `Bearer ${tokenResponse.token}`,
@@ -342,12 +452,10 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
         }
         // Construct URL
         const url = `${baseUrl}${fullPath}?${params.toString()}`;
-        console.error(`[askAzure] Making request to ${url}`);
         // Execute request with pagination if needed
         let result;
         if (method === 'get' && fetchAllPages) {
             // Fetch first page
-            console.error(`[askAzure] Executing GET with pagination`);
             const response = await fetch(url, options);
             if (!response.ok) {
                 const errorText = await response.text();
@@ -363,7 +471,6 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
                 const allItems = [...(firstPage.value || [])];
                 let nextLink = firstPage.nextLink;
                 while (nextLink) {
-                    console.error(`[askAzure] Fetching next page: ${nextLink}`);
                     const pageResponse = await fetch(nextLink, options);
                     if (!pageResponse.ok)
                         throw new Error(`Azure API pagination error: ${pageResponse.status}`);
@@ -380,11 +487,9 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
         }
         else {
             // Single page request
-            console.error(`[askAzure] Executing ${method} request`);
             const response = await fetch(url, options);
             if (!response.ok) {
                 const errorText = await response.text();
-                console.error(`[askAzure] Request failed with status ${response.status}: ${errorText}`);
                 let errorDetail;
                 try {
                     errorDetail = JSON.parse(errorText);
@@ -400,14 +505,9 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
             const text = await response.text();
             result = text ? JSON.parse(text) : { status: "Success" };
         }
-        console.error(`[askAzure] Successfully executed request`);
         return formatApiResponse('Azure', method, path, result);
     }
     catch (err) {
-        console.error(`[askAzure] ERROR: ${err instanceof Error ? err.message : String(err)}`);
-        if (err instanceof Error && err.stack) {
-            console.error(`[askAzure] Stack trace: ${err.stack}`);
-        }
         return formatErrorResponse(err, 'Azure');
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north7/entraaware",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -13,10 +13,16 @@
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["mcp-server", "entra", "azure-ad", "mcp", "microsoft-graph"],
-  "author": "",
-  "license": "ISC",
-  "description": "MCP server for querying Entra and Azure",
+  "keywords": ["mcp-server", "entra", "azure-ad", "mcp", "microsoft-graph", "azure-api"],
+  "author": "North7",
+  "contributors": [
+    {
+      "name": "Merill Fernando",
+      "url": "https://github.com/merill/lokka"
+    }
+  ],
+  "license": "MIT",
+  "description": "MCP server for querying Microsoft Entra (Azure AD) and Azure Resource Management APIs",
   "files": [
     "build"
   ],