Fountain Pen Ink MCP Server

Instructions

Implementation Reference

• src/index.ts:522-681 (handler)

  Main handler function that executes the get_color_palette tool. Handles theme parsing, color harmony generation, and finds closest matching fountain pen inks for each palette color.
  private getColorPalette( theme: string, paletteSize: number, harmony?: Harmony, ): MCPTextResponse { const themeColors: { [key: string]: [number, number, number][] } = { warm: [ [255, 100, 50], [255, 150, 0], [200, 80, 80], [180, 120, 60], [220, 180, 100], ], cool: [ [50, 150, 255], [100, 200, 200], [150, 100, 255], [80, 180, 150], [120, 120, 200], ], earth: [ [139, 69, 19], [160, 82, 45], [210, 180, 140], [107, 142, 35], [85, 107, 47], ], ocean: [ [0, 119, 190], [0, 150, 136], [72, 201, 176], [135, 206, 235], [25, 25, 112], ], autumn: [ [255, 140, 0], [255, 69, 0], [220, 20, 60], [184, 134, 11], [139, 69, 19], ], spring: [ [154, 205, 50], [124, 252, 0], [173, 255, 47], [50, 205, 50], [0, 255, 127], ], summer: [ [255, 235, 59], [255, 193, 7], [76, 175, 80], [139, 195, 74], [3, 169, 244], ], winter: [ [224, 224, 224], [144, 164, 174], [96, 125, 139], [33, 150, 243], [0, 0, 128], ], pastel: [ [255, 204, 204], [204, 255, 204], [204, 204, 255], [255, 255, 204], [255, 204, 255], ], vibrant: [ [255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 0], [255, 0, 255], ], monochrome: [ [255, 255, 255], [224, 224, 224], [192, 192, 192], [128, 128, 128], [64, 64, 64], [0, 0, 0], ], sunset: [ [255, 224, 130], [255, 170, 85], [255, 110, 80], [200, 80, 120], [100, 60, 110], ], forest: [ [34, 85, 34], [20, 60, 20], [60, 100, 60], [100, 140, 100], [140, 180, 140], ], }; let targetColors: [number, number, number][]; const lowerCaseTheme = theme.toLowerCase(); if (harmony) { try { const baseRgb = hexToRgb(theme); const baseHsl = rgbToHsl(baseRgb); const harmonyHsl = generateHarmonyColors(baseHsl, harmony); targetColors = harmonyHsl.map((hsl) => hslToRgb(hsl)); } catch { throw new Error('Invalid base color for harmony rule. Please use a single valid hex code.'); } } else if (themeColors[lowerCaseTheme]) { targetColors = themeColors[lowerCaseTheme]; } else if (theme.startsWith('#') || theme.includes(',')) { try { targetColors = theme.split(',').map((hex) => hexToRgb(hex.trim())); } catch { throw new Error( 'Invalid custom palette format. Please use a comma-separated list of hex codes, e.g., "#FF0000,#00FF00,#0000FF"', ); } } else { throw new Error( `Unknown theme: "${theme}". Available themes are: ${Object.keys(themeColors).join(', ')}`, ); } const paletteInks: SearchResult[] = []; const usedInkIds = new Set<string>(); for (let i = 0; i < Math.min(paletteSize, targetColors.length); i++) { const targetRgb = targetColors[i]; const closestInks = findClosestInks(targetRgb, this.inkColors, 5).filter( (ink) => !usedInkIds.has(ink.ink_id), ); if (closestInks.length > 0) { const ink = closestInks[0]; usedInkIds.add(ink.ink_id); const metadata = this.getInkMetadata(ink.ink_id); paletteInks.push(createSearchResult(ink, metadata, ink.distance)); } } const palette: PaletteResult = { theme, inks: paletteInks, description: `A curated palette of ${paletteInks.length} fountain pen inks matching the ${theme} theme.`, }; return { content: [ { type: 'text', text: JSON.stringify(palette, null, 2), }, ], } satisfies MCPTextResponse; }
• src/index.ts:230-257 (schema)

  Tool schema definition provided in listTools response, specifying input parameters: theme (required), palette_size, harmony.
  { name: 'get_color_palette', description: 'Generate a themed or harmony-based palette of inks. Supports three modes: 1) Predefined themes (warm, cool, earth, ocean, autumn, spring, summer, winter, pastel, vibrant, monochrome, sunset, forest), 2) Custom hex color lists (comma-separated), 3) Color harmony generation from a base hex color.', inputSchema: { type: 'object', properties: { theme: { type: 'string', description: 'Theme name (e.g., "warm", "ocean"), comma-separated hex colors (e.g., "#FF0000,#00FF00"), or single hex color for harmony generation (e.g., "#FF0000").', }, palette_size: { type: 'number', description: 'Number of inks in the palette (default: 5)', default: 5, }, harmony: { type: 'string', description: 'Color harmony rule to apply when theme is a single hex color. Options: "complementary", "analogous", "triadic", "split-complementary". Requires theme to be a valid hex color.', enum: ['complementary', 'analogous', 'triadic', 'split-complementary'], }, }, required: ['theme'], additionalProperties: false, }, },
• src/index.ts:295-300 (registration)

  Tool call dispatch in the CallToolRequestSchema handler, routing to the getColorPalette implementation.
  case 'get_color_palette': return this.getColorPalette( args.theme as string, (args.palette_size as number) || 5, args.harmony as Harmony, );
• src/utils.ts:321-335 (helper)

  Helper function to generate color harmony variants (complementary, analogous, etc.) from base HSL color, used when harmony parameter is provided.
  export function generateHarmonyColors( baseHsl: [number, number, number], harmony: 'complementary' | 'analogous' | 'triadic' | 'split-complementary', ): [number, number, number][] { const [h, s, l] = baseHsl; const harmonyHues: { [key: string]: number[] } = { complementary: [h, (h + 180) % 360], analogous: [h, (h + 30) % 360, (h + 330) % 360], triadic: [h, (h + 120) % 360, (h + 240) % 360], 'split-complementary': [h, (h + 150) % 360, (h + 210) % 360], }; const hues = harmonyHues[harmony] || [h]; return hues.map((hue) => [hue, s, l]); }
• src/utils.ts:106-120 (helper)

  Core helper to find closest fountain pen inks to a target RGB color using distance metric, used repeatedly in palette generation.
  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); }