D365 Finance & Operations Development Assistant

Expert assistant for developing and maintaining the d365fo-client Python package - a comprehensive client library for Microsoft Dynamics 365 Finance & Operations (D365 F&O).

Project Overview

This package provides:

**Tech Stack**: Python >=3.13, uv package manager, async/await throughout, comprehensive type hints

Instructions

When assisting with d365fo-client development, follow these guidelines:

1. Project Structure Understanding

The codebase follows this architecture:

2. Package Management with uv

Always use uv commands for dependency management:

3. Development Workflow

Use make commands for common tasks (cross-platform support):

**Unix/Linux/macOS:**

```bash

make dev-setup # Initial setup

make dev # Quick check (format + lint + test)

make quality-check # Comprehensive checks

```

**Windows PowerShell:**

```powershell

.\make.ps1 dev-setup

.\make.ps1 dev

.\make.ps1 quality-check

```

**Available targets**: dev-setup, dev, quality-check, test, test-coverage, format, lint, type-check, build, publish-test, publish, clean, security-check, info

4. Code Quality Standards

5. Testing Framework

**Unit Testing:**

**Integration Testing (Multi-Tier):**

Three test levels available:

1. **Mock Server** (`mock`) - Fast, isolated testing

- Local aiohttp server simulating D365 F&O API

- No external dependencies

- Ideal for CI/CD

2. **Sandbox** (`sandbox`) - DEFAULT, realistic validation

- Tests against real D365 F&O test environments

- Azure AD authentication integration

- Status: 17/17 tests passing ✅

3. **Live** (`live`) - Production validation

- Performance benchmarking

- Final deployment validation

**Running integration tests:**

```powershell

PowerShell automation

.\tests\integration\integration-test-simple.ps1 test-sandbox -VerboseOutput

.\tests\integration\integration-test-simple.ps1 test-mock

.\tests\integration\integration-test-simple.ps1 coverage

Direct Python

python tests/integration/test_runner.py sandbox --verbose

```

Configure via `.env` file in `tests/integration/`:

```bash

INTEGRATION_TEST_LEVEL=sandbox

D365FO_SANDBOX_BASE_URL=https://your-env.dynamics.com

D365FO_CLIENT_ID=your-client-id

D365FO_CLIENT_SECRET=your-secret

D365FO_TENANT_ID=your-tenant-id

```

6. CLI Development Practices

**Command Structure:**

**Configuration Management:**

**Output Formatting:**

**CLI Implementation Pattern:**

```python

class CLIManager:

async def execute_command(self, args: argparse.Namespace) -> int:

# Setup -> Create client -> Route -> Handle errors

# Return 0 success, 1 error

```

7. MCP Server Development

**Architecture (FastMCP Framework):**

**Tool Categories (49 total tools):**

**Adding New Tools:**

1. Identify appropriate mixin or create new one

2. Add method with `@self.mcp.tool()` decorator

3. Use proper type hints and docstrings

4. Handle errors gracefully

5. Add tests for new tools

**Mixin Example:**

```python

class ConnectionToolsMixin(BaseToolsMixin):

def register_connection_tools(self):

@self.mcp.tool()

async def d365fo_test_connection(profile: str = "default") -> Dict[str, Any]:

"""Test connection to D365 F&O environment."""

# Implementation

```

8. Dependencies Management

9. Documentation Standards

10. Entry Points

Key Principles

1. **Async-First**: Use async/await throughout the codebase

2. **Type Safety**: Comprehensive type hints on all functions

3. **Test Coverage**: Aim for >90% coverage with unit + integration tests

4. **Multi-Tier Testing**: Use mock/sandbox/live testing strategy

5. **FastMCP Mixins**: Organize MCP tools by functional category

6. **Cross-Platform**: Support Unix, Windows CMD, and PowerShell

7. **Configuration Flexibility**: CLI args > Env vars > Profiles > Defaults

8. **Error Handling**: Graceful error handling with proper logging

9. **Documentation**: Comprehensive docs and docstrings

10. **Backward Compatibility**: Maintain existing APIs without breaking changes

Common Tasks

**Add a new dependency:**

```bash

uv add requests # Runtime

uv add --group dev pytest-cov # Dev dependency

```

**Run quality checks:**

```bash

make quality-check # Unix

.\make.ps1 quality-check # Windows PowerShell

```

**Run integration tests:**

```powershell

.\tests\integration\integration-test-simple.ps1 test-sandbox -VerboseOutput

```

**Build and publish:**

```bash

make build

make publish-test # Test PyPI first

make publish # Production PyPI

```

**Add new MCP tool:**

1. Choose/create appropriate mixin in `src/d365fo_client/mcp/mixins/`

2. Add `@self.mcp.tool()` decorated async method

3. Register in mixin's registration method

4. Add tests in `tests/test_mcp_server.py`