README.md•8.24 kB
# 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](https://www.linkedin.com/pulse/my-first-mcp-server-weekend-experiment-ai-pair-edd-wilder-james-jjric).
<a href="https://glama.ai/mcp/servers/@ewilderj/inks-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@ewilderj/inks-mcp/badge" alt="Fountain Pen Ink Server MCP server" />
</a>
[](https://github.com/ewilderj/inks-mcp/actions/workflows/ci.yml)
[](https://prettier.io)
[](https://eslint.org)
## 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
```bash
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
```bash
# 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
```bash
# 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:
```json
{
"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:
```bash
# 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:
```json
{ "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:
```json
{ "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:
```json
{ "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:
```json
{ "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:
```json
{ "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:
```json
{ "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](https://wilderwrites.ink/) 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:
```bash
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](https://wilderwrites.ink/) - Source of ink data and detailed ink information
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP documentation and examples