bc-webclient-mcp
Version:
Model Context Protocol (MCP) server for Microsoft Dynamics 365 Business Central via WebUI protocol. Enables AI assistants to interact with BC through the web client protocol, supporting Card, List, and Document pages with full line item support and server
180 lines • 6.83 kB
TypeScript
/**
* Write Page Data MCP Tool
*
* Creates or updates records on a BC page by setting field values.
* Uses the real SaveValue protocol captured from BC traffic.
*
* Usage workflow:
* 1. Call get_page_metadata to open the page
* 2. Call execute_action with "Edit" (for updates) or "New" (for creates)
* 3. Call write_page_data with field values
*/
import { BaseMCPTool } from './base-tool.js';
import type { Result } from '../core/result.js';
import type { BCError } from '../core/errors.js';
import type { IBCConnection } from '../core/interfaces.js';
import type { WritePageDataInput, WritePageDataOutput } from '../types/mcp-types.js';
import type { AuditLogger } from '../services/audit-logger.js';
/**
* MCP Tool: write_page_data
*
* Writes data to a BC page (sets field values on current record).
*
* Prerequisites:
* - Page must be open (call get_page_metadata first)
* - Record must be in edit mode (call execute_action with "Edit" or "New")
*/
export declare class WritePageDataTool extends BaseMCPTool {
private readonly connection;
private readonly bcConfig?;
readonly name = "write_page_data";
readonly description: string;
readonly inputSchema: {
type: string;
properties: {
pageContextId: {
type: string;
description: string;
};
fields: {
oneOf: ({
type: string;
description: string;
additionalProperties: boolean;
items?: undefined;
} | {
type: string;
description: string;
items: {
type: string;
properties: {
name: {
type: string;
};
value: {
type: string[];
description: string;
};
controlPath: {
type: string;
};
};
required: string[];
};
additionalProperties?: undefined;
})[];
};
stopOnError: {
type: string;
description: string;
default: boolean;
};
immediateValidation: {
type: string;
description: string;
default: boolean;
};
subpage: {
type: string;
description: string;
};
lineBookmark: {
type: string;
description: string;
};
lineNo: {
type: string;
description: string;
minimum: number;
};
workflowId: {
type: string;
description: string;
};
};
required: string[];
};
readonly requiresConsent = true;
readonly sensitivityLevel: "medium";
readonly consentPrompt = "Write field values to a Business Central record? This will modify data in your Business Central database.";
constructor(connection: IBCConnection, bcConfig?: {
baseUrl: string;
username: string;
password: string;
tenantId: string;
} | undefined, auditLogger?: AuditLogger);
/**
* Validates and extracts input with field normalization.
* NOTE: write-page-data-tool uses legacy validation due to complex field format normalization.
* Zod migration deferred pending refactoring.
*/
protected validateInput(input: unknown): Result<WritePageDataInput, BCError>;
/**
* Builds a map of field names to metadata from cached LogicalForm.
* Uses ControlParser to extract all fields from the control tree.
*
* @param logicalForm - Cached LogicalForm from pageContext
* @returns Map of field name → FieldMetadata (case-insensitive keys)
*/
private buildFieldMap;
/**
* Validates that a field exists and is editable using cached metadata.
* Provides helpful error messages for common issues.
*
* @param fieldName - Field name to validate
* @param fieldMap - Map of available fields from buildFieldMap()
* @returns Result with field metadata or validation error
*/
private validateFieldExists;
/**
* Executes the tool to write page data.
* Uses legacy validation with field normalization.
*
* Sets field values on the current record using SaveValue interactions.
*/
protected executeInternal(input: unknown): Promise<Result<WritePageDataOutput, BCError>>;
/**
* Finds a repeater (subpage) by name using PageState (preferred) or LogicalForm (fallback).
* Searches by both caption and design name (case-insensitive).
*
* Phase 1: Uses PageState if available, falls back to LogicalForm
* Phase 2: PageState will be required
*/
private findRepeaterBySubpage;
/**
* Builds a field map from repeater column metadata.
* Maps column captions and design names to column metadata.
*/
private buildColumnFieldMap;
/**
* Selects a line in a repeater using SetCurrentRowAndRowsSelection.
* This sets server-side focus to the target row before field updates.
*/
private selectLine;
/**
* Extracts bookmark from DataRefreshChange event (for new line creation).
* BC sends this async event when a new line is inserted with the new bookmark.
*/
private extractBookmarkFromDataRefresh;
/**
* Sets a field value using the SaveValue interaction.
* Uses the real BC protocol captured from traffic.
* Optionally inspects handlers for validation errors.
*
* Supports null values for clearing fields (converted to empty string).
*/
private setFieldValue;
/**
* Updates a PropertyChange in cached handlers with new value from SaveValue response.
* Implements UPSERT logic: updates existing PropertyChange or inserts new one.
* This ensures read_page_data returns fresh values without requiring LoadForm.
*
* @param cachedHandlers - Cached handlers from pageContext
* @param formId - Form ID to match
* @param controlPath - Exact controlPath from SaveValue response (e.g., "server:c[1]/c[1]")
* @param newValue - Updated value to cache
* @returns true if cache was updated/inserted, false if LogicalClientChangeHandler not found
*/
private updateCachedPropertyChange;
}
//# sourceMappingURL=write-page-data-tool.d.ts.map