Inks MCP

🚀 Fountain Pen Ink MCP Server

A Model Context Protocol (MCP) server that equips 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 offers the following tools for LLMs:

🔍 Search Tools

• search_inks_by_name: Conduct a 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: Obtain 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 Examples

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.

📚 Documentation

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

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests if applicable.
5. 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.

🔗 Links

• Wilder Writes - Source of ink data and detailed ink information.
• Model Context Protocol - MCP documentation and examples.