Content
# Power Platform Agent
Power Platform development assistant - Built on top of Hermes Agent framework, providing tool access via MCP protocol for Claude Code and Cursor.
## Features
- 📋 **Code-first development**: Define Power Platform metadata using YAML
- 🔧 **Plugin automation**: Automatic build and deployment of .NET plugins
- 🔄 **Bi-directional sync**: Compare and sync local and cloud metadata
- 📝 **Naming conventions**: Unified naming conversion and validation rules
- 🧩 **Multi-environment support**: Manage dev/test/prod environments
- 📚 **Data dictionary**: Automatically generate navigable data documentation
- 🗂️ **Component library**: Reusable YAML template snippets
- 🔌 **Git Hooks**: Automatic documentation updates before commits
## Quick Start
### Install Dependencies
```bash
# Windows
install.bat
# Linux/Mac
chmod +x install.sh
./install.sh
```
Or manual installation:
```bash
pip install -r requirements.txt
```
### Run Build and Validation
```bash
python build_and_validate.py
```
### Start MCP Server
```bash
# Method 1: Run directly (recommended for development)
python framework/mcp_serve.py --stdio
# Method 2: Run as package (recommended for production)
pip install -e .
pp-mcp --stdio
# SSE mode (standalone)
python framework/mcp_serve.py --port 8000
```
### Test Imports
```bash
python test_imports.py
```
## Project Structure
```
power-platform-agent/
├── framework/ # Framework layer (reusable core components)
│ ├── agents/ # Agent implementations
│ │ ├── core_agent.py
│ │ ├── metadata_agent.py
│ │ ├── plugin_agent.py
│ │ └── solution_agent.py
│ ├── utils/ # Utility functions
│ │ ├── dataverse_client.py
│ │ ├── yaml_parser.py
│ │ ├── schema_validator.py
│ │ └── naming_converter.py
│ └── mcp_serve.py # MCP server entry
├── metadata/ # YAML metadata definitions
│ ├── _schema/ # Schema definitions
│ ├── tables/ # Table definitions
│ ├── forms/ # Form definitions
│ ├── views/ # View definitions
│ ├── webresources/ # Web Resource configurations
│ ├── ribbon/ # Command bar definitions
│ ├── sitemap/ # App navigation definitions
│ └── optionsets/ # Global option sets
├── sources/ # Source file layer
│ ├── templates/ # Excel/Word/PPT templates
│ ├── features/ # Organized by feature iterations
│ └── library/ # Reusable YAML snippets
├── transformers/ # Transformer layer (schema preserved)
├── docs/
│ ├── data_dictionary/ # Automatically generated data dictionary
│ ├── spec/ # Specification documents
│ └── guides/ # User guides
├── scripts/ # Script tools
│ ├── generate_data_dictionary.py
│ ├── hooks/ # Git hooks
│ └── install_hooks.sh
├── webresources/ # Web Resource source files
│ ├── css/
│ ├── js/
│ ├── html/
│ └── img/
├── plugins/ # .NET plugin source code
│ └── AccountPlugin/
├── config/ # Configuration files
│ ├── hermes_profile.yaml
│ ├── environments.yaml
│ ├── naming_rules.yaml
│ ├── extensions.yaml
│ └── settings.yaml
├── .claude/ # Claude Code configuration
│ └── context_config.yaml
├── build_and_validate.py # Build and validation script
├── setup.py # Package installation configuration
└── test_imports.py # Import test
```
## Data Dictionary Auto-Generation
The project includes an auto-generated data dictionary feature, generating navigable Markdown documentation from YAML metadata.
### Install Git Hooks (Recommended)
```bash
bash scripts/install_hooks.sh
```
After installation, YAML files in `metadata/` will automatically update the data dictionary on commit.
### Manual Generation
```bash
# Generate all documents
python scripts/generate_data_dictionary.py --all
# Generate specific files
python scripts/generate_data_dictionary.py --files metadata/tables/account.yaml
```
### Generated Documentation Structure
```
docs/data_dictionary/
├── index.md # Index
├── all_tables.md # All table structures
├── all_optionsets.md # All option sets
├── tables/ # Tables by block
│ ├── account.md
│ └── contact.md
└── optionsets/ # Option set documentation
├── new_customer_status.md
└── new_payment_terms.md
```
### Virtual Field Filtering
The generator automatically filters Dataverse virtual fields:
- Lookup `_name` suffixes (e.g., `primarycontactid_name`)
- Calculated fields (`is_calculated: true`)
- Rollup fields (`aggregate_type` present)
### Global Option Sets
Define reusable option sets in `metadata/optionsets/global_optionsets.yaml`:
```yaml
global_optionsets:
- schema_name: new_customer_status
display_name: Customer Status
options:
- value: 1
label_zh: Potential Customer
label_en: Potential
```
Reference in table definitions:
```yaml
attributes:
- name: status
type: Picklist
option_set_ref: new_customer_status
```
## Quick Start
### Install Dependencies
```bash
cd power-platform-agent
pip install -r requirements.txt
```
### Configure Environment Variables
```bash
export DEV_TENANT_ID="your-tenant-id"
export DEV_CLIENT_ID="your-client-id"
export DEV_CLIENT_SECRET="your-client-secret"
```
### Configure MCP Server in Claude Code
Add to `.mcp.json`:
```json
{
"mcpServers": {
"power-platform": {
"command": "python",
"args": ["{your_path}/power-platform-agent/framework/mcp_serve.py"],
"env": {
"TENANT_ID": "${TENANT_ID}",
"CLIENT_ID": "${CLIENT_ID}",
"CLIENT_SECRET": "${CLIENT_SECRET}"
}
}
}
}
```
Or use installed package:
```json
{
"mcpServers": {
"power-platform": {
"command": "pp-mcp"
}
}
}
```
## Guides
### 🔐 Authentication and Connection
```
# Connect to development environment
Connect to dev environment
# View connection status
View current connection status
# Switch environments
Switch to test environment
# Disconnect
Logout from current environment
```
### 📋 Metadata Management
```
# Create table (natural language description)
Create a customer table with the following fields:
- Customer Number (String, required, primary name)
- Contact Phone (String)
- Account Balance (Money, precision 2)
- Customer Status (Picklist: Active/Inactive/Closed)
# Validate metadata
Validate metadata/tables/customer.yaml format
# Apply to Dataverse
Apply customer table to Dataverse
# Export metadata
Export account table as YAML to output/ directory
```
### 🏷️ Naming Conversion
```
# Convert schema name
Convert "CustomerAccountNumber" to lowercase schema_name
# Output: new_customer_account_number
# Batch conversion
Convert the following field names to schema_name:
- AccountBalance
- CustomerType
- IsActive
# Validate naming
Validate if "new_customer_account" meets naming rules
# View naming rules
Display current naming rule configuration
```
### 🔌 Plugin Management
```
# Build plugin
Build plugins/AccountPlugin/AccountPlugin.csproj
# Deploy plugin
Deploy plugins/AccountPlugin/bin/Release/net462/AccountPlugin.dll
# Register step
Register a step for AccountPlugin:
- Entity: account
- Message: Create
- Stage: post-operation
# List steps
List all registered steps for AccountPlugin
# Delete step
Delete specified step
```
### 📦 Solution Management
```
# Export solution
Export MySolution_Dev solution
# Import solution
Import solutions/MySolution.zip to test environment
# Compare differences
Compare local metadata/ with cloud MySolution differences
# Bi-directional sync
Perform bi-directional sync from local to cloud
# View sync status
View current sync status
```
## Example Workflows
### Workflow 1: Create New Table
```
1. Edit metadata/tables/product.yaml
↓
2. Validate: Validate product.yaml
↓
3. Check naming: Check if naming meets rules
↓
4. Apply: Apply product table to Dataverse
↓
5. Confirm: View creation result
```
### Workflow 2: Develop Plugin
```
1. Write C# plugin code
↓
2. Configure plugin_config.yaml
↓
3. Build: Build plugin project
↓
4. Deploy: Deploy assembly
↓
5. Register: Register Plugin Step
↓
6. Test: Test in Dataverse
```
### Workflow 3: Form Design
```
1. Create form definition YAML
↓
2. Configure tabs and sections
↓
3. Add fields to cells
↓
4. Associate Web Resources
↓
5. Apply to Dataverse
```
## Chat Examples
### Scenario: Create Account Table
```
You: I need to create a bank account table
Agent: Okay, I'll help you create a bank account table. Please tell me what fields you need?
You: I need account number, account type (savings/checking), balance, and opening date
Agent: Alright. I'll create a account table for you with the following fields:
- accountNumber (Account Number) - String type
- accountType (Account Type) - Picklist
- balance (Balance) - Money type
- openedDate (Opening Date) - DateTime type
Generating YAML metadata...
Validating schema...
Applying naming conversion (account → new_account)...
Applying to Dataverse...
✓ Table created successfully! schema_name: new_account
```
### Scenario: Fix Naming Issue
```
You: Is there a problem with this field name: CustomerAccount_123?
Agent: Let me check...
Check result:
✗ Does not meet naming rules
Issues:
- Contains illegal characters "_123"
- Suggestion: use new_customer_account_123 or new_customer_account123
Do you want me to help convert it?
```
### Scenario: Plugin Deployment
```
You: I modified the plugin code, help me redeploy
Agent: Okay, processing:
1. Detected plugin code change
2. Building...
✓ Build successful: AccountPlugin.dll v1.0.0.1
3. Deploying...
✓ Deployment successful
4. Updating steps...
✓ Step updated successfully
Plugin redeployed and effective!
```
## Advanced Techniques
### 1. Batch Operations
```
Batch convert all property names to schema_name
Batch validate all files under metadata/tables/
Batch deploy Web Resources
```
### 2. Difference Sync
```
Compare local and cloud differences, tell me what needs to be synced
Perform bi-directional sync, preserving local modifications
```
### 3. Listening Mode
```
Enable plugin listening mode, automatic build and deployment
```
### 4. Custom Naming Rules
Edit `config/naming_rules.yaml`:
```yaml
naming:
prefix: "your_prefix" # Modify prefix
schema_name:
style: "camelCase" # Change to camelCase style
```
## Troubleshooting
| Issue | Solution |
|-----|---------|
| Authentication failure | Check environment variable configuration |
| Naming conflict | Use `naming_validate` to check |
| API rate limiting | Wait and retry, system will handle automatically |
| Schema error | Use `metadata_validate` to validate |
| Standard table protection | Confirm if modification is necessary |
## Command Cheat Sheet
| Function | Command/Description |
|-----|----------|
| **Authentication** | |
| Connect environment | `Connect to dev environment` |
| View status | `View connection status` |
| Switch environment | `Switch to test environment` |
| **Metadata** | |
| Create table | `Create a customer table with...` |
| Validate metadata | `Validate customer.yaml` |
| Apply metadata | `Apply customer table to Dataverse` |
| Export metadata | `Export account table as YAML` |
| **Naming** | |
| Convert naming | `Convert "AccountName" to schema_name` |
| Validate naming | `Validate "new_customer" meets rules` |
| View rules | `Display current naming rules` |
| **Plugin** | |
| Build plugin | `Build AccountPlugin.csproj` |
| Deploy plugin | `Deploy AccountPlugin.dll` |
| Register step | `Register plugin step: account/Create/post` |
| **Solution** | |
| Export solution | `Export MySolution` |
| Import solution | `Import MySolution.zip` |
| Compare differences | `Compare local and cloud differences` |
| Sync status | `View sync status` |
| **Data Dictionary** | |
| Generate documentation | `python scripts/generate_data_dictionary.py --all` |
| Install Hooks | `bash scripts/install_hooks.sh` |
## Documentation
- [Architecture Documentation](docs/spec/architecture.md) - System architecture design
- [Metadata Specification](docs/spec/metadata-spec.md) - Metadata definition specification
- [Quick Start](docs/guides/getting-started.md) - Detailed getting started guide
### Additional Documentation
Comprehensive reference information on Microsoft Dataverse and related technologies:
| Resource | Description |
|----------|-------------|
| **[Dataverse Developer Guide](https://learn.microsoft.com/power-apps/developer/data-platform/)** | Complete developer documentation for Microsoft Dataverse |
| **[Dataverse Web API Reference](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/)** | Detailed Web API reference and examples |
| **[Python Azure Identity](https://learn.microsoft.com/python/api/overview/azure/identity-readme)** | Authentication library documentation and credential types |
| **[Power Platform Developer Center](https://learn.microsoft.com/power-platform/developer/)** | Broader Power Platform development resources |
| **[.NET Dataverse SDK](https://learn.microsoft.com/power-apps/developer/data-platform/org-service/overview)** | Official .NET SDK for Microsoft Dataverse |
| **[Python Dataverse SDK Source Code](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/tree/main)** | PowerPlatform Dataverse Client for Python |
## Tech Stack
- **Agent Framework**: Hermes Agent
- **MCP Protocol**: Model Context Protocol
- **Metadata Format**: YAML + JSON Schema
- **Authentication**: MSAL (OAuth 2.0)
- **Plugin Development**: .NET Framework 4.6.2
## License
MIT License
