@north7/entraaware 0.0.5 → 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.5",
+    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: [
@@ -98,6 +152,7 @@ function processODataParams({ queryParams = {}, select, filter, expand, orderBy,
     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"),
@@ -197,6 +252,7 @@ server.tool("askEntra", "Direct access to Microsoft Graph API for accurate 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"),
@@ -222,18 +278,28 @@ server.tool("askAzure", "Direct access to Azure Resource Management API for mana
         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 = '2022-12-01'; // Default API version for listing 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
@@ -283,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)
@@ -303,10 +383,41 @@ 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north7/entraaware",
-  "version": "0.0.5",
+  "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"
   ],