pcf-toolkit 0.2.5

PCF toolkit CLI for manifest authoring and local proxy development.

Developer-first toolkit for authoring Power Apps PCF manifests and running a local proxy that removes the publish loop.

For detailed guides, API reference, and examples, see the documentation.

Lifecycle
Core Stack
Navigation

1. Install (recommended): uv tool install pcf-toolkit@latest
2. Initialize a proxy config: pcf-toolkit proxy init
3. Build your control so out/controls/{PCF_NAME} exists.
4. Start the proxy: pcf-toolkit proxy start MyComponent

Run without install (useful in CI or scripts):

uvx pcf-toolkit --help

Requirements:

• Python 3.13
• uv (recommended for install/run)
• mitmproxy (required for proxy mode; auto-installed if auto_install: true)
• Optional: Microsoft PAC CLI (pac) for environment discovery

Feature Badge	Details
	Intercepts PCF webresource requests and serves your local build without publishing.
	Strict schema validation with readable errors.
	Stable, ordered XML output for clean diffs.
	Import legacy XML and keep authoring in YAML or JSON.
	Export JSON Schema for editor validation and linting.
	Diagnoses ports, mitmproxy, certs, and dist paths.

Proxy config (pcf-proxy.yaml)

Top-level keys:

Name	Required	Default	Format	Description
project_root	no	-	path	Project root for global configs.
crm_url	no	-	URL	Power Apps environment URL (required for auto-launch).
expected_path	no	/webresources/{PCF_NAME}/	string	Webresource path template to match.
proxy	no	-	object	Proxy endpoint settings.
http_server	no	-	object	Local HTTP server settings.
bundle	no	-	object	Build output location template.
browser	no	-	object	Browser preference and path.
mitmproxy	no	-	object	mitmproxy path override.
environments	no	-	list	Named environments from PAC.
open_browser	no	true	bool	Auto-launch browser with proxy settings.
auto_install	no	true	bool	Auto-install mitmproxy if missing.

proxy:

Name	Required	Default	Format	Description
host	no	127.0.0.1	string	mitmproxy listen host.
port	no	8080	int	mitmproxy listen port.

http_server:

Name	Required	Default	Format	Description
host	no	127.0.0.1	string	Local file server host.
port	no	8082	int	Local file server port.

bundle:

Name	Required	Default	Format	Description
dist_path	no	out/controls/{PCF_NAME}	path	Build output template for the control.

browser:

Name	Required	Default	Format	Description
prefer	no	chrome	string	Browser preference: chrome or edge.
path	no	-	path	Explicit browser binary path.

mitmproxy:

Name	Required	Default	Format	Description
path	no	-	path	Explicit mitmproxy or mitmdump path.

environments:

Name	Required	Default	Format	Description
name	yes	-	string	Friendly environment name.
url	yes	-	URL	Environment base URL.
active	no	false	bool	Preferred environment when multiple exist.

Manifest authoring

• Author manifests in YAML or JSON.
• Generate XML with pcf-toolkit generate.
• Import existing XML with pcf-toolkit import-xml.
• Validate with pcf-toolkit validate.

Environment variables

Used internally (set automatically by the CLI):

Name	Required	Default	Format	Description
PCF_COMPONENT_NAME	yes	-	string	Component name passed to the proxy addon.
PCF_EXPECTED_PATH	no	/webresources/{PCF_NAME}/	string	Path template used by the redirect addon.
HTTP_SERVER_HOST	no	127.0.0.1	string	Local HTTP server host.
HTTP_SERVER_PORT	no	8082	int	Local HTTP server port.

• Provider: GitHub Actions (.github/workflows/ci.yml).
• Triggers: pushes to main, PRs targeting main, and tags starting with v.
• Build steps: install uv, install Python 3.13, sync deps, build schema snapshot and JSON schema.
• Guardrail: git diff --exit-code ensures generated schema artifacts are committed.
• Tests: pytest with coverage report (terminal output only).
• Publish: on tags v*, builds and publishes to PyPI with uv publish.

• Optional: Microsoft PAC CLI (pac) for environment discovery and selection.
• The proxy expects your control to build into bundle.dist_path (defaults to out/controls/{PCF_NAME}).
• The proxy intercepts /webresources/{PCF_NAME}/... requests and serves files from your local build output.

• The toolkit does not manage authentication.
• PAC CLI uses your existing Power Platform login for environment discovery.
• The proxy does not store tokens or credentials; it only rewrites webresource requests.

• No telemetry is emitted by default.
• No analytics or event collection is built into the CLI.

• This project does not require a database.

• Use pcf-toolkit proxy doctor to check ports, mitmproxy, certs, and dist paths.
• Active proxy sessions store PID metadata in .pcf-toolkit/proxy.session.json.
• Detached runs write logs to .pcf-toolkit/proxy.log.

Install dev dependencies:

uv sync --extra dev

Run tests:

uv run --python 3.13 pytest

Regenerate schema artifacts:

uv run --python 3.13 --script scripts/build_schema_snapshot.py
uv run --python 3.13 --script scripts/build_json_schema.py

If you run scripts/extract_spec.py, install browser binaries first:

uv run --python 3.13 python -m playwright install

Build a wheel locally:

uv build

• Python 3.13 available.
• schemas/pcf-manifest.schema.json and data/schema_snapshot.json regenerated.
• pcf-toolkit proxy doctor passes for your target component.
• CI pipeline is green and release tag is created for publishing.

• CLI: Typer-based commands in pcf_toolkit.cli and pcf_toolkit.proxy.cli.
• Manifest tooling: Pydantic models validate YAML/JSON and serialize deterministic XML.
• Proxy workflow: mitmproxy addon rewrites PCF webresource requests to a local http.server instance.
• Schema pipeline: scripts extract and normalize Microsoft Learn references into JSON Schema and snapshots.

Command	Purpose
pcf-toolkit validate <manifest>	Validate YAML/JSON against the manifest schema.
pcf-toolkit generate <manifest> -o ControlManifest.Input.xml	Generate deterministic XML.
pcf-toolkit import-xml <ControlManifest.Input.xml>	Convert XML to YAML/JSON.
pcf-toolkit export-json-schema -o schemas/pcf-manifest.schema.json	Export JSON Schema.
pcf-toolkit export-schema -o data/schema_snapshot.json	Export schema snapshot.
pcf-toolkit proxy init	Create or update proxy config.
pcf-toolkit proxy start <Component>	Start proxy session.
pcf-toolkit proxy stop	Stop proxy session.
pcf-toolkit proxy doctor	Diagnose proxy prerequisites.

• Manifest invalid: run pcf-toolkit validate and fix fields reported in the error table.
• Dist path missing: run your PCF build or update bundle.dist_path in pcf-proxy.yaml.
• Config not found: run pcf-toolkit proxy init or pass --config.
• mitmproxy missing: run pcf-toolkit proxy doctor --fix or set mitmproxy.path.
• mitmproxy CA cert missing: run pcf-toolkit proxy doctor and follow OS-specific guidance.
• Browser did not open: set crm_url and check browser.prefer or browser.path.
• Ports already in use: change proxy.port or http_server.port.

• License: LICENSE.md (Vectorfy Co Community Use License).
• No secrets are stored in the repo; use placeholders in configs.
• Some badges use stand-in icons (Typer uses FastAPI, Proxy uses Server Fault).