# Business Central MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A modern MCP server designed for effortless integration with Microsoft Dynamics 365 Business Central, allowing MCP clients to easily access and manage any entity within your Business Central environment. Developed by [Tan Tran](https://www.tantran.dev/).

## Features

- Async interface to Business Central resources via Model Context Protocol (MCP)
- Optimized HTTP request handling
- Tools for managing sales orders and more

## Project Structure

```
main.py                  # Entrypoint for the MCP server
requirements.txt         # Python dependencies
src/
    business_central_client.py
    modes.py
    sale_order_tools.py
    # ...other tool modules
LICENSE
README.md
```

## Setup

1. Cài đặt Poetry (nếu chưa có):

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

2. Đăng ký ứng dụng trong Azure Portal (Microsoft Entra ID) để lấy Client ID, Tenant ID, và Client Secret (xem docs/enabling-api.md).
3. Cấp quyền API cho app (Business Central, Application permissions, ...).
4. Copy `.env.example` thành `.env` và điền thông tin cấu hình:

```env
BC_API_URL=https://api.businesscentral.dynamics.com/v2.0/<environment>
BC_TENANT_ID=<your-tenant-id>
BC_CLIENT_ID=<your-client-id>
BC_CLIENT_SECRET=<your-client-secret>
BC_COMPANY=<company-name>
BC_SCOPE=https://api.businesscentral.dynamics.com/.default
ENABLE_RESOURCE_TOOLS=true  # Enable or disable resource tools registration (true/false)
```

5. Cài dependencies bằng Poetry:

```bash
poetry install
```

6. (Tùy chọn) Nếu muốn vào môi trường ảo Poetry:

```bash
poetry shell
```

7. Chạy server:

```bash
poetry run python main.py
```

## Environment Variables

- `BC_API_URL`: Business Central API base URL
- `BC_TENANT_ID`: Azure AD tenant ID
- `BC_CLIENT_ID`: Application (client) ID
- `BC_CLIENT_SECRET`: Client secret
- `BC_COMPANY`: Your Business Central company name
- `BC_SCOPE`: OAuth2 scope (default: https://api.businesscentral.dynamics.com/.default)
- `ENABLE_RESOURCE_TOOLS`: Enable or disable resource tools registration (true/false). If set to `false`, resource endpoints will not be registered.

## Tool Registration

Tools are registered in `main.py`:

```python
from src.tools.sales_order_tools import register_sales_order_tools
register_sales_order_tools(mcp)
```

Add new tools by creating modules in `src/` and registering them in `main.py`.

## Development

- All business logic is in `src/`.
- Add new tools by creating new modules in `src/` and registering them in `main.py`.

## Sales Order Support

### Create Sales Order (Tool: `create_sales_order`)

This server supports creating new sales orders in Business Central via the MCP tool `create_sales_order`.

**Input parameters:**

- `customer_number` (str): Customer number in Business Central
- `items` (list of str): List of item IDs to add to the order
- `quantities` (list of float): List of quantities for each item (must match length of `items`)
- `order_date` (str, optional): Order date in format `YYYY-MM-DD`

**Example tool call:**

```json
{
  "tool": "create_sales_order",
  "arguments": {
    "customer_number": "10000",
    "items": ["ITEM001", "ITEM002"],
    "quantities": [2, 5],
    "order_date": "2025-07-28"
  }
}
```

- The tool will create a sales order header and add lines for each item/quantity pair.
- Returns the created sales order object if successful.

See [docs/sale-order.md](docs/sale-order.md) for API details and field mapping.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Copyright (c) 2025 Tan Tran (me@tantran.dev, www.tantran.dev)