# D-Tools MCP Server

[![CI](https://github.com/Saml1211/D-Tools-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/Saml1211/D-Tools-MCP-Server/actions)
![Tests](https://img.shields.io/badge/Tests-172%2B%20passing-brightgreen)
![Node.js](https://img.shields.io/badge/node.js-%3E%3D%2018-brightgreen)
![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)
![MCP](https://img.shields.io/badge/MCP-Protocol-orange)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI assistants to the [D-Tools System Integrator (SI)](https://d-tools.com) platform. Designed for professional audio-visual (AV) integrators, it exposes **25 tools** covering the full SI workflow — projects, clients, catalogs, tasks, service orders, purchase orders, and health monitoring — directly to Claude Desktop, Cursor, and any other MCP-compatible host.

## Why D-Tools SI + MCP?

D-Tools SI manages the complete AV project lifecycle: quoting, equipment tracking, task management, and client records. Its API uses a queue-based publish/subscribe model where integrators publish changes and consumers poll or receive webhooks.

MCP standardises how AI agents call external tools. Combining the two means Claude (or any AI host) can look up a project, analyse its profitability, create a task, or check a purchase order — all through natural language, with no custom glue code.

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/Saml1211/D-Tools-MCP-Server.git
cd D-Tools-MCP-Server
npm install

# 2. Configure
cp .env.example .env
# Edit .env — set DTOOLS_API_URL and DTOOLS_API_KEY

# 3. Build and run
npm run build
npm start
```

The server connects over stdin/stdout and is immediately usable by any MCP host.

### Add to Claude Desktop

Edit your Claude Desktop config (`%APPDATA%/Claude/config.json` on Windows, `~/Library/Application Support/Claude/config.json` on macOS):

```json
{
  "mcpServers": {
    "d-tools": {
      "command": "node",
      "args": ["/path/to/D-Tools-MCP-Server/dist/index.js"],
      "env": {
        "DTOOLS_API_URL": "https://api.d-tools.com",
        "DTOOLS_API_KEY": "your-dtools-api-key"
      }
    }
  }
}
```

Restart Claude Desktop and try: *"List all active projects"* or *"Analyse the profitability of project 12345"*.

### Docker

```bash
docker build -t dtools-mcp .

docker run -it --rm \
  -e DTOOLS_API_URL=https://api.d-tools.com \
  -e DTOOLS_API_KEY=your-dtools-api-key \
  dtools-mcp
```

## Features

| Feature | Detail |
|---|---|
| **25 MCP tools** | Projects, clients, catalogs, tasks, service orders, purchase orders, health |
| **Strict validation** | Every tool input validated with Zod before hitting the API |
| **Resilient HTTP** | Axios with exponential retry/backoff for transient failures |
| **Rate limiting** | Token-bucket limiter protects SI API quotas |
| **Webhook support** | Optional listener with HMAC SHA-256 signature verification |
| **Structured logging** | Pino JSON logs to stderr; sensitive headers redacted |
| **172+ tests** | Unit, MCP-protocol, dispatch, and health suites — all offline |

## Tools Reference

| Category | Tool | Purpose |
|---|---|---|
| **Projects** | `get_project` | Fetch a project or change order by ID |
| | `list_projects` | Paginated list with search and status filters |
| | `create_project` | Publish a new project with optional line items |
| | `update_project` | Update any combination of fields |
| | `archive_project` | Archive or unarchive one or more projects |
| | `analyze_project_profitability` | Cost, revenue, profit and gross margin from line items |
| | `get_equipment_summary` | Equipment totals grouped by category |
| **Clients** | `get_client` | Retrieve a client by ID |
| | `list_clients` | Paginated list with search |
| | `create_client` | Publish a new client record |
| | `update_client` | Update contact or company details |
| **Catalogs** | `get_catalog` | Fetch a product catalog entry by ID |
| | `search_products` | Search by keyword across the product catalog |
| | `list_catalogs` | Paginated catalog listing |
| **Tasks** | `get_task` | Retrieve a task by ID |
| | `list_tasks` | List tasks, optionally filtered by project |
| | `create_task` | Publish a new task |
| | `update_task` | Update status, assignee, or due date |
| **Service Orders** | `get_service_order` | Retrieve a service order by ID |
| | `list_service_orders` | List with client and progress filters |
| | `create_service_order` | Publish a new service order |
| **Purchase Orders** | `get_purchase_order` | Retrieve a purchase order by ID |
| | `list_purchase_orders` | List with vendor and status filters |
| **Health** | `health_check` | API connectivity, config, webhooks, and rate-limiter status |
| | `server_status` | Uptime, memory usage, and Node.js version |

### Example tool calls

```json
// Fetch a project
{ "name": "get_project", "arguments": { "id": "12345" } }

// Analyse profitability
{ "name": "analyze_project_profitability", "arguments": { "id": "12345" } }

// Create a client
{
  "name": "create_client",
  "arguments": {
    "client": { "name": "Acme Corp", "email": "info@acme.example" }
  }
}

// Search catalog
{ "name": "search_products", "arguments": { "searchText": "65 inch display" } }
```

## Configuration

Copy `.env.example` to `.env` and set the variables:

| Variable | Required | Description |
|---|---|---|
| `DTOOLS_API_URL` | Yes | Base URL of the SI API (no trailing slash) |
| `DTOOLS_API_KEY` | Yes | Your SI API key (`X-DTSI-ApiKey` header) |
| `WEBHOOK_PORT` | No | Enable the webhook listener on this port |
| `WEBHOOK_SECRET` | No | HMAC-SHA256 secret for webhook signature verification |
| `LOG_LEVEL` | No | Pino log level — `trace` / `debug` / `info` / `warn` / `error` / `fatal` (default: `info`) |

Get your API key from the D-Tools SI desktop app under **Settings → API Integration**.

## Development

```bash
# Install dependencies
npm install

# Type-check
npx tsc --noEmit

# Lint
npm run lint

# Run offline test suite
npm test

# Run with coverage
npm run test:ci

# Run MCP-protocol tests only
npm run test:mcp

# Run tests against the local mock API
node mock-api/server.js          # Terminal 1
cp .env.test .env && npm test    # Terminal 2
```

See [TESTING.md](TESTING.md) for the full testing guide, including integration tests and the mock API server.

## Project Structure

```
src/
├── index.ts                 # Entry point — creates McpServer, registers tools, starts stdio transport
├── config.ts                # Zod-validated environment configuration
├── logger.ts                # Pino logger (sensitive header redaction)
├── lib/
│   ├── dtools-client.ts     # Axios HTTP client with retry/backoff
│   ├── auth.ts              # API key auth helper
│   ├── errors.ts            # Custom error classes
│   ├── rate-limiter.ts      # Token-bucket rate limiter
│   ├── request-context.ts   # Async-local-storage request tracing
│   ├── webhook-handlers.ts  # SI event handlers
│   └── webhook-server.ts    # Optional HMAC-verified HTTP listener
├── tools/
│   ├── projects.ts          # 7 project tools
│   ├── clients.ts           # 4 client tools
│   ├── catalogs.ts          # 3 catalog tools
│   ├── tasks.ts             # 4 task tools
│   ├── service-orders.ts    # 3 service order tools
│   ├── purchase-orders.ts   # 2 purchase order tools
│   └── health.ts            # 2 health tools
├── types/
│   ├── dtools.ts            # SI domain types
│   └── mcp.ts               # MCP response types
└── __tests__/               # Vitest test suite (172+ tests, all offline)
```

## Architecture Notes

### Publish/Subscribe model

The SI API uses a queue-based model: `Publish/…` endpoints write changes, `Subscribe/…` endpoints read them. When listing entities you may need to paginate to drain the full queue — use `pageNumber` and `pageSize` on any list tool.

### Security

- The API key is loaded from `.env` and injected as `X-DTSI-ApiKey` on every request. The Pino logger redacts this header so it never appears in log output.
- If webhooks are enabled, the server verifies every incoming request's `x-signature` header with HMAC SHA-256 before dispatching.
- All tool inputs are validated by Zod before any API call is made.

### Troubleshooting

| Symptom | Fix |
|---|---|
| Tools not listed in host | Ensure the server process started and logged `D-Tools MCP server started`. Check `DTOOLS_API_KEY`. |
| 401 Unauthorized | Invalid or missing `DTOOLS_API_KEY` in `.env`. |
| Empty list responses | SI only returns data that has been published to the queue. Use `searchText` or narrow filters. |
| Repeated timeouts | The client retries 3× with exponential backoff. Check network access to `api.d-tools.com`. |

## Contributing

Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for branching conventions, code style, and how to add new tools.

## License

[MIT](LICENSE) © Sam Lyndon

---

*Built for the AV integration community*