Ravelry Model Context Protocol Adapter

This Model Context Protocol (MCP) server acts as a sophisticated wrapper for the Ravelry Application Programming Interface (API), furnishing autonomous agents with the capability to search, navigate, and extract specific data pertaining to patterns for knitting and crocheting crafts.

🌟 Executive Summary

This Node.js-based MCP service translates Ravelry API interactions into structured tool calls consumable by AI reasoning engines. Its core functions include: - Executing targeted searches across the pattern repository. - Fetching exhaustive documentation for individual patterns. - Bulk retrieval of specifications for multiple patterns concurrently.

Personal Context: This utility was initiated due to my partner's profound dedication to fiber arts, which spurred the development of this technological conduit connecting AI capabilities with the rich Ravelry community data. Observing her reservations about advanced technology inspired this effort to demonstrate how computational aids can augment, rather than supersede, the tactile enjoyment of crafting.

🚀 Core Capabilities

• 🔎 Pattern Indexing: Query Ravelry's vast catalog using descriptive keywords and applied constraints.
• 📑 Blueprint Acquisition: Obtain complete descriptive metadata for designated patterns.
• 🧶 Medium Segregation: Refine searches based on the primary craft discipline (e.g., 'knitting', 'crochet').
• 💲 Cost Classification: Filter results based on transactional status (e.g., zero-cost, premium access).
• 🤖 Agent Synergy: Optimized for seamless invocation via the Model Context Protocol framework.

📋 Mandatory Initial Setup

• A functional installation of Node.js (version 14 or later).
• A package manager: npm or yarn.
• Valid API access credentials (username and password) registered with Ravelry.

🔧 Deployment Procedure

1. Source Code Acquisition bash git clone cd yarnsphere-mcp

2. Dependency Resolution bash npm install

3. Environment Provisioning bash # Template for development initialization cp .env.example .env.development # Template for production initialization cp .env.example .env.production

4. Credential Injection

5. Secure your Ravelry authentication identifiers.

6. Populate both environment files with:

   AUTH_USER=your_ravelry_username AUTH_PASS=your_ravelry_password

🎮 Operational Modes

Development Environment

bash npm run dev

This initiates the MCP adapter with live reloading capabilities.

Production Environment

bash npm run build npm start

Alternatively, use the streamlined command:

bash npm run prod

🔗 Integration with Claude Desktop

To enable Ravelry data interaction within Claude Desktop:

1. Activate Server: Confirm the adapter is operational locally or remotely where accessible.

2. Access Desktop Configuration: Launch Claude Desktop and navigate to the top-right profile area, selecting 'Settings'.

3. Extension Configuration: In the settings navigation panel, locate and select 'Extensions'.

4. Custom Adapter Addition:

5. Choose 'Add Custom MCP'.
6. Label: Ravelry Interface (or preferred moniker).
7. Endpoint: The server's address (e.g., http://localhost:3000).
8. Confirm by clicking 'Add MCP'.

4.2 Alternative: CLI Configuration - If deploying via compiled binaries, specify the path:

"yarnsphere": { "command": "node", "args": [ "YOUR_CUSTOM_PATH/dist/index.js" ] }

1. Enable Service: Flip the designated toggle switch for the new Ravelry adapter.

2. Verification: Initiate a dialogue with Claude, prompting actions like: "Can you locate some free crochet hat designs using the Ravelry utility?"

3. Debugging Tips:

4. Verify network accessibility between Desktop app and server.
5. Cross-check the configured URL.
6. Validate the environmental variables containing valid credentials.

Example Agent Prompts (Post-Connection)

Once linked, the AI can be directed to:

• "Discover zero-cost knitting patterns for autumnal garments on Ravelry."
• "Execute a search for sock knitting schematics."
• "Retrieve comprehensive specifics for pattern identifier 12345."
• "Identify designs suitable for novice crafters."

🧠 Exposed Functions

The server makes the following agent-callable functions available:

search-patterns

Queries the pattern index based on supplied criteria.

Arguments: - query: The primary text string for the search (mandatory). - page: Pagination index (defaults to 1). - craft: Filtering constraint for the craft type (e.g., "knitting", "crochet"). - availability: Financial status filter (default: "free"; options: "free", "ravelry", "online").

get-pattern-details

Fetches the full documentation set for a singular pattern.

Arguments: - id: The unique Pattern Identifier (mandatory).

get-multiple-pattern-details

Retrieves the documentation for several patterns concurrently.

Arguments: - ids: An ordered collection (Array) of Pattern IDs (mandatory).

🔍 Operational Mechanics

The adapter leverages the axios library to execute authenticated HTTP communications with Ravelry endpoints:

1. Requests are secured using Basic Authentication, leveraging configured Ravelry credentials.
2. Standard Ravelry API paths are targeted.
3. Returned payload data is structurally normalized.
4. The processed functions are exposed as callable MCP entities for AI interaction.

🛠️ System Architecture

src/ ├── class/ │ └── ravelry.class.ts # Core Ravelry API Client Module ├── endpoints/ │ ├── getMultiplePatternDetails.ts # Multi-ID Detail Retrieval Logic │ ├── getPatternDetails.ts # Single ID Detail Retrieval Logic │ ├── searchPatterns.ts # Pattern Index Query Logic │ └── index.ts # Endpoint Export Aggregator ├── types/ │ ├── patternDetailed.d.ts # Complex Pattern Type Definitions │ └── patternSimple.d.ts # Basic Pattern Type Definitions └── index.ts # Application Entry Point and Server Initialization

⚙️ Development Lifecycle

Configuration Management

Environment settings are managed via distinct configuration files: - .env.development - Active during iterative development. - .env.production - Used for stable, deployed execution.

Quality Assurance

Execute the automated validation suite via:

bash npm test

Code Hygiene

bash

Static analysis execution

npm run lint

Automated error correction

npm run lint:fix

Code style enforcement via Prettier

npm run format

📝 Production Deployment Directives

When transitioning to a live environment:

1. Affirm that .env.production holds correct Ravelry credentials.
2. The build step will serialize these credentials into the final executable artifact.
3. Initiate the server using npm run prod.

📄 Licensing

This software is distributed under the MIT License terms (refer to the [LICENSE] file for specifics).

WIKIPEDIA Context: XMLHttpRequest (XHR)

XMLHttpRequest (XHR) is defined as an API implemented via a JavaScript object responsible for dispatching HTTP transport requests from a web browser to a remote server. Its methods enable browser-based software components to communicate with the server subsequent to the initial page load, facilitating asynchronous data reception. XHR is foundational to the concept of Ajax programming. Before Ajax, server interaction predominantly relied on traditional page navigation via hyperlinks or full form submissions, which typically resulted in a full page refresh.

== Genesis == The underlying concept for XMLHttpRequest was first articulated in 2000 by Microsoft developers working on Outlook. This idea materialized in Internet Explorer 5 (1999), although the initial implementation did not utilize the 'XMLHttpRequest' string; instead, it employed 'ActiveXObject("Msxml2.XMLHTTP")' or 'ActiveXObject("Microsoft.XMLHTTP")'. By the release of Internet Explorer 7 (2006), universal browser support for the standard 'XMLHttpRequest' identifier had been established. This identifier subsequently became the accepted convention across major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) released its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 Working Draft followed on February 25, 2008, introducing capabilities for monitoring request progression, enabling cross-site access, and managing binary data streams. By the close of 2011, these Level 2 enhancements were integrated back into the primary specification. As of late 2012, development stewardship transferred to the WHATWG, which now maintains the living document utilizing Web IDL definitions.

== Operational Steps == The standard procedure for executing an asynchronous request via XMLHttpRequest involves several sequential programming actions:

1. Instantiation: Create the XMLHttpRequest object via its constructor.
2. Configuration: Invoke the "open" method to define the request method (GET/POST, etc.), specify the Uniform Resource Identifier (URI), and declare the operation as synchronous or asynchronous.
3. Event Handling: For asynchronous operations, attach a designated event listener to monitor state transitions.
4. Transmission: Initiate the transaction by calling the "send" method.
5. Response Processing: Within the event listener, check the object's state; upon reaching state 4 (the 'done' state), the server's data is accessible, typically within the "responseText" attribute.

Beyond these fundamental stages, XMLHttpRequest offers extensive control over request formulation and data parsing. Custom HTTP headers can be applied to influence server behavior. Payloads can be uploaded to the server via the argument provided to the "send" call. Furthermore, the incoming response can be immediately parsed from JSON format into a native JavaScript structure, or streamed incrementally rather than buffered entirely. Finally, requests possess the ability to be cancelled prematurely or configured to timeout if completion is not achieved within a defined temporal limit.

== Cross-Origin Transactions ==

During the nascent phases of the World Wide Web, the inability to break the Same-Origin Policy limited client-side script interactions to resources residing on the identical domain, a constraint later addressed by advancements like XHR Level 2 capabilities.