DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/ElementTools.ts:220-240 (handler)

  Tool definition including name, description, input schema, and handler implementation for 'execute_agent'. The handler delegates execution to server.executeAgent(name, goal).

  {
    tool: {
      name: "execute_agent",
      description: "Execute an agent element with a specific goal",
      inputSchema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            description: "The agent name to execute",
          },
          goal: {
            type: "string",
            description: "The goal for the agent to achieve",
          },
        },
        required: ["name", "goal"],
      },
    },
    handler: (args: ExecuteAgentArgs) => server.executeAgent(args.name, args.goal)
  },

• src/server/tools/ElementTools.ts:70-73 (schema)

  Type definition for ExecuteAgentArgs used in the tool handler.

  interface ExecuteAgentArgs {
    name: string;
    goal: string;
  }

• src/server/ServerSetup.ts:52-54 (registration)

  Registration of all element tools, including 'execute_agent', via getElementTools(instance) in the ToolRegistry.

  // Register element tools (new generic tools for all element types)
  this.toolRegistry.registerMany(getElementTools(instance));

• src/server/types.ts:31-31 (schema)

  IToolHandler interface definition for the executeAgent method signature used by the tool handler.

  executeAgent(name: string, goal: string): Promise<any>;

• src/server/ServerSetup.ts:86-205 (helper)

  Access to ToolRegistry instance where tools are registered and handlers stored.

    logger.debug('ToolDiscoveryCache: Cache invalidated due to tool registration');
  }
  
  /**
   * Setup the ListToolsRequest handler with caching
   */
  private setupListToolsHandler(server: Server): void {
    server.setRequestHandler(ListToolsRequestSchema, async () => {
      const startTime = Date.now();
      
      // Try to get cached tools first
      let tools = this.toolCache.getToolList();
      
      if (!tools) {
        // Cache miss - fetch tools from registry
        tools = this.toolRegistry.getAllTools();
        
        // Cache the results for future requests
        this.toolCache.setToolList(tools);
        
        const duration = Date.now() - startTime;
        logger.info('ToolDiscoveryCache: Cache miss - fetched and cached tools', {
          toolCount: tools.length,
          duration: `${duration}ms`,
          source: 'registry'
        });
      } else {
        const duration = Date.now() - startTime;
        logger.debug('ToolDiscoveryCache: Cache hit - returned cached tools', {
          toolCount: tools.length,
          duration: `${duration}ms`,
          source: 'cache'
        });
      }
      
      return { tools };
    });
  }
  
  /**
   * Setup the CallToolRequest handler
   */
  private setupCallToolHandler(server: Server): void {
    server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;
      
      try {
        const handler = this.toolRegistry.getHandler(name);
        
        if (!handler) {
          throw new McpError(
            ErrorCode.MethodNotFound,
            `Unknown tool: ${name}`
          );
        }
        
        // Normalize Unicode in all string arguments to prevent security bypasses
        const normalizedArgs = this.normalizeArgumentsUnicode(args, name);
        
        const response = await handler(normalizedArgs);
        
        // Wizard auto-trigger removed for v1.8.0
        // Manual wizard still available via config tool with action: 'wizard'
        
        return response;
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        
        throw new McpError(
          ErrorCode.InternalError,
          `Error executing tool ${name}: ${error}`
        );
      }
    });
  }
  
  /**
   * Recursively normalize Unicode in all string values within arguments
   */
  private normalizeArgumentsUnicode(args: any, toolName: string): any {
    if (args === null || args === undefined) {
      return args;
    }
    
    if (typeof args === 'string') {
      const result = UnicodeValidator.normalize(args);
      if (result.detectedIssues && result.detectedIssues.length > 0) {
        logger.warn(`Unicode security issues detected in tool ${toolName}:`, {
          issues: result.detectedIssues,
          severity: result.severity
        });
      }
      return result.normalizedContent;
    }
    
    if (Array.isArray(args)) {
      return args.map(item => this.normalizeArgumentsUnicode(item, toolName));
    }
    
    if (typeof args === 'object') {
      const normalized: any = {};
      for (const [key, value] of Object.entries(args)) {
        // Normalize both keys and values to prevent Unicode attacks in property names
        const normalizedKey = typeof key === 'string' ? 
          UnicodeValidator.normalize(key).normalizedContent : key;
        normalized[normalizedKey] = this.normalizeArgumentsUnicode(value, toolName);
      }
      return normalized;
    }
    
    // For non-string primitive types, return as-is
    return args;
  }
  
  /**
   * Get the tool registry
   */
  getToolRegistry(): ToolRegistry {