@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.
95 lines • 4.33 kB
TypeScript
/**
* MCP-AQL Tools - Unified query interface for AI agents
*
* Provides two endpoint modes configurable via MCP_AQL_ENDPOINT_MODE environment variable:
*
* ## Mode 1: CRUDE Endpoints (Default) - MCP_AQL_ENDPOINT_MODE=crude
* 5 tools: mcp_aql_create, mcp_aql_read, mcp_aql_update, mcp_aql_delete, mcp_aql_execute (~4,300 tokens)
*
* ## Mode 2: Single Endpoint (Minimal) - MCP_AQL_ENDPOINT_MODE=single
* 1 tool: mcp_aql (~350 tokens)
* Ideal for multi-server deployments where token budget is constrained.
*
* Note: These tools are only registered when MCP_INTERFACE_MODE=mcpaql (default).
* When MCP_INTERFACE_MODE=discrete, discrete tools are registered instead.
*
* ## Why 5 CRUDE Endpoints? (Default Mode)
*
* The 5-endpoint CRUDE pattern (Create, Read, Update, Delete, Execute) was chosen for:
*
* 1. **User Comprehension**: CRUDE extends CRUD with Execute for non-idempotent
* operations, making it easy for users to reason about what each endpoint can do.
*
* 2. **Platform Annotations**: MCP platforms like ChatGPT's apps require
* tool annotations that describe safety and destructiveness. The 5-endpoint
* split maps directly to distinct permission levels:
* - CREATE: additive, non-destructive (readOnlyHint: false, destructiveHint: false)
* - READ: safe, read-only (readOnlyHint: true, destructiveHint: false)
* - UPDATE: modifying, potentially destructive (readOnlyHint: false, destructiveHint: true)
* - DELETE: destructive (readOnlyHint: false, destructiveHint: true)
* - EXECUTE: non-idempotent, potentially destructive (readOnlyHint: false, destructiveHint: true)
*
* 3. **Granular Permission Control**: Users can grant READ endpoint full access
* while locking down CREATE, UPDATE, DELETE, and EXECUTE. This enables safe
* read-only integrations without exposing mutation capabilities.
*
* ## Why Single Endpoint? (Minimal Mode)
*
* The single-endpoint mode was added for:
*
* 1. **Token Efficiency**: ~350 tokens vs ~4,300 tokens (92% reduction)
* 2. **Multi-Server Deployments**: When running multiple MCP servers, token
* budgets can be constrained. Single endpoint reduces overhead.
* 3. **Simplified Integration**: Some clients prefer a single entry point.
*
* Security is maintained through server-side Gatekeeper enforcement - the
* server determines which operation type is being executed and applies
* appropriate permission checks.
*
* ## GraphQL-Style Introspection
*
* MCP-AQL follows GraphQL patterns for self-documentation. Tool descriptions
* are generated dynamically from OPERATION_ROUTES, ensuring they always reflect
* the current available operations.
*
* ### Introspection Examples
*
* List all available operations:
* ```json
* { "operation": "introspect", "params": { "query": "operations" } }
* ```
*
* Get details for a specific operation (parameters, examples, return types):
* ```json
* { "operation": "introspect", "params": { "query": "operations", "name": "create_element" } }
* ```
*
* Discover available types (e.g., ElementType enum values):
* ```json
* { "operation": "introspect", "params": { "query": "types", "name": "ElementType" } }
* ```
*
* ### Design Philosophy
*
* - **Single source of truth**: OPERATION_ROUTES defines all operations
* - **Dynamic descriptions**: Adding an operation to OPERATION_ROUTES automatically
* updates tool descriptions - no manual synchronization needed
* - **Introspection-first**: LLMs discover parameters via introspect, not static docs
* - **GraphQL heritage**: Patterns familiar to any LLM trained on GraphQL
*/
import type { MCPAQLHandler } from '../../handlers/mcp-aql/MCPAQLHandler.js';
import type { ToolDefinition, ToolHandler } from '../../handlers/types/ToolTypes.js';
/**
* Get MCP-AQL tools for registration in the ToolRegistry.
*
* Returns different tools based on MCP_AQL_ENDPOINT_MODE environment variable:
* - 'crude' (default): 5 CRUDE endpoints (Create, Read, Update, Delete, Execute) (~4,300 tokens)
* - 'single': 1 unified endpoint (~350 tokens)
*
* Note: MCP_AQL_MODE is supported as a deprecated alias for backward compatibility.
*/
export declare function getMCPAQLTools(handler: MCPAQLHandler): Array<{
tool: ToolDefinition;
handler: ToolHandler;
}>;
//# sourceMappingURL=MCPAQLTools.d.ts.map