@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.
277 lines • 9.96 kB
TypeScript
/**
* IntrospectionResolver - GraphQL-style introspection for MCP-AQL
*
* Provides discovery capabilities for LLMs to understand available operations,
* their parameters, return types, and examples.
*
* INTROSPECTION QUERIES:
* - operations: List all available operations
* - operation(name): Get details for a specific operation
* - types: List available types (ElementType, etc.)
* - type(name): Get details for a specific type
* - categories: Category format rules + discovery guidance (Issue #631)
*
* DESIGN RATIONALE:
* - Token-efficient: Returns minimal but useful information
* - Self-documenting: Operations describe themselves
* - Read-only: Safe to call at any time (no side effects)
*
* SCHEMA INTEGRATION (Issue #254):
* - Schema-driven operations get their metadata from OperationSchema
* - Legacy operations use the fallback OPERATION_PARAMETERS/OPERATION_EXAMPLES
* - This ensures single source of truth for schema-driven operations
*/
import { type CRUDEndpoint } from './OperationRouter.js';
import { type EndpointPermissions } from './PermissionGuard.js';
/**
* Basic information about an operation (used in list responses)
*/
export interface OperationInfo {
/** Operation name (e.g., 'create_element') */
name: string;
/** CRUD endpoint this operation belongs to */
endpoint: string;
/** Brief description of what the operation does */
description: string;
}
/**
* Parameter information for operation details
*/
export interface ParameterInfo {
/** Parameter name */
name: string;
/** Parameter type (e.g., 'string', 'ElementType', 'object') */
type: string;
/** Whether the parameter is required */
required: boolean;
/** Brief description of the parameter */
description: string;
/** Default value if any */
default?: unknown;
}
/**
* Return type information
*/
export interface TypeInfo {
/** Type name */
name: string;
/** Type kind (enum, object, scalar, union) */
kind: 'enum' | 'object' | 'scalar' | 'union';
/** Brief description */
description?: string;
}
/**
* Detailed information about a specific operation
*/
export interface OperationDetails {
/** Operation name */
name: string;
/** CRUD endpoint */
endpoint: string;
/** MCP tool name (e.g., 'mcp_aql_read') */
mcpTool: string;
/** Full description */
description: string;
/** Permission flags */
permissions: EndpointPermissions;
/** Parameter definitions */
parameters: ParameterInfo[];
/** Return type information */
returns: TypeInfo;
/** Usage examples */
examples: string[];
/** Alternative operation names that resolve to this operation */
aliases?: string[];
}
/**
* Detailed type information with enum values or object fields
*/
export interface TypeDetails {
/** Type name */
name: string;
/** Type kind */
kind: 'enum' | 'object' | 'scalar' | 'union';
/** Full description */
description: string;
/** Enum values (for enum types) */
values?: string[];
/** Object fields (for object types) */
fields?: ParameterInfo[];
/** Union member types (for union types) */
members?: string[];
}
/**
* Format specification for an element type (Issue #715)
*/
export interface FormatSpec {
/** Element type this spec describes */
elementType: string;
/** File format used for storage */
fileFormat: string;
/** Required fields in frontmatter */
requiredFields: string[];
/** Optional fields in frontmatter */
optionalFields: string[];
/** Guidance on using instructions vs content fields */
dualFieldGuidance: string;
/** Syntax notes specific to this element type */
syntaxNotes: string[];
/** Minimal working example */
minimalExample: string;
/** Full-featured example */
fullExample: string;
/** Naming conventions for this element type */
namingConventions: string[];
}
/**
* Result of an introspection query
*/
export interface IntrospectionResult {
/** List of operations (for 'operations' query) */
operations?: OperationInfo[];
/** Single operation details (for 'operation(name)' query) */
operation?: OperationDetails | null;
/** List of types (for 'types' query) */
types?: TypeInfo[];
/** Single type details (for 'type(name)' query) */
type?: TypeDetails | null;
/** Format specification (for 'format' query) */
formatSpec?: FormatSpec | FormatSpec[] | null;
/** Category discovery info (for 'categories' query, Issue #631) */
categories?: Record<string, unknown>;
}
/**
* Resolver for introspection queries.
* Provides self-documentation capabilities for MCP-AQL operations.
*/
export declare class IntrospectionResolver {
/**
* Execute an introspection query
*
* @param params - Introspection parameters
* @param params.query - What to introspect: 'operations', 'types', 'format', or 'categories'
* @param params.name - Optional: specific operation or type name
* @returns IntrospectionResult with requested information
*/
static resolve(params: Record<string, unknown>): IntrospectionResult;
/**
* List all available operations
*
* For schema-driven operations, uses description from OperationSchema.
* For legacy operations, uses description from OPERATION_ROUTES.
*
* @see Issue #254 - Single source of truth from schema
*/
private static listOperations;
/**
* Get detailed information about a specific operation
*
* For schema-driven operations, reads metadata from OperationSchema.
* For legacy operations, uses fallback OPERATION_PARAMETERS/OPERATION_EXAMPLES.
*
* @see Issue #254 - Auto-generate introspection from schema
*/
private static getOperationDetails;
/**
* Get operation details from OperationSchema (dispatch-driven or introspection-only)
*
* @see Issue #254 - Single source of truth from schema
* @see Issue #594 - Introspection-only schemas for all operations
*/
private static getSchemaOperationDetails;
/**
* Get the return type for a legacy (non-schema) operation.
* Schema-driven and introspection-only operations get return types from their schema definitions.
*/
private static getReturnType;
/**
* List all available types
*/
private static listTypes;
/**
* Get detailed information about a specific type
*/
private static getTypeDetails;
/**
* Get format specification for an element type.
* If name is provided, returns a single spec (or null for unknown types).
* If name is omitted, returns all specs as an overview.
*
* @see Issue #715 - Proactive LLM guidance for element creation
*/
private static getFormatSpec;
/**
* Issue #631: Category discovery info — format rules, allowed aggregation fields,
* and guidance for discovering existing categories via query_elements.
* IntrospectionResolver is stateless (no portfolio access), so live category data
* must be fetched via query_elements with aggregate: { group_by: "category" }.
*/
private static getCategoryInfo;
/**
* Get operations grouped by endpoint
* Utility method for documentation generation
*/
static getOperationsByEndpoint(): Record<CRUDEndpoint, OperationInfo[]>;
/**
* Generate a compact summary for token-efficient responses
*/
static getSummary(): string;
/**
* Get server capabilities grouped by user-intent category.
* Reads category from each operation's schema definition at runtime.
* Designed for extensibility — additional CapabilitySources (e.g. portfolio
* elements from the capability index) can be registered via registerSource().
*
* @param params - Optional parameters
* @param params.category - Filter to a specific category
* @returns CapabilitiesResult with categorized operations
* @see Issue #1760 - get_capabilities operation
*/
static getCapabilities(params: Record<string, unknown>): Record<string, unknown>;
/**
* Build the full category map from all registered capability sources.
* Returns sorted categories with descriptions and merged entries.
*/
private static buildCategoryMap;
/**
* Filter the category map to a single matching category (case-insensitive).
*/
private static filterByCategory;
/**
* Register an additional capability source.
* Future element sources (reading from the capability index) can be
* plugged in here without modifying the get_capabilities handler.
* @see Issue #1760 - extensibility for portfolio element capabilities
*/
static registerSource(source: CapabilitySource): void;
/**
* Truncate a description to a brief one-liner.
* Takes the first sentence (up to first period followed by space or end).
*/
private static toBrief;
}
/**
* A single capability entry — represents one thing a user can do.
*/
export interface CapabilityEntry {
/** Operation or capability name */
name: string;
/** One-line description */
brief: string;
/** Origin: 'server' for built-in operations, or 'skill:name', 'agent:name', etc. */
source: string;
/** CRUDE endpoint (for server operations) */
endpoint?: string;
/** Whether this capability is currently active or available to activate */
status: 'active' | 'available';
}
/**
* Interface for pluggable capability providers.
* Implement this to contribute capabilities from new sources (e.g. portfolio elements).
* @see Issue #1760 - extensibility for portfolio element capabilities
*/
export interface CapabilitySource {
readonly sourceType: string;
getCapabilities(): Record<string, CapabilityEntry[]>;
}
//# sourceMappingURL=IntrospectionResolver.d.ts.map