mcp-consultant-tools 1.0.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2025 Michal Sobieraj
+
+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.
+
+================================================================================
+This project includes code derived from Figma-Context-MCP
+(https://github.com/glipsman/figma-context-mcp)
+
+Original Copyright Notice:
+Copyright (c) 2025 Graham Lipsman
+
+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,11 +1,11 @@
-# PowerPlatform MCP Server
+# MCP Consultant Tools
 
-A Model Context Protocol (MCP) server that provides intelligent access to PowerPlatform/Dataverse entities and records. This tool offers context-aware assistance, entity exploration and metadata access.
+A Model Context Protocol (MCP) server that provides intelligent access to PowerPlatform/Dataverse entities, Azure DevOps, and Figma designs. This tool offers context-aware assistance, entity exploration, and metadata access across multiple platforms.
 
 Key features:
-- Rich entity metadata exploration with formatted, context-aware prompts
-- Advanced OData query support with intelligent filtering
-- Comprehensive relationship mapping and visualization
+- **PowerPlatform/Dataverse**: Rich entity metadata exploration with formatted, context-aware prompts, advanced OData query support, comprehensive relationship mapping
+- **Azure DevOps**: Wiki search, work item management, WIQL queries, and team collaboration tools
+- **Figma**: Design data extraction with simplified AI-friendly format, component analysis, and style deduplication
 - AI-assisted query building and data modeling through AI agent
 - Full access to entity attributes, relationships, and global option sets
 
@@ -37,6 +37,44 @@ npx mcp-consultant-tools
 
 This is an MCP server designed to work with MCP-compatible clients like Claude Desktop, Cursor, or Claude Code (VS Code extension).
 
+### Quick Start: VS Code (Claude Code) Configuration
+
+For VS Code with Claude Code extension, create a `.vscode/mcp.json` file in your repository:
+
+```json
+{
+  "servers": {
+    "mcp-consultant-tools": {
+      "command": "npx",
+      "args": ["-y", "mcp-consultant-tools"],
+      "env": {
+        "POWERPLATFORM_URL": "https://yourenvironment.crm.dynamics.com",
+        "POWERPLATFORM_CLIENT_ID": "your-azure-app-client-id",
+        "POWERPLATFORM_CLIENT_SECRET": "your-azure-app-client-secret",
+        "POWERPLATFORM_TENANT_ID": "your-azure-tenant-id",
+        "AZUREDEVOPS_ORGANIZATION": "your-organization-name",
+        "AZUREDEVOPS_PAT": "your-personal-access-token",
+        "AZUREDEVOPS_PROJECTS": "Project1,Project2",
+        "AZUREDEVOPS_API_VERSION": "7.1",
+        "AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE": "true",
+        "AZUREDEVOPS_ENABLE_WORK_ITEM_DELETE": "false",
+        "AZUREDEVOPS_ENABLE_WIKI_WRITE": "false",
+        "FIGMA_API_KEY": "your-figma-personal-access-token",
+        "FIGMA_OAUTH_TOKEN": "",
+        "FIGMA_USE_OAUTH": "false"
+      }
+    }
+  }
+}
+```
+
+**After configuration:**
+1. Save the `.vscode/mcp.json` file
+2. Reload VS Code window
+3. The MCP server will be available in Claude Code
+
+**Note:** You can omit PowerPlatform, Azure DevOps, or Figma credentials if you only need certain integrations (see Environment Variables Reference below).
+
 ### Quick Start: Claude Desktop Configuration
 
 Add this to your Claude Desktop config file at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
@@ -58,7 +96,10 @@ Add this to your Claude Desktop config file at `~/Library/Application Support/Cl
         "AZUREDEVOPS_API_VERSION": "7.1",
         "AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE": "true",
         "AZUREDEVOPS_ENABLE_WORK_ITEM_DELETE": "false",
-        "AZUREDEVOPS_ENABLE_WIKI_WRITE": "false"
+        "AZUREDEVOPS_ENABLE_WIKI_WRITE": "false",
+        "FIGMA_API_KEY": "your-figma-personal-access-token",
+        "FIGMA_OAUTH_TOKEN": "",
+        "FIGMA_USE_OAUTH": "false"
       }
     }
   }
@@ -86,7 +127,10 @@ For local development and testing, you can run the server directly from your clo
         "AZUREDEVOPS_API_VERSION": "7.1",
         "AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE": "true",
         "AZUREDEVOPS_ENABLE_WORK_ITEM_DELETE": "false",
-        "AZUREDEVOPS_ENABLE_WIKI_WRITE": "false"
+        "AZUREDEVOPS_ENABLE_WIKI_WRITE": "false",
+        "FIGMA_API_KEY": "your-figma-personal-access-token",
+        "FIGMA_OAUTH_TOKEN": "",
+        "FIGMA_USE_OAUTH": "false"
       }
     }
   }
@@ -97,10 +141,11 @@ For local development and testing, you can run the server directly from your clo
 
 ### Environment Variables Reference
 
-**Note:** Both PowerPlatform and Azure DevOps integrations are optional. You can configure only the services you need:
+**Note:** All integrations (PowerPlatform, Azure DevOps, Figma) are optional. You can configure only the services you need:
 - PowerPlatform only: Set `POWERPLATFORM_*` variables
 - Azure DevOps only: Set `AZUREDEVOPS_*` variables
-- Both: Set all variables
+- Figma only: Set `FIGMA_*` variables
+- Any combination: Set only the variables you need
 
 **PowerPlatform/Dataverse (Optional):**
 - `POWERPLATFORM_URL`: Your PowerPlatform environment URL
@@ -117,6 +162,18 @@ For local development and testing, you can run the server directly from your clo
 - `AZUREDEVOPS_ENABLE_WORK_ITEM_DELETE`: Enable work item delete operations (default: "false")
 - `AZUREDEVOPS_ENABLE_WIKI_WRITE`: Enable wiki write operations (default: "false")
 
+**Figma (Optional):**
+- `FIGMA_API_KEY`: Figma Personal Access Token (generate at: https://www.figma.com/developers/api#authentication)
+- `FIGMA_OAUTH_TOKEN`: Alternative to API key for OAuth authentication
+- `FIGMA_USE_OAUTH`: Set to "true" if using OAuth token instead of API key (default: "false")
+
+**How to get a Figma API Key:**
+1. Go to https://www.figma.com/developers/api#authentication
+2. Scroll to "Personal Access Tokens"
+3. Click "Get personal access token"
+4. Log in to Figma
+5. Generate new token and copy it to your config
+
 **After configuration:**
 1. Save the config file
 2. Completely restart Claude Desktop (quit and reopen)
@@ -128,6 +185,10 @@ Once configured, the MCP server will expose tools for retrieving PowerPlatform e
 
 ### Available Tools
 
+The server provides **30 tools** across PowerPlatform, Azure DevOps, and Figma integrations.
+
+### PowerPlatform/Dataverse Tools
+
 #### Entity Metadata & Data Tools
 - `get-entity-metadata`: Get metadata about a PowerPlatform entity
 - `get-entity-attributes`: Get attributes/fields of a PowerPlatform entity
@@ -136,7 +197,6 @@ Once configured, the MCP server will expose tools for retrieving PowerPlatform e
 - `get-global-option-set`: Get a global option set definition
 - `get-record`: Get a specific record by entity name and ID
 - `query-records`: Query records using an OData filter expression
-- `use-powerplatform-prompt`: Use pre-defined prompt templates for PowerPlatform entities
 
 #### Plugin Registration & Validation Tools
 - `get-plugin-assemblies`: List all plugin assemblies in the environment
@@ -144,153 +204,60 @@ Once configured, the MCP server will expose tools for retrieving PowerPlatform e
 - `get-entity-plugin-pipeline`: Get all plugins that execute on a specific entity, organized by message and execution order
 - `get-plugin-trace-logs`: Query plugin trace logs with filtering and exception parsing
 
-## MCP Prompts
-
-The server includes a prompts feature that provides formatted, context-rich information about PowerPlatform entities.
-
-### Available Prompt Types
-
-#### Entity Prompts
-The `use-powerplatform-prompt` tool supports the following prompt types:
-
-1. **ENTITY_OVERVIEW**: Comprehensive overview of an entity
-2. **ATTRIBUTE_DETAILS**: Detailed information about a specific entity attribute
-3. **QUERY_TEMPLATE**: OData query template for an entity with example filters
-4. **RELATIONSHIP_MAP**: Visual map of entity relationships
-
-#### Plugin Prompts
-5. **plugin-deployment-report**: Generate a comprehensive deployment report for a plugin assembly with validation warnings
-6. **entity-plugin-pipeline-report**: Generate a visual execution pipeline showing all plugins for an entity in order
-
-### Examples
-
-#### Entity Overview Prompt
-
-```javascript
-// Example client code
-await mcpClient.invoke("use-powerplatform-prompt", {
-  promptType: "ENTITY_OVERVIEW",
-  entityName: "account"
-});
-```
-
-**Output:**
-```
-## Power Platform Entity: account
-
-This is an overview of the 'account' entity in Microsoft Power Platform/Dataverse:
+#### Workflow & Power Automate Flow Tools
+- `get-flows`: List all Power Automate cloud flows (category = 5)
+- `get-flow-definition`: Get complete flow definition including JSON logic from clientdata field
+- `get-flow-runs`: Get flow run history with status, duration, and error details
+- `get-workflows`: List all classic Dynamics workflows (category = 0)
+- `get-workflow-definition`: Get complete workflow definition including XAML and trigger configuration
 
-### Entity Details
-- Display Name: Account
-- Schema Name: Account
-- Description: Business that represents a customer or potential customer
-- Primary Key: accountid
-- Primary Name: name
+### Azure DevOps Tools
 
-### Key Attributes
-- name: String (Account Name)
-- emailaddress1: String (Email)
-- telephone1: String (Main Phone)
-- address1_city: String (City)
-- statecode: Status (Status)
-- accountnumber: String (Account Number)
-- industrycode: OptionSetValue (Industry)
-- revenue: Money (Annual Revenue)
-- ownerid: Owner (Owner)
-- createdon: DateTime (Created On)
-
-### Relationships
-- One-to-Many Relationships: 42
-- Many-to-Many Relationships: 8
-
-You can query this entity using OData filters against the plural name.
-```
-
-#### Attribute Details Prompt
-
-```javascript
-await mcpClient.invoke("use-powerplatform-prompt", {
-  promptType: "ATTRIBUTE_DETAILS",
-  entityName: "account",
-  attributeName: "revenue"
-});
-```
-
-**Output:**
-```
-## Attribute: revenue
-
-Details for the 'revenue' attribute of the 'account' entity:
-
-- Display Name: Annual Revenue
-- Description: Annual revenue for the account
-- Type: Money
-- Format: Currency
-- Is Required: No
-- Is Searchable: true
-
-### Usage Notes
-- Data Type: Money
-- Required: No
-- Max Length: N/A
-```
-
-#### Query Template Prompt
-
-```javascript
-await mcpClient.invoke("use-powerplatform-prompt", {
-  promptType: "QUERY_TEMPLATE",
-  entityName: "account"
-});
-```
-
-**Output:**
-```
-## OData Query Template for accounts
+#### Wiki Tools
+- `get-wikis`: List all wikis in a project
+- `search-wiki-pages`: Full-text search across wiki pages with highlighting
+- `get-wiki-page`: Get specific wiki page content and metadata
+- `create-wiki-page`: Create new wiki page (requires `AZUREDEVOPS_ENABLE_WIKI_WRITE=true`)
+- `update-wiki-page`: Update existing wiki page (requires `AZUREDEVOPS_ENABLE_WIKI_WRITE=true`)
 
-Use this template to build queries against the accounts entity:
-accounts?$select=name,emailaddress1,telephone1, address1_city,statecode&$filter=name eq 'Example'&$orderby=name asc&$top=50
-```
+#### Work Item Tools
+- `get-work-item`: Get work item by ID with full details
+- `query-work-items`: Execute WIQL queries to find work items
+- `get-work-item-comments`: Get discussion comments for a work item
+- `add-work-item-comment`: Add comment to work item (requires `AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true`)
+- `update-work-item`: Update work item fields using JSON Patch (requires `AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true`)
+- `create-work-item`: Create new work item (requires `AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true`)
+- `delete-work-item`: Delete work item (requires `AZUREDEVOPS_ENABLE_WORK_ITEM_DELETE=true`)
 
-### Common Filter Examples
-- Equals: `name eq 'Contoso'`
-- Contains: `contains(name, 'Contoso')`
-- Greater than date: `createdon gt 2023-01-01T00:00:00Z`
-- Multiple conditions: `name eq 'Contoso' and statecode eq 0`
-```
+### Figma Tools
+- `get-figma-data`: Get comprehensive Figma design data including layout, text, styles, and components. Fetches from Figma API and transforms into simplified, AI-friendly format. Can fetch entire files or specific nodes.
+- `download-figma-images`: Placeholder for future image download functionality (Coming in v2)
 
-#### Relationship Map Prompt
+## MCP Prompts
 
-```javascript
-await mcpClient.invoke("use-powerplatform-prompt", {
-  promptType: "RELATIONSHIP_MAP",
-  entityName: "contact"
-});
-```
+The server includes **12 prompts** that provide formatted, context-rich information across all integrations.
 
-**Output:**
-```
-## Relationship Map for contact
+### Available Prompts
 
-This shows all relationships for the 'contact' entity:
+#### Entity Prompts
+1. **entity-overview**: Comprehensive overview of a PowerPlatform entity
+2. **attribute-details**: Detailed information about a specific entity attribute
+3. **query-template**: OData query template for an entity with example filters
+4. **relationship-map**: Visual map of entity relationships
 
-### One-to-Many Relationships (contact as Primary)
-- contact_activity_parties: contact (1) → activityparty (N)
-- contact_connections1: contact (1) → connection (N)
-- contact_connections2: contact (1) → connection (N)
-- contact_customer_contacts: contact (1) → contact (N)
-- contact_master_contact: contact (1) → contact (N)
+#### PowerPlatform Plugin Prompts
+5. **plugin-deployment-report**: Generate a comprehensive deployment report for a plugin assembly with validation warnings
+6. **entity-plugin-pipeline-report**: Generate a visual execution pipeline showing all plugins for an entity in order
 
-### One-to-Many Relationships (contact as Related)
-- account_primary_contact: account (1) → contact (N)
-- customer_contacts: customer (1) → contact (N)
-- system_user_contacts: systemuser (1) → contact (N)
+#### PowerPlatform Workflow & Flow Prompts
+7. **flows-report**: Comprehensive report of all Power Automate flows grouped by state
+8. **workflows-report**: Comprehensive report of all classic Dynamics workflows grouped by state
 
-### Many-to-Many Relationships
-- contactleads_association: contact (N) ↔ lead (N)
-- contactopportunities_association: contact (N) ↔ opportunity (N)
-- contactquotes_association: contact (N) ↔ quote (N)
-```
+#### Azure DevOps Prompts
+9. **wiki-search-results**: Search Azure DevOps wiki pages with formatted results and content snippets
+10. **wiki-page-content**: Get a formatted wiki page with navigation context and sub-pages
+11. **work-item-summary**: Get a comprehensive summary of a work item with details and comments
+12. **work-items-query-report**: Execute a WIQL query and get results grouped by state/type
 
 ## Prompt Examples
 

package/build/FigmaService.js

@@ -0,0 +1,107 @@
+import { fetchWithRetry } from "./figma/utils/fetch-with-retry.js";
+import { simplifyRawFigmaObject } from "./figma/extractors/design-extractor.js";
+import { allExtractors } from "./figma/extractors/built-in.js";
+/**
+ * Service for interacting with the Figma API
+ * Follows the service pattern established by PowerPlatformService
+ */
+export class FigmaService {
+    config;
+    baseUrl = "https://api.figma.com/v1";
+    constructor(config) {
+        this.config = config;
+        // Validate configuration
+        if (!this.config.apiKey && !this.config.oauthToken) {
+            throw new Error("Figma configuration requires either apiKey or oauthToken");
+        }
+        if (this.config.useOAuth && !this.config.oauthToken) {
+            throw new Error("useOAuth is true but oauthToken is not provided");
+        }
+    }
+    /**
+     * Get authentication headers based on configuration
+     */
+    getAuthHeaders() {
+        if (this.config.useOAuth && this.config.oauthToken) {
+            console.error("Using OAuth Bearer token for authentication");
+            return { Authorization: `Bearer ${this.config.oauthToken}` };
+        }
+        else if (this.config.apiKey) {
+            console.error("Using Personal Access Token for authentication");
+            return { "X-Figma-Token": this.config.apiKey };
+        }
+        throw new Error("No valid authentication method configured");
+    }
+    /**
+     * Make an authenticated request to the Figma API
+     */
+    async request(endpoint) {
+        try {
+            console.error(`Calling ${this.baseUrl}${endpoint}`);
+            const headers = this.getAuthHeaders();
+            return await fetchWithRetry(`${this.baseUrl}${endpoint}`, {
+                headers,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to make request to Figma API endpoint '${endpoint}': ${errorMessage}`);
+        }
+    }
+    /**
+     * Get raw Figma API response for a file
+     * @param fileKey - The Figma file key from the URL
+     * @param depth - Optional depth limit for traversal
+     */
+    async getFigmaFile(fileKey, depth) {
+        const endpoint = `/files/${fileKey}${depth ? `?depth=${depth}` : ""}`;
+        console.error(`Retrieving Figma file: ${fileKey} (depth: ${depth ?? "default"})`);
+        const response = await this.request(endpoint);
+        return response;
+    }
+    /**
+     * Get raw Figma API response for specific nodes
+     * @param fileKey - The Figma file key from the URL
+     * @param nodeIds - Array of node IDs to fetch
+     * @param depth - Optional depth limit for traversal
+     */
+    async getFigmaNodes(fileKey, nodeIds, depth) {
+        const endpoint = `/files/${fileKey}/nodes?ids=${nodeIds.join(",")}${depth ? `&depth=${depth}` : ""}`;
+        console.error(`Retrieving Figma nodes: ${nodeIds.join(", ")} from ${fileKey} (depth: ${depth ?? "default"})`);
+        const response = await this.request(endpoint);
+        return response;
+    }
+    /**
+     * Get comprehensive Figma design data in simplified, AI-friendly format
+     * This is the main method exposed to MCP tools
+     *
+     * @param fileKey - The Figma file key from the URL
+     * @param nodeId - Optional specific node ID(s) to fetch (format: "1:10" or "1:10;2:20")
+     * @param depth - Optional tree traversal depth limit
+     * @returns Simplified design data ready for AI consumption
+     */
+    async getFigmaData(fileKey, nodeId, depth) {
+        try {
+            // Fetch raw data from Figma API
+            let rawData;
+            if (nodeId) {
+                // Parse node IDs (support both single and multiple, semicolon-separated)
+                const nodeIds = nodeId.split(";").map(id => id.trim()).filter(id => id.length > 0);
+                rawData = await this.getFigmaNodes(fileKey, nodeIds, depth);
+            }
+            else {
+                rawData = await this.getFigmaFile(fileKey, depth);
+            }
+            // Transform raw Figma data into simplified format using extractors
+            const options = {
+                maxDepth: depth,
+            };
+            const simplifiedData = simplifyRawFigmaObject(rawData, allExtractors, options);
+            return simplifiedData;
+        }
+        catch (error) {
+            console.error("Error fetching Figma data:", error);
+            throw new Error(`Failed to fetch Figma data: ${error.message}`);
+        }
+    }
+}