mcp-consultant-tools 8.0.0 → 9.0.0

package/README.md

@@ -1,6 +1,6 @@
 # MCP Consultant Tools
 
-A Model Context Protocol (MCP) server providing intelligent access to PowerPlatform/Dataverse, Azure DevOps, Figma, Azure Application Insights, Azure Log Analytics, and Azure SQL Database through an AI-friendly interface.
+A Model Context Protocol (MCP) server providing intelligent access to PowerPlatform/Dataverse, Azure DevOps, Figma, Azure Application Insights, Azure Log Analytics, Azure SQL Database, and GitHub Enterprise through an AI-friendly interface.
 
 ## Overview
 
@@ -18,10 +18,11 @@ This MCP server enables AI assistants to:
 - **Application Insights** (10 tools): Query telemetry, analyze exceptions, monitor performance, troubleshoot issues
 - **Log Analytics** (10 tools): Query Azure Functions logs, analyze errors, monitor function performance, search workspace logs
 - **Azure SQL Database** (9 tools): Explore database schema, query tables safely with read-only access, investigate database structure
+- **GitHub Enterprise** (22 tools): Access source code, commits, branches, pull requests, correlate with deployed plugins and ADO work items
 
 All integrations are **optional** - configure only the services you need.
 
-**Total: 116 MCP tools & 23 prompts** providing comprehensive access to your development and operations lifecycle.
+**Total: 138 MCP tools & 28 prompts** providing comprehensive access to your development and operations lifecycle.
 
 ## Known limitations
 - Cannot create Model-Driven-Apps
@@ -92,7 +93,16 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
         "AZURE_SQL_DATABASE": "yourdatabase",
         "AZURE_SQL_USERNAME": "your-username",
         "AZURE_SQL_PASSWORD": "your-password",
-        "AZURE_SQL_USE_AZURE_AD": "false"
+        "AZURE_SQL_USE_AZURE_AD": "false",
+
+        "GHE_URL": "https://github.yourcompany.com",
+        "GHE_PAT": "ghp_your_personal_access_token",
+        "GHE_AUTH_METHOD": "pat",
+        "GHE_REPOS": "[{\"id\":\"plugin-core\",\"owner\":\"yourorg\",\"repo\":\"PluginCore\",\"defaultBranch\":\"release/9.0\",\"active\":true}]",
+        "GHE_ENABLE_CACHE": "true",
+        "GHE_CACHE_TTL": "300",
+        "GHE_ENABLE_WRITE": "false",
+        "GHE_ENABLE_CREATE": "false"
       }
     }
   }
@@ -147,7 +157,16 @@ Create `.vscode/mcp.json` in your project:
         "AZURE_SQL_DATABASE": "yourdatabase",
         "AZURE_SQL_USERNAME": "your-username",
         "AZURE_SQL_PASSWORD": "your-password",
-        "AZURE_SQL_USE_AZURE_AD": "false"
+        "AZURE_SQL_USE_AZURE_AD": "false",
+
+        "GHE_URL": "https://github.yourcompany.com",
+        "GHE_PAT": "ghp_your_personal_access_token",
+        "GHE_AUTH_METHOD": "pat",
+        "GHE_REPOS": "[{\"id\":\"plugin-core\",\"owner\":\"yourorg\",\"repo\":\"PluginCore\",\"defaultBranch\":\"release/9.0\",\"active\":true}]",
+        "GHE_ENABLE_CACHE": "true",
+        "GHE_CACHE_TTL": "300",
+        "GHE_ENABLE_WRITE": "false",
+        "GHE_ENABLE_CREATE": "false"
       }
     }
   }
@@ -291,9 +310,70 @@ Reload VS Code window after saving.
 - `appinsights-get-availability` - Get availability test results and uptime stats
 - `appinsights-get-custom-events` - Get custom application events
 
+### Log Analytics (10 tools)
+
+- `loganalytics-list-workspaces` - List all configured Log Analytics workspaces
+- `loganalytics-get-metadata` - Get workspace schema (tables and columns)
+- `loganalytics-execute-query` - Execute custom KQL queries
+- `loganalytics-get-function-logs` - Get Azure Function logs with filtering
+- `loganalytics-get-function-errors` - Get function error logs with exception details
+- `loganalytics-get-function-stats` - Get execution statistics (count, success rate)
+- `loganalytics-get-function-invocations` - Get function invocation records
+- `loganalytics-get-recent-events` - Get recent events from any table
+- `loganalytics-search-logs` - Search logs across tables
+- `loganalytics-test-workspace-access` - Validate workspace access
+
+### Azure SQL Database (9 tools)
+
+- `sql-test-connection` - Test database connectivity
+- `sql-list-tables` - List all tables with row counts and sizes
+- `sql-list-views` - List all views
+- `sql-list-stored-procedures` - List all stored procedures
+- `sql-list-triggers` - List all triggers
+- `sql-list-functions` - List all user-defined functions
+- `sql-get-table-schema` - Get complete table schema (columns, indexes, FKs)
+- `sql-get-object-definition` - Get SQL definition for views, procedures, functions, triggers
+- `sql-execute-query` - Execute SELECT queries safely with validation
+
+### GitHub Enterprise (22 tools)
+
+**Repository & Branch Management:**
+- `ghe-list-repos` - List all configured repositories
+- `ghe-list-branches` - List all branches for a repository
+- `ghe-get-default-branch` - Auto-detect default branch with typo handling
+- `ghe-get-branch-details` - Get detailed branch information
+- `ghe-compare-branches` - Compare two branches and show differences
+- `ghe-search-repos` - Search repositories by name or description
+
+**File Operations:**
+- `ghe-get-file` - Get file content from a specific branch
+- `ghe-search-code` - Search code across repositories
+- `ghe-list-files` - List files in a directory
+- `ghe-get-directory-structure` - Get recursive directory tree structure
+- `ghe-get-file-history` - Get commit history for a specific file
+
+**Commit & History:**
+- `ghe-get-commits` - Get commit history for a branch
+- `ghe-get-commit-details` - Get detailed information about a specific commit
+- `ghe-search-commits` - Search commits by message or hash (supports #1234 work item refs)
+- `ghe-get-commit-diff` - Get detailed diff for a commit
+
+**Pull Requests:**
+- `ghe-list-pull-requests` - List pull requests for a repository
+- `ghe-get-pull-request` - Get detailed pull request information
+- `ghe-get-pr-files` - Get files changed in a pull request
+
+**Write Operations (disabled by default):**
+- `ghe-create-branch` - Create a new branch (requires GHE_ENABLE_CREATE=true)
+- `ghe-update-file` - Update file content (requires GHE_ENABLE_WRITE=true)
+- `ghe-create-file` - Create a new file (requires GHE_ENABLE_CREATE=true)
+
+**Cache Management:**
+- `ghe-clear-cache` - Clear cached GitHub API responses
+
 ## Available Prompts
 
-The server includes **18 prompts** that provide formatted, context-rich output:
+The server includes **28 prompts** that provide formatted, context-rich output:
 
 **PowerPlatform:**
 - `entity-overview` - Comprehensive entity overview
@@ -319,15 +399,42 @@ The server includes **18 prompts** that provide formatted, context-rich output:
 - `appinsights-availability-report` - Availability and uptime report
 - `appinsights-troubleshooting-guide` - Comprehensive troubleshooting guide combining all telemetry
 
+**Log Analytics:**
+- `loganalytics-workspace-summary` - Workspace health overview with all functions
+- `loganalytics-function-troubleshooting` - Comprehensive function troubleshooting report
+- `loganalytics-function-performance-report` - Performance analysis with recommendations
+- `loganalytics-logs-report` - Formatted logs with insights for any table
+
 **Azure SQL Database:**
 - `sql-database-overview` - Comprehensive database schema overview with all objects
 - `sql-table-details` - Detailed table report with columns, indexes, and relationships
 - `sql-query-results` - Formatted query results with column headers
 
+**GitHub Enterprise:**
+- `ghe-repo-overview` - Repository overview with branch analysis and recent commits
+- `ghe-code-search-report` - Formatted code search results with relevance scoring
+- `ghe-branch-comparison-report` - Branch comparison with deployment checklist
+- `ghe-troubleshooting-guide` - Bug troubleshooting with cross-service correlation (ADO + GHE + PowerPlatform)
+- `ghe-deployment-report` - Deployment-ready report with rollback plan
+
 ## Documentation
 
+### Per-Integration Documentation
+
+Comprehensive documentation for each integration with setup, tools, prompts, examples, best practices, and troubleshooting:
+
+- **[PowerPlatform/Dataverse](docs/documentation/POWERPLATFORM.md)** - 76 tools, 9 prompts (entity metadata, plugins, workflows, customization API)
+- **[Azure DevOps](docs/documentation/AZURE_DEVOPS.md)** - 11 tools, 4 prompts (wikis, work items, WIQL queries)
+- **[Figma](docs/documentation/FIGMA.md)** - 2 tools (design data extraction, AI-friendly format)
+- **[Application Insights](docs/documentation/APPLICATION_INSIGHTS.md)** - 10 tools, 5 prompts (telemetry, exceptions, performance, dependencies)
+- **[Log Analytics](docs/documentation/LOG_ANALYTICS.md)** - 10 tools, 5 prompts (Azure Functions logs, KQL queries, function diagnostics)
+- **[Azure SQL Database](docs/documentation/AZURE_SQL.md)** - 9 tools, 3 prompts (schema exploration, read-only querying)
+- **[GitHub Enterprise](docs/documentation/GITHUB_ENTERPRISE.md)** - 22 tools, 5 prompts (source code, commits, branches, PRs, code correlation)
+
+### General Documentation
+
 - **[SETUP.md](SETUP.md)** - Complete setup guide with credentials, troubleshooting, and security
-- **[TOOLS.md](TOOLS.md)** - Full reference for all 105+ tools and 21 prompts
+- **[TOOLS.md](TOOLS.md)** - Full reference for all 138 tools and 28 prompts
 - **[USAGE.md](USAGE.md)** - Examples and use cases for all integrations
 - **[CLAUDE.md](CLAUDE.md)** - Architecture details and development guide
 
@@ -429,6 +536,20 @@ All integrations are optional and can be configured independently:
 - Read-only access to telemetry data
 - Entra ID recommended for production (higher rate limits)
 
+**Log Analytics:**
+- Supports Entra ID (OAuth) or API Key authentication
+- Read-only access to workspace logs
+- Can share credentials with Application Insights (automatic fallback)
+- Entra ID recommended for production (higher rate limits)
+
+**GitHub Enterprise:**
+- Supports Personal Access Token (PAT) or GitHub App authentication
+- PAT authentication is simpler (recommended for individual use)
+- GitHub App authentication for organization-wide deployments (higher rate limits)
+- Write operations disabled by default (enable with environment flags)
+- Response caching with configurable TTL (default: 5 minutes)
+- Required scopes for PAT: `repo` (required), `read:org` (optional)
+
 See [SETUP.md](SETUP.md#security-best-practices) for security best practices.
 
 ## Examples
@@ -479,6 +600,31 @@ AI: [uses sql-execute-query tool with "SELECT TOP 10 * FROM dbo.Users WHERE IsAc
 Returns formatted query results with column headers
 ```
 
+### Troubleshoot bugs with GitHub Enterprise cross-service correlation
+
+```
+User: "Investigate bug reported in ADO work item #1234"
+AI: [uses ghe-troubleshooting-guide prompt]
+1. Gets work item details from Azure DevOps
+2. Searches GitHub commits for "AB#1234" references
+3. Retrieves changed code files
+4. Checks deployed plugin assembly in PowerPlatform
+5. Analyzes Application Insights exceptions
+Returns comprehensive troubleshooting report with code changes, deployment status, and runtime errors
+```
+
+```
+User: "Search GitHub for ContactPlugin implementation"
+AI: [uses ghe-search-code tool]
+Returns code search results with file paths and line numbers
+```
+
+```
+User: "Compare release/9.0 and main branches"
+AI: [uses ghe-branch-comparison-report prompt]
+Returns formatted comparison with deployment checklist
+```
+
 See [USAGE.md](USAGE.md) for more examples.
 
 ## Development

package/build/AzureDevOpsService.js

@@ -30,7 +30,7 @@ export class AzureDevOpsService {
     /**
      * Make an authenticated request to the Azure DevOps API
      */
-    async makeRequest(endpoint, method = 'GET', data, useSearchUrl = false) {
+    async makeRequest(endpoint, method = 'GET', data, useSearchUrl = false, customHeaders) {
         try {
             const baseUrl = useSearchUrl ? this.searchUrl : this.baseUrl;
             const url = `${baseUrl}/${endpoint}`;
@@ -40,7 +40,8 @@ export class AzureDevOpsService {
                 headers: {
                     'Authorization': this.authHeader,
                     'Content-Type': method === 'PATCH' ? 'application/json-patch+json' : 'application/json',
-                    'Accept': 'application/json'
+                    'Accept': 'application/json',
+                    ...customHeaders // Merge custom headers (can override defaults)
                 },
                 data
             });
@@ -158,33 +159,67 @@ export class AzureDevOpsService {
      */
     async getWikiPage(project, wikiId, pagePath, includeContent = true) {
         this.validateProject(project);
-        // Auto-convert git paths to wiki paths for better compatibility
-        // If the path ends with .md, it's likely a git path from search results
-        let wikiPath = pagePath;
-        if (pagePath.endsWith('.md')) {
-            wikiPath = this.convertGitPathToWikiPath(pagePath);
-            // Log to stderr (not stdout) to avoid breaking MCP protocol
-            console.error(`Auto-converted git path to wiki path: ${pagePath} -> ${wikiPath}`);
+        // Always normalize paths to wiki format (removes .md, converts dashes to spaces)
+        // This ensures consistent behavior regardless of input format
+        const wikiPath = this.convertGitPathToWikiPath(pagePath);
+        // Log conversion if the path was changed (for debugging)
+        if (wikiPath !== pagePath) {
+            console.error(`Normalized wiki path: ${pagePath} -> ${wikiPath}`);
+        }
+        // Use axios directly to access response headers (for ETag)
+        const url = `${this.baseUrl}/${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(wikiPath)}&includeContent=${includeContent}&api-version=${this.apiVersion}`;
+        try {
+            const axiosResponse = await axios({
+                method: 'GET',
+                url,
+                headers: {
+                    'Authorization': this.authHeader,
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json'
+                }
+            });
+            const response = axiosResponse.data;
+            // Extract ETag from response headers (needed for updates)
+            const etag = axiosResponse.headers['etag'] || axiosResponse.headers['ETag'];
+            // The API returns the page data directly (not wrapped in a 'page' property)
+            return {
+                id: response.id,
+                path: response.path,
+                content: response.content,
+                gitItemPath: response.gitItemPath,
+                subPages: response.subPages || [],
+                url: response.url,
+                remoteUrl: response.remoteUrl,
+                version: etag, // Include ETag for use with updateWikiPage
+                project,
+                wikiId
+            };
+        }
+        catch (error) {
+            // Handle errors similar to makeRequest
+            const errorDetails = error.response?.data?.message || error.response?.data || error.message;
+            console.error('Azure DevOps API request failed:', {
+                url,
+                status: error.response?.status,
+                error: errorDetails
+            });
+            if (error.response?.status === 401) {
+                throw new Error('Azure DevOps authentication failed. Please check your PAT token and permissions.');
+            }
+            if (error.response?.status === 403) {
+                throw new Error('Azure DevOps access denied. Please check your PAT scopes and project permissions.');
+            }
+            if (error.response?.status === 404) {
+                throw new Error(`Wiki page not found: ${wikiPath} (original input: ${pagePath})`);
+            }
+            throw new Error(`Azure DevOps API request failed: ${error.message} - ${JSON.stringify(errorDetails)}`);
         }
-        const response = await this.makeRequest(`${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(wikiPath)}&includeContent=${includeContent}&api-version=${this.apiVersion}`);
-        // The API returns the page data directly (not wrapped in a 'page' property)
-        return {
-            id: response.id,
-            path: response.path,
-            content: response.content,
-            gitItemPath: response.gitItemPath,
-            subPages: response.subPages || [],
-            url: response.url,
-            remoteUrl: response.remoteUrl,
-            project,
-            wikiId
-        };
     }
     /**
      * Create a new wiki page
      * @param project The project name
      * @param wikiId The wiki identifier
-     * @param pagePath The path for the new page
+     * @param pagePath The path for the new page (will be normalized to wiki format)
      * @param content The markdown content
      * @returns Created page information
      */
@@ -193,7 +228,13 @@ export class AzureDevOpsService {
         if (!this.config.enableWikiWrite) {
             throw new Error('Wiki write operations are disabled. Set AZUREDEVOPS_ENABLE_WIKI_WRITE=true to enable.');
         }
-        const response = await this.makeRequest(`${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(pagePath)}&api-version=${this.apiVersion}`, 'PUT', { content });
+        // Always normalize paths to wiki format (removes .md, converts dashes to spaces)
+        const wikiPath = this.convertGitPathToWikiPath(pagePath);
+        // Log conversion if the path was changed (for debugging)
+        if (wikiPath !== pagePath) {
+            console.error(`Normalized wiki path for creation: ${pagePath} -> ${wikiPath}`);
+        }
+        const response = await this.makeRequest(`${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(wikiPath)}&api-version=${this.apiVersion}`, 'PUT', { content });
         return {
             id: response.page?.id,
             path: response.page?.path,
@@ -206,9 +247,9 @@ export class AzureDevOpsService {
      * Update an existing wiki page
      * @param project The project name
      * @param wikiId The wiki identifier
-     * @param pagePath The path to the page
+     * @param pagePath The path to the page (will be normalized to wiki format)
      * @param content The updated markdown content
-     * @param version The ETag/version for optimistic concurrency
+     * @param version The ETag/version for optimistic concurrency (recommended to prevent conflicts)
      * @returns Updated page information
      */
     async updateWikiPage(project, wikiId, pagePath, content, version) {
@@ -216,7 +257,16 @@ export class AzureDevOpsService {
         if (!this.config.enableWikiWrite) {
             throw new Error('Wiki write operations are disabled. Set AZUREDEVOPS_ENABLE_WIKI_WRITE=true to enable.');
         }
-        const response = await this.makeRequest(`${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(pagePath)}&api-version=${this.apiVersion}`, 'PUT', { content });
+        // Always normalize paths to wiki format (removes .md, converts dashes to spaces)
+        const wikiPath = this.convertGitPathToWikiPath(pagePath);
+        // Log conversion if the path was changed (for debugging)
+        if (wikiPath !== pagePath) {
+            console.error(`Normalized wiki path for update: ${pagePath} -> ${wikiPath}`);
+        }
+        // Add If-Match header if version is provided (for optimistic concurrency control)
+        const customHeaders = version ? { 'If-Match': version } : undefined;
+        const response = await this.makeRequest(`${project}/_apis/wiki/wikis/${wikiId}/pages?path=${encodeURIComponent(wikiPath)}&api-version=${this.apiVersion}`, 'PUT', { content }, false, // useSearchUrl
+        customHeaders);
         return {
             id: response.page?.id,
             path: response.page?.path,