# acu-mcp (archived — migrated to tuxton-platform)

> **This TypeScript project has been ported to Python and moved into the `tuxton-platform` monorepo as `apps/acu_mcp/`.**
>
> New home: `/home/huyson/develop/tuxton-platform/apps/acu_mcp/`
>
> The port reuses the shared `packages/tuxton_acumatica/` client (OAuth2 + entity REST + OData v3) so `acu_etl` and `acu_mcp` can evolve together. OData v4 tools were dropped from the initial port because the `/ODataV4/` route is currently 406ing at the IIS layer regardless of client — the underlying helpers still exist in `tuxton_acumatica` and can be re-wired as tools when the server-side issue clears.
>
> This directory is kept in place for historical reference but should not receive new work. Any new Acumatica REST integration goes into `apps/acu_mcp/` or `packages/tuxton_acumatica/`.

---

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects Claude to Acumatica ERP for read-only analytics queries.

## Tools

| Tool | Description |
|------|-------------|
| `query_sales_orders` | List and filter sales orders with OData expressions |
| `get_sales_order` | Get a single order with full line item detail |
| `list_inventory_items` | List stock items filtered by class, status, etc. |
| `get_inventory_item` | Get a specific item with warehouse stock quantities |
| `query_shipments` | List and filter shipments |
| `get_shipment` | Get a single shipment with line detail |
| `query_invoices` | List and filter AR invoices |
| `get_invoice` | Get a single invoice with line detail |
| `query_purchase_orders` | List and filter purchase orders |
| `get_purchase_order` | Get a single purchase order with line detail |
| `query_customers` | List and filter customers |
| `get_customer` | Get a single customer with contacts and addresses |
| `list_odata_entities` | Discover all available Generic Inquiry entity sets via OData |
| `query_odata` | Query any Generic Inquiry by name with OData filter, select, orderby, top, skip |

## Prerequisites

- [Node.js](https://nodejs.org) 18.3 or later
- An Acumatica instance with a dedicated service account (see [Acumatica Setup](#acumatica-setup) below)

## Installation

```bash
git clone git@github.com:lycheejello/acu-mcp.git
cd acu-mcp
npm install
npm run build
```

## Configuration

Copy the example env file and fill in your values:

```bash
cp .env.example .env
```

```env
ACU_BASE_URL=https://yourinstance.acumatica.com/YourTenant
# OData URL is derived automatically: {ACU_BASE_URL}/odata/{ACU_COMPANY}
ACU_USERNAME=mcp-user
ACU_PASSWORD=your_password
ACU_COMPANY=YourCompanyLoginName
ACU_ENDPOINT=Default
ACU_VERSION=25.200.001
# Required for OData access (see Acumatica Setup below)
ACU_CLIENT_ID=your_client_id@YourCompanyLoginName
ACU_CLIENT_SECRET=your_client_secret
```

> **Warning:** Use a dedicated service account (e.g. `mcp-user`). Do NOT use your personal Acumatica login.

## Claude Integration

### Claude Code (CLI)

Run once to register the server globally:

```bash
claude mcp add --scope user acumatica \
  -e ACU_BASE_URL=https://yourinstance.acumatica.com/YourTenant \
  -e ACU_USERNAME=mcp-user \
  -e ACU_PASSWORD=your_password \
  -e ACU_COMPANY=YourCompanyLoginName \
  -e ACU_ENDPOINT=Default \
  -e ACU_VERSION=25.200.001 \
  -e ACU_CLIENT_ID=your_client_id@YourCompanyLoginName \
  -e ACU_CLIENT_SECRET=your_client_secret \
  -- node /absolute/path/to/acu-mcp/dist/index.js
```

Restart Claude Code after running this command.

### Claude Desktop — macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "acumatica": {
      "command": "node",
      "args": ["/absolute/path/to/acu-mcp/dist/index.js"],
      "env": {
        "ACU_BASE_URL": "https://yourinstance.acumatica.com/YourTenant",
        "ACU_USERNAME": "mcp-user",
        "ACU_PASSWORD": "your_password",
        "ACU_COMPANY": "YourCompanyLoginName",
        "ACU_ENDPOINT": "Default",
        "ACU_VERSION": "25.200.001",
        "ACU_CLIENT_ID": "your_client_id@YourCompanyLoginName",
        "ACU_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Claude Desktop — Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same structure, using a Windows path:

```json
"args": ["C:\\absolute\\path\\to\\acu-mcp\\dist\\index.js"]
```

Restart Claude Desktop after saving.

### Verify

After restarting, ask Claude:

> *"Show me the last 5 open sales orders"*

Claude should call `query_sales_orders` and return live data.

## Acumatica Setup

### Connected Applications (required for OData)

OData access requires a Connected Application registered in Acumatica. Create one per integration (e.g. one for this MCP server, one for Azure Functions) so credentials can be managed and revoked independently.

In **SM301000** (Connected Applications):

1. Click **+** to add a new application
2. Set **Client Name** (display name only, e.g. `TuxtonTools MCP` or `TuxtonTools ETL`)
3. Leave **Client ID** blank to let Acumatica generate one, or set a custom value
4. Set **Flow** to `Resource Owner Password` — this is the grant type used by the code
5. Save
6. On the **Shared Secrets** tab, click **+**, enter a **Description** (e.g. `acu-mcp-prod`), and click **Generate Secret** — copy the secret password immediately, it will not be shown again
7. Note the **Client ID** and the generated **Shared Secret password** — use these as `ACU_CLIENT_ID` and `ACU_CLIENT_SECRET`

> **Note:** Create separate Connected Applications for each integration. This allows independent credential rotation and audit trails.

### Service Account

In **SM201010** (Users), create a dedicated service account:

1. Set **Login Name** (e.g. `mcp-user`) and a strong password
2. Enable the **Web Service Access** checkbox
3. On the **Roles** tab, assign read-only viewer roles for each module (Sales Orders, Inventory, AR, AP, etc.)
4. Set **Max Number of API Logins** to at least `5` to allow concurrent sessions during development

## Development

```bash
npm run dev    # run with tsx (no build step)
npm run build  # compile TypeScript → dist/
npm start      # run compiled output
```

### Adding a New Entity

1. Create `src/tools/{entity}.ts` and export a `register{Entity}Tools(server: McpServer)` function
2. Call it from `src/tools/index.ts`
3. No other changes needed

## Roadmap

See [PLAN.md](./PLAN.md) for the full architecture and phased development plan.

**Phase 1 (complete):** Core server with 12 REST tools across Sales Orders, Inventory, Shipments, Invoices, Purchase Orders, and Customers.
**Phase 2 (in progress):** OData/GI passthrough done (`list_odata_entities` + `query_odata`); GL balance tools and MCP Resources/Prompts still pending.
**Phase 3:** OAuth 2.0, HTTP/SSE transport, production hardening.