search_inks_by_color

Find fountain pen inks matching a specific color by entering a hex code to discover similar shades from the database.

Instructions

Find inks similar to a given color using RGB matching

Input Schema

TableJSON Schema

Name	Required	Description	Default
`color`	Yes	Hex color code (e.g., "#FF5733")
`max_results`	No	Maximum number of results to return (default: 20)

Implementation Reference

src/index.ts:364-394 (handler)

The primary handler function for the 'search_inks_by_color' tool. Converts input hex color to RGB, finds closest matching inks using color distance, retrieves metadata, formats results as JSON, and returns MCPTextResponse.

private searchInksByColor(colorHex: string, maxResults: number): MCPTextResponse {
  try {
    const targetRgb = hexToRgb(colorHex);
    const closestInks = findClosestInks(targetRgb, this.inkColors, maxResults);

    const results: SearchResult[] = closestInks.map((ink) => {
      const metadata = this.getInkMetadata(ink.ink_id);
      return createSearchResult(ink, metadata, ink.distance);
    });

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              target_color: colorHex,
              target_rgb: targetRgb,
              results_count: results.length,
              results,
            },
            null,
            2,
          ),
        },
      ],
    } satisfies MCPTextResponse;
  } catch {
    throw new Error(`Invalid color format: ${colorHex}. Please use hex format like #FF5733`);
  }
}

src/index.ts:159-177 (schema)

Tool schema definition in the ListTools response, specifying input parameters: color (required hex string) and optional max_results.

{
  name: 'search_inks_by_color',
  description: 'Find inks similar to a given color using RGB matching',
  inputSchema: {
    type: 'object',
    properties: {
      color: {
        type: 'string',
        description: 'Hex color code (e.g., "#FF5733")',
      },
      max_results: {
        type: 'number',
        description: 'Maximum number of results to return (default: 20)',
        default: 20,
      },
    },
    required: ['color'],
  },
},

src/index.ts:277-281 (registration)
Dispatch registration in the CallToolRequestSchema handler switch statement, mapping tool calls to the searchInksByColor method.
```
case 'search_inks_by_color':
  return this.searchInksByColor(
    args.color as string,
    (args.max_results as number) || 20,
  );
```

src/utils.ts:106-120 (helper)

Core helper function that computes Euclidean RGB color distances for all inks against target, sorts by closeness, and returns top matches with distance.

export function findClosestInks(
  targetRgb: [number, number, number],
  inkColors: InkColor[],
  maxResults: number = 20,
): InkWithDistance[] {
  const distances = inkColors.map((ink) => ({
    ...ink,
    distance: calculateColorDistance(targetRgb, ink.rgb), // Now both are RGB!
  }));

  // Sort by distance (closest first)
  distances.sort((a, b) => a.distance - b.distance);

  return distances.slice(0, maxResults);
}

src/utils.ts:15-27 (helper)

Utility function to parse hex color string to RGB array, used in the handler for input validation and conversion.

export function hexToRgb(hex: string): [number, number, number] {
  const cleanHex = hex.replace(/^#/, '');
  if (cleanHex.length !== 6) {
    throw new Error('Invalid hex color string');
  }

  const bigint = parseInt(cleanHex, 16);
  const r = (bigint >> 16) & 255;
  const g = (bigint >> 8) & 255;
  const b = bigint & 255;

  return [r, g, b];
}

Fountain Pen Ink MCP Server