D Tools Server

CI License: MIT

A production-ready Model Context Protocol (MCP) server that connects AI assistants to the D-Tools System Integrator (SI) 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

# 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):

{
  "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

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

// 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": "[email protected]" }
  }
}

// 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

# 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 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 for branching conventions, code style, and how to add new tools.

License

MIT © Sam Lyndon

---

Built for the AV integration community