Tiling Trees MCP Server

Instructions

Implementation Reference

• src/index.ts:362-375 (registration)

  Registration of the 'validate_split_quality' tool in the TOOLS constant array. Includes the tool name, description, and input schema definition.

  {
    name: "validate_split_quality",
    description: "Validate split quality and detect common antipatterns (vague language, catch-all buckets, mixed dimensions, retroactive splitting, incomplete coverage). Returns a detailed quality report with issues and recommendations.",
    inputSchema: {
      type: "object",
      properties: {
        tileId: {
          type: "string",
          description: "ID of the tile whose split to validate",
        },
      },
      required: ["tileId"],
    },
  },

• src/index.ts:642-652 (handler)

  MCP server request handler dispatch case for 'validate_split_quality' tool. Extracts tileId argument, calls treeManager.validateSplitQuality, and returns JSON-formatted result.

  case "validate_split_quality": {
    const result = treeManager.validateSplitQuality(args.tileId as string);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/research-tree.ts:616-709 (handler)

  Primary implementation of the validateSplitQuality method in the ResearchTree class. This is the core logic that validates a tile's split by checking for common antipatterns, generating issues and recommendations, calculating a quality score, and returning a SplitQualityReport.

  validateSplitQuality(tileId: string): SplitQualityReport {
    const tile = this.tiles.get(tileId);
    if (!tile) {
      throw new Error(`Tile ${tileId} not found`);
    }
  
    const issues: ValidationIssue[] = [];
    const recommendations: string[] = [];
  
    // Get children for analysis
    const children = tile.childrenIds.map((id) => this.tiles.get(id)).filter((t) => t !== undefined) as Tile[];
  
    if (children.length === 0) {
      return {
        tileId: tile.id,
        tileTitle: tile.title,
        issues: [],
        score: 100,
        recommendations: ["Tile has no children - nothing to validate"],
      };
    }
  
    // 1. Check for vague language
    const vagueIssues = this.detectVagueLanguage(tile, children);
    issues.push(...vagueIssues);
  
    // 2. Check for catch-all buckets
    const catchAllIssues = this.detectCatchAllBuckets(tile, children);
    issues.push(...catchAllIssues);
  
    // 3. Check for mixed dimensions
    const mixedDimIssues = this.detectMixedDimensions(tile, children);
    issues.push(...mixedDimIssues);
  
    // 4. Check for retroactive splitting
    const retroactiveIssues = this.detectRetroactiveSplitting(tile, children);
    issues.push(...retroactiveIssues);
  
    // 5. Check for incomplete coverage
    if (!tile.isMECE) {
      issues.push({
        type: "incomplete_coverage",
        severity: "warning",
        message: "Split has not been validated for MECE completeness",
        tileId: tile.id,
        suggestion: "Use mark_mece to validate that the split is Mutually Exclusive and Collectively Exhaustive",
      });
    }
  
    // Generate recommendations
    if (issues.length === 0) {
      recommendations.push("Split appears well-structured");
      if (tile.isMECE) {
        recommendations.push("MECE validation completed");
      }
    } else {
      const errorCount = issues.filter((i) => i.severity === "error").length;
      const warningCount = issues.filter((i) => i.severity === "warning").length;
  
      if (errorCount > 0) {
        recommendations.push(`Address ${errorCount} critical issue(s) before proceeding`);
      }
      if (warningCount > 0) {
        recommendations.push(`Review ${warningCount} warning(s) to improve split quality`);
      }
  
      // Specific recommendations
      if (issues.some((i) => i.type === "vague_language")) {
        recommendations.push("Replace vague terms with measurable physical properties or precise definitions");
      }
      if (issues.some((i) => i.type === "catch_all_bucket")) {
        recommendations.push("Replace catch-all categories with specific, splittable subsets");
      }
      if (issues.some((i) => i.type === "mixed_dimensions")) {
        recommendations.push("Use a single consistent dimension/attribute for this split level");
      }
      if (issues.some((i) => i.type === "retroactive_splitting")) {
        recommendations.push("Consider physics/math-based splits instead of known solution types");
      }
    }
  
    // Calculate score (100 - 20 per error - 10 per warning)
    const errorPenalty = issues.filter((i) => i.severity === "error").length * 20;
    const warningPenalty = issues.filter((i) => i.severity === "warning").length * 10;
    const score = Math.max(0, 100 - errorPenalty - warningPenalty);
  
    return {
      tileId: tile.id,
      tileTitle: tile.title,
      issues,
      score,
      recommendations,
    };
  }

• src/research-tree.ts:711-764 (helper)

  Helper method detectVagueLanguage used by validateSplitQuality to identify vague terms in child tiles' titles and descriptions.

  private detectVagueLanguage(parent: Tile, children: Tile[]): ValidationIssue[] {
    const issues: ValidationIssue[] = [];
  
    // Common vague terms that lack physical precision
    const vagueTerms = [
      "natural",
      "artificial",
      "forced",
      "conventional",
      "traditional",
      "modern",
      "advanced",
      "simple",
      "complex",
      "normal",
      "standard",
      "typical",
      "unusual",
      "special",
      "general",
      "specific", // without quantification
      "better",
      "worse",
      "good",
      "bad",
      "clean",
      "dirty",
      "easy",
      "hard",
      "other", // catch-all
      "misc",
      "various",
    ];
  
    for (const child of children) {
      const textToCheck = `${child.title} ${child.description}`.toLowerCase();
  
      for (const vagueTerm of vagueTerms) {
        // Check for whole word matches
        const regex = new RegExp(`\\b${vagueTerm}\\b`, "i");
        if (regex.test(textToCheck)) {
          issues.push({
            type: "vague_language",
            severity: "warning",
            message: `Tile "${child.title}" uses vague term "${vagueTerm}" which may lack precision`,
            tileId: child.id,
            suggestion: `Replace "${vagueTerm}" with measurable properties (e.g., instead of "natural", specify "bio-derived" or "occurring without human intervention"; instead of "simple", specify complexity metrics)`,
          });
        }
      }
    }
  
    return issues;
  }