Fountain Pen Ink MCP Server

A Model Context Protocol (MCP) server that provides LLMs with specialized knowledge about fountain pen inks, enabling intelligent ink search, color matching, and recommendations. Read my article about creating this server.

Features

This MCP server provides the following tools for LLMs:

🔍 Search Tools

search_inks_by_name: Fuzzy search for inks by name or manufacturer
search_inks_by_color: Find inks similar to any given color using RGB matching
get_inks_by_maker: List all inks from a specific manufacturer

📊 Information Tools

get_ink_details: Get comprehensive information about a specific ink
analyze_color: Analyze any color and find the closest matching inks

🎨 Recommendation Tools

get_color_palette: Generate sophisticated themed ink palettes with color theory support
- 13 predefined themes (warm, cool, earth, ocean, autumn, spring, summer, winter, pastel, vibrant, monochrome, sunset, forest)
- Color harmony generation (complementary, analogous, triadic, split-complementary)
- Custom hex color palettes

Quick start

git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp
npm install
npm run build

# List tools and run a sample query
npm run tools:list
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

Installation

Prerequisites

Node.js 18 or higher
npm or yarn

Setup

# Clone the project
git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Running the Server

# Run once
npm start

# Development mode with auto-rebuild
npm run dev

# Watch mode for development
npm run watch

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "servers": {
    "fountain-pen-ink-server": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"]
    }
  }
}

CLI Client (Generic)

A small script is included to exercise any tool from the command line:

# List tools
npm run tools:list

# Call a tool with inline JSON args
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

# Call with arguments from a file
npm run client -- --tool get_color_palette --args-file examples/palette.complementary.json

# Change output mode (auto | content | raw)
npm run client -- --tool search_inks_by_color --args '{"color":"#2E5984"}' --output content

Script options:

--list List available tools
--tool <name> Tool name to call
--args '<json>' Inline JSON arguments
--args-file <path> JSON file with arguments
--server <path> Path to compiled server (default: dist/index.js)
--timeout <ms> Timeout in milliseconds (default: 10000)
--output <mode> Output mode: auto | content | raw (default: auto)

Available Tools

search_inks_by_name

Search for fountain pen inks using fuzzy text matching.

Parameters: query (string), max_results (number, optional)

Example input:

{ "query": "sailor blue", "max_results": 10 }

Example prompt:

Find inks matching "sailor blue"; limit to 10 results.

search_inks_by_color

Find inks similar to a given color using RGB color space matching.

Parameters: color (hex string), max_results (number, optional)

Example input:

{ "color": "#2E5984", "max_results": 15 }

Example prompt:

Find inks similar to color #2E5984; up to 15 results.

get_ink_details

Get complete information about a specific ink.

Parameters: ink_id (string)

Example input:

{ "ink_id": "diamine-oxblood" }

Example prompt:

Show info for "diamine-oxblood".

get_inks_by_maker

List all inks from a specific manufacturer.

Parameters: maker (string), max_results (number, optional)

Example input:

{ "maker": "diamine", "max_results": 25 }

Example prompt:

List Diamine inks; limit 25.

analyze_color

Analyze a color and provide fountain pen ink context.

Parameters: color (hex string), max_results (number, optional)

Example input:

{ "color": "#2E5984", "max_results": 7 }

Example prompt:

Analyze #2E5984 and show the top 7 closest inks.

get_color_palette

Generate a themed or harmony-based palette of fountain pen inks with color theory support.

Parameters: theme (string), palette_size (number, optional), harmony (string, optional)

Supported Themes:

Classic: warm, cool, earth, ocean, autumn, spring
Seasonal: summer, winter
Mood: pastel, vibrant, monochrome
Atmospheric: sunset, forest

Harmony Rules: complementary, analogous, triadic, split-complementary

Example input:

{ "theme": "sunset", "palette_size": 4 }

Example prompt:

Generate a 4‑ink palette for the "sunset" theme.

For more examples, see examples/USAGE.md.

Data Sources

The server uses two main data files:

ink-colors.json: Contains RGB color values and basic ink information
search.json: Contains metadata including manufacturers, scan dates, and searchable names

All ink data links back to Wilder Writes for detailed information and images.

Development

Project Structure

inks-mcp/
├── src/
│   ├── index.ts      # Main MCP server implementation
│   ├── types.ts      # TypeScript type definitions
│   └── utils.ts      # Utility functions for color matching
├── data/
│   ├── ink-colors.json   # RGB color data
│   └── search.json       # Search metadata
├── dist/             # Compiled JavaScript (generated)

Scripts

npm run build: Compile TypeScript to JavaScript
npm run start: Run the compiled server
npm run dev: Build and run in one command
npm run watch: Watch for changes and rebuild automatically
npm run client: Run the generic CLI client
npm run tools:list: List available tools via the CLI client

Testing

Run the comprehensive test suite to validate all functionality:

npm test

# Run individual test categories
cd test
node test-enhanced-palette.js    # Palette generation features
node test-mcp-palette.js        # MCP protocol compliance
node test-schema.js             # Tool schema validation
node test-harmony-direct.js     # Color harmony algorithms

For manual, ad‑hoc testing, use the CLI client documented above.

The test suite covers:

✅ 13 predefined themes + 4 harmony rules
✅ Custom color palette generation
✅ MCP protocol compliance
✅ Error handling and validation
✅ Color space conversions (BGR→RGB, RGB↔HSL)

Color Matching Algorithm

The server uses Euclidean distance in RGB color space to find similar inks:

distance = √[(r₁-r₂)² + (g₁-g₂)² + (b₁-b₂)²]

Future improvements may include:

LAB color space for better perceptual accuracy
Weighted color components for fountain pen ink characteristics
Semantic color descriptions

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

Fountain Pen Ink MCP Server

Features

This MCP server provides the following tools for LLMs:

🔍 Search Tools

search_inks_by_name: Fuzzy search for inks by name or manufacturer
search_inks_by_color: Find inks similar to any given color using RGB matching
get_inks_by_maker: List all inks from a specific manufacturer

📊 Information Tools

get_ink_details: Get comprehensive information about a specific ink
analyze_color: Analyze any color and find the closest matching inks

🎨 Recommendation Tools

get_color_palette: Generate sophisticated themed ink palettes with color theory support
- 13 predefined themes (warm, cool, earth, ocean, autumn, spring, summer, winter, pastel, vibrant, monochrome, sunset, forest)
- Color harmony generation (complementary, analogous, triadic, split-complementary)
- Custom hex color palettes

Quick start

git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp
npm install
npm run build

# List tools and run a sample query
npm run tools:list
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

Installation

Prerequisites

Node.js 18 or higher
npm or yarn

Setup

# Clone the project
git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Running the Server

# Run once
npm start

# Development mode with auto-rebuild
npm run dev

# Watch mode for development
npm run watch

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "servers": {
    "fountain-pen-ink-server": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"]
    }
  }
}

CLI Client (Generic)

A small script is included to exercise any tool from the command line:

# List tools
npm run tools:list

# Call a tool with inline JSON args
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

# Call with arguments from a file
npm run client -- --tool get_color_palette --args-file examples/palette.complementary.json

# Change output mode (auto | content | raw)
npm run client -- --tool search_inks_by_color --args '{"color":"#2E5984"}' --output content

Script options:

--list List available tools
--tool <name> Tool name to call
--args '<json>' Inline JSON arguments
--args-file <path> JSON file with arguments
--server <path> Path to compiled server (default: dist/index.js)
--timeout <ms> Timeout in milliseconds (default: 10000)
--output <mode> Output mode: auto | content | raw (default: auto)

Available Tools

search_inks_by_name

Search for fountain pen inks using fuzzy text matching.

Parameters: query (string), max_results (number, optional)

Example input:

{ "query": "sailor blue", "max_results": 10 }

Example prompt:

Find inks matching "sailor blue"; limit to 10 results.

search_inks_by_color

Find inks similar to a given color using RGB color space matching.

Parameters: color (hex string), max_results (number, optional)

Example input:

{ "color": "#2E5984", "max_results": 15 }

Example prompt:

Find inks similar to color #2E5984; up to 15 results.

get_ink_details

Get complete information about a specific ink.

Parameters: ink_id (string)

Example input:

{ "ink_id": "diamine-oxblood" }

Example prompt:

Show info for "diamine-oxblood".

get_inks_by_maker

List all inks from a specific manufacturer.

Parameters: maker (string), max_results (number, optional)

Example input:

{ "maker": "diamine", "max_results": 25 }

Example prompt:

List Diamine inks; limit 25.

analyze_color

Analyze a color and provide fountain pen ink context.

Parameters: color (hex string), max_results (number, optional)

Example input:

{ "color": "#2E5984", "max_results": 7 }

Example prompt:

Analyze #2E5984 and show the top 7 closest inks.

get_color_palette

Generate a themed or harmony-based palette of fountain pen inks with color theory support.

Parameters: theme (string), palette_size (number, optional), harmony (string, optional)

Supported Themes:

Classic: warm, cool, earth, ocean, autumn, spring
Seasonal: summer, winter
Mood: pastel, vibrant, monochrome
Atmospheric: sunset, forest

Harmony Rules: complementary, analogous, triadic, split-complementary

Example input:

{ "theme": "sunset", "palette_size": 4 }

Example prompt:

Generate a 4‑ink palette for the "sunset" theme.

For more examples, see examples/USAGE.md.

Data Sources

The server uses two main data files:

ink-colors.json: Contains RGB color values and basic ink information
search.json: Contains metadata including manufacturers, scan dates, and searchable names

All ink data links back to Wilder Writes for detailed information and images.

Development

Project Structure

inks-mcp/
├── src/
│   ├── index.ts      # Main MCP server implementation
│   ├── types.ts      # TypeScript type definitions
│   └── utils.ts      # Utility functions for color matching
├── data/
│   ├── ink-colors.json   # RGB color data
│   └── search.json       # Search metadata
├── dist/             # Compiled JavaScript (generated)

Scripts

npm run build: Compile TypeScript to JavaScript
npm run start: Run the compiled server
npm run dev: Build and run in one command
npm run watch: Watch for changes and rebuild automatically
npm run client: Run the generic CLI client
npm run tools:list: List available tools via the CLI client

Testing

Run the comprehensive test suite to validate all functionality:

npm test

# Run individual test categories
cd test
node test-enhanced-palette.js    # Palette generation features
node test-mcp-palette.js        # MCP protocol compliance
node test-schema.js             # Tool schema validation
node test-harmony-direct.js     # Color harmony algorithms

For manual, ad‑hoc testing, use the CLI client documented above.

The test suite covers:

✅ 13 predefined themes + 4 harmony rules
✅ Custom color palette generation
✅ MCP protocol compliance
✅ Error handling and validation
✅ Color space conversions (BGR→RGB, RGB↔HSL)

Color Matching Algorithm

The server uses Euclidean distance in RGB color space to find similar inks:

distance = √[(r₁-r₂)² + (g₁-g₂)² + (b₁-b₂)²]

Future improvements may include:

LAB color space for better perceptual accuracy
Weighted color components for fountain pen ink characteristics
Semantic color descriptions

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.