D365FO-claude-connector: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that enables Claude to interact with Microsoft Dynamics 365 Finance & Operations environments. It supports:

• Multi-environment configuration - Connect to multiple D365 environments (production, UAT, dev)
• Read operations - Query data on all environments
• Write operations - Create/update/delete records on non-production environments only
• Production safety - Production environments are always read-only by design

Build Commands

npm run build    # Compile TypeScript to dist/
npm run dev      # Watch mode - recompile on changes
npm start        # Run the compiled server

No test or lint commands are configured.

Architecture

index.ts (entry)
    ├── EnvironmentManager
    │   ├── D365Client (per environment)
    │   └── MetadataCache (per environment)
    │
    ├── Resources (d365://entities, d365://entity/{name}, d365://enums, d365://queries)
    │   └── Uses default environment's MetadataCache
    │
    └── Tools (all support optional 'environment' parameter)
        ├── Read Tools: describe_entity, execute_odata, aggregate, search_entity, etc.
        └── Write Tools: create_record, update_record, delete_record (non-production only)

Core Components:

• environment-manager.ts - Manages multiple D365Client instances, enforces write guards
• config-loader.ts - Loads JSON config with fallback to legacy env vars
• d365-client.ts - Authenticated OData HTTP client with read/write methods
• auth.ts - TokenManager for OAuth2 client credentials flow with auto-refresh
• metadata-cache.ts - Two-tier metadata loading (fast entity names ~1s, full EDMX ~30-60s) with 24h TTL

Resources (src/resources/) - Schema discovery endpoints for Claude to understand D365 structure

Tools (src/tools/) - Data access operations. Each tool is registered via:

export function register[ToolName]Tool(server: McpServer, envManager: EnvironmentManager): void {
  server.tool("tool_name", "description", { /* Zod schema */ }, async (params, extra) => {
    const client = envManager.getClient(params.environment);
    // ... handler
  });
}