@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
282 lines • 9.27 kB
TypeScript
/**
* TypeScript type definitions for MCP-AQL (MCP Agent Query Language)
* These types match the GraphQL schema defined in schema.graphql
*/
/**
* Element types supported by DollhouseMCP.
* These correspond to the 6 core element types in the system.
*/
export declare enum ElementType {
Persona = "persona",
Skill = "skill",
Template = "template",
Agent = "agent",
Memory = "memory",
Ensemble = "ensemble"
}
export declare function normalizeMCPAQLElementType(value: string): ElementType | undefined;
/**
* Input for all MCP-AQL operations.
* The operation field determines which handler function is invoked.
*/
export interface OperationInput {
/**
* The operation to perform (e.g., 'create_element', 'list_elements')
*/
operation: string;
/**
* Element type for element operations (snake_case, Issue #290)
*/
element_type?: ElementType;
/**
* Element type for element operations (camelCase, legacy)
* @deprecated Use element_type instead
*/
elementType?: ElementType;
/**
* Operation-specific parameters as a JSON object
*/
params?: Record<string, unknown>;
}
/**
* Batch request containing multiple operations to execute in sequence.
* Operations are executed in order, and failures do not stop execution.
*/
export interface BatchRequest {
/**
* Array of operations to execute in sequence
*/
operations: Array<{
operation: string;
element_type?: ElementType;
elementType?: ElementType;
params?: Record<string, unknown>;
}>;
}
/**
* Individual result in a batch operation response
*/
export interface BatchOperationResult {
/**
* Index of the operation in the batch (0-based)
*/
index: number;
/**
* Operation that was executed
*/
operation: string;
/**
* Result of the operation
*/
result: OperationResult;
}
/**
* Result of a batch operation request.
* success=false when the batch itself is rejected (e.g. exceeds size limit).
*/
export interface BatchResult {
success: boolean;
/**
* Array of individual operation results
*/
results: BatchOperationResult[];
/**
* Summary statistics
*/
summary: {
total: number;
succeeded: number;
failed: number;
};
/** Batch-level error message (present when success=false) */
error?: string;
/** Request correlation and timing metadata for the overall batch (Issue #301) */
_meta: ResponseMeta;
}
/**
* Successful operation result.
* Data contains the operation-specific result payload.
*/
export interface OperationSuccess {
success: true;
/** Operation-specific result payload */
data: unknown;
/** Request correlation and timing metadata (Issue #301) */
_meta: ResponseMeta;
error?: never;
}
/**
* Failed operation result.
* Error contains a human-readable error message.
*/
export interface OperationFailure {
success: false;
/** Human-readable error message */
error: string;
/** Request correlation and timing metadata (Issue #301) */
_meta: ResponseMeta;
data?: never;
}
/**
* Standard result type for all MCP-AQL operations.
* Discriminated union ensures type safety:
* - success: true → data is present, error is absent
* - success: false → error is present, data is absent
*/
export type OperationResult = OperationSuccess | OperationFailure;
/**
* Response metadata for request correlation and timing.
* Included in every operation response to enable log correlation and performance monitoring.
* Issue #301: Request IDs and distributed tracing support.
*/
export interface ResponseMeta {
/** Correlation ID from ContextTracker (matches correlationId in log entries) */
requestId: string;
/** Wall-clock milliseconds for the operation */
durationMs: number;
/** ISO 8601 response timestamp */
timestamp: string;
}
/**
* Operation categories mapped to their safety annotations
*/
export interface OperationSafety {
readOnly: boolean;
destructive: boolean;
}
/**
* Map of endpoint names to their safety annotations
*/
export declare const ENDPOINT_SAFETY: Record<string, OperationSafety>;
/**
* Operation names grouped by endpoint
*/
export declare const ENDPOINT_OPERATIONS: {
readonly create: readonly ["create_element", "import_element", "addEntry", "activate_element"];
readonly read: readonly ["list_elements", "get_element", "search_elements", "query_elements", "get_active_elements", "validate_element", "render", "export_element", "deactivate_element", "introspect"];
readonly update: readonly ["edit_element"];
readonly delete: readonly ["delete_element", "execute_agent", "clear"];
};
/**
* Type guard to check if a string is a valid ElementType.
* Accepts both singular ("memory") and plural ("memories") forms.
* Issue #433: Users and LLMs naturally use either form.
*/
export declare function isElementType(value: unknown): value is ElementType;
/**
* Type guard to check if an object is a valid OperationInput
* Issue #290: Accepts both element_type (snake_case) and elementType (camelCase)
*/
export declare function isOperationInput(value: unknown): value is OperationInput;
/**
* Type guard to check if an object is a valid OperationResult
*/
export declare function isOperationResult(value: unknown): value is OperationResult;
/**
* Type guard to check if an object is a valid BatchRequest
*/
export declare function isBatchRequest(value: unknown): value is BatchRequest;
/**
* Legacy tool format that some LLMs might generate.
* This is NOT documented but silently supported for resilience.
*
* NOTE: Only one of args/params should be used; if both are present,
* args takes precedence.
*/
interface LegacyToolFormat {
tool: string;
/** Operation arguments (takes precedence over params) */
args?: Record<string, unknown>;
/** Operation parameters (used only if args not present) */
params?: Record<string, unknown>;
}
/**
* Type guard to check if input is in legacy tool format.
* Supports: { tool: 'operation_name', args: {...} }
* or: { tool: 'operation_name', params: {...} }
*
* INTERNAL USE ONLY - Not documented to users.
* Issue #205: Silent JSON fallback for edge cases.
*/
export declare function isLegacyToolFormat(value: unknown): value is LegacyToolFormat;
/**
* Convert legacy tool format to proper OperationInput.
*
* PRECEDENCE RULES:
* 1. If `args` is present (even if empty {}), use `args`
* 2. Otherwise, if `params` is present, use `params`
* 3. If neither present, use empty object {}
*
* EDGE CASE: { tool: 'x', args: { a: 1 }, params: { b: 2 } }
* Result: { operation: 'x', params: { a: 1 } } (args wins, params ignored)
*
* INTERNAL USE ONLY - Not documented to users.
* Issue #205: Silent JSON fallback for edge cases.
*/
export declare function convertLegacyToMCPAQL(legacy: LegacyToolFormat): OperationInput;
/**
* Input format types for internal metrics tracking.
* Issue #205: Silent JSON fallback for edge cases.
*/
export type InputFormat = 'proper' | 'legacy_converted' | 'permission_prompt_protocol' | 'invalid';
/**
* Internal metrics for input format tracking.
* Not exposed to users; for monitoring purposes only.
*
* High legacy_converted ratio might indicate:
* - Documentation issues
* - Model confusion
* - Need for better prompt engineering
*/
export declare class InputFormatMetrics {
private static counts;
/**
* Record an input format event
*/
static record(format: InputFormat): void;
/**
* Get current metrics snapshot
*/
static getMetrics(): Readonly<Record<InputFormat, number>>;
/**
* Reset metrics (mainly for testing)
*/
static reset(): void;
}
/**
* Parse and normalize operation input, handling multiple formats.
*
* Supports:
* 1. Proper MCP-AQL format: { operation: 'x', params: {...} }
* 2. Legacy tool format: { tool: 'x', args: {...} } (silent fallback)
*
* Issue #205: Silent JSON fallback for edge cases.
*
* @param input - Raw input to parse
* @returns Normalized OperationInput or null if invalid
*/
export declare function parseOperationInput(input: unknown): OperationInput | null;
/**
* Generate a diagnostic summary of invalid input for error messages.
* Helps agents and developers understand what was actually received when
* parsing fails — especially useful for debugging parallel-call issues (#1656).
*
* @param input - The raw input that failed to parse
* @returns Human-readable diagnostic string describing what was received
*
* @example
* describeInvalidInput(null)
* // => 'Received: null'
*
* describeInvalidInput({ params: { element_name: 'x' } })
* // => 'Received: { params } (missing "operation" field)'
*
* describeInvalidInput([{ operation: 'addEntry' }, { operation: 'addEntry' }])
* // => 'Received: array with 2 items (use { operations: [...] } for batch calls)'
*
* describeInvalidInput({ operation: 123, params: {} })
* // => 'Received: { operation, params } ("operation" is number, expected string)'
*/
export declare function describeInvalidInput(input: unknown): string;
export {};
//# sourceMappingURL=types.d.ts.map