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
117 lines • 3.86 kB
TypeScript
/**
* Business Central LogicalForm Parser
*
* Parses BC WebSocket LogicalForm structures to extract search results,
* form data, and control values.
*
* Based on protocol analysis - see docs/tell-me-search-protocol.md
*
* NOTE: BC27+ uses LogicalClientChangeHandler with DataRefreshChange for search results,
* not the original LogicalForm Value array approach.
*/
import { type Result } from '../core/result.js';
import type { BCError } from '../core/errors.js';
import type { PageSearchResult } from '../types/mcp-types.js';
/**
* BC Handler structure from protocol
*/
export interface BcHandler {
handlerType: string;
parameters?: readonly unknown[];
LogicalForm?: BcLogicalForm;
}
/**
* BC LogicalForm structure
*/
interface BcLogicalForm {
Id?: string;
Children?: BcControl[];
Controls?: BcControl[];
}
/**
* BC Control structure
*/
interface BcControl {
Type?: number;
t?: string;
Value?: unknown[];
Properties?: {
Value?: unknown[];
};
Controls?: BcControl[];
}
/**
* Input can be a handler wrapper or array of handlers
*/
interface HandlerWrapper {
LogicalForm?: BcLogicalForm;
}
/**
* Tell Me search result row structure.
* Based on captured protocol, each result is an array:
* [name, category, objectId, objectType, key, context?, action?, actionKey?]
*/
export interface TellMeSearchResultRow {
/** Page/Report name (e.g., "Customer List") */
name: string;
/** Category (e.g., "List", "Report and analysis") */
category: string;
/** Page/Report ID (e.g., "22") */
objectId: string;
/** Object type (e.g., "Page", "Report") */
objectType: string;
/** Unique key for selection (GUID) */
key: string;
/** Optional contextual description */
context?: string;
/** Optional tooltip/description */
tooltip?: string;
/** Optional action type */
action?: string;
/** Optional action key (GUID) */
actionKey?: string;
}
/**
* Extracts Tell Me search results from a decompressed LogicalForm.
*
* Search results are in a Repeater control (Type 11) at Controls[1].
* Each result is an array with structure: [name, category, id, type, key, ...]
*
* @param logicalForm - Decompressed LogicalForm object
* @returns Array of search result rows
*/
export declare function extractTellMeResults(handlersOrForm: BcHandler[] | HandlerWrapper | null | undefined): Result<TellMeSearchResultRow[], BCError>;
/**
* Converts Tell Me search results to MCP PageSearchResult format.
*
* @param tellMeResults - Parsed Tell Me results
* @returns Array of PageSearchResult objects
*/
export declare function convertToPageSearchResults(tellMeResults: TellMeSearchResultRow[]): PageSearchResult[];
/**
* Gets the form ID from a LogicalForm.
*
* @param logicalForm - Decompressed LogicalForm
* @returns Form ID or undefined
*/
export declare function getFormId(logicalForm: HandlerWrapper | null | undefined): string | undefined;
/**
* Gets the search query value from a Tell Me LogicalForm.
* The search input is at Controls[0]/Controls[0].
*
* @param logicalForm - Decompressed LogicalForm
* @returns Search query string or undefined
*/
export declare function getSearchQuery(logicalForm: HandlerWrapper | null | undefined): string | undefined;
/**
* Extracts Tell Me search results from BC27+ LogicalClientChangeHandler format.
*
* In BC27+, search results are sent as DataRefreshChange, InitializeChange, or
* ControlAddChange updates instead of being embedded in the LogicalForm's Value property.
*
* @param handlers - Array of handlers from decompressed response
* @returns Array of search result rows
*/
export declare function extractTellMeResultsFromChangeHandler(handlers: BcHandler[]): Result<TellMeSearchResultRow[], BCError>;
export {};
//# sourceMappingURL=logical-form-parser.d.ts.map