searchcraft-mcp-server An MCP Server powered by Searchcraft – the developer-first vertical search engine. The Searchcraft MCP Server provides a suite of tools for managing your Searchcraft cluster's Documents, Indexes, Federations, Access Keys, and Analytics. It enables MCP Clients, like Claude Desktop, to be prompted in plain English to perform administrative actions like setting up search indexe
Add this skill
npx mdskills install searchcraft-inc/searchcraft-mcp-serverComprehensive MCP server with 50+ well-documented tools for search engine administration and app generation
1<img alt="ReTail website screenshot" src="./header.png">2<h1 align="center">searchcraft-mcp-server</h1>3<p align="center">4An MCP Server powered by <a href="https://searchcraft.io">Searchcraft</a> – the developer-first vertical search engine.5</p>67<p align="center">8 <a href="https://www.typescriptlang.org/">9 <img src="https://img.shields.io/badge/TypeScript-5.8-blue.svg?logo=typescript&style=flat" alt="TypeScript">10 </a>11 <a href="https://nodejs.org/en/">12 <img src="https://img.shields.io/badge/Node.js-22+-339933.svg?logo=node.js&style=flat" alt="Node.js">13 </a>14 <a href="https://expressjs.com/">15 <img src="https://img.shields.io/badge/Express-5.1-330033.svg?logo=express&style=flat" alt="Node.js">16 </a>17</p>1819The Searchcraft MCP Server provides a suite of tools for managing your Searchcraft cluster's Documents, Indexes, Federations, Access Keys, and Analytics. It enables MCP Clients, like Claude Desktop, to be prompted in plain English to perform administrative actions like setting up search indexes, access keys, ingesting documents, viewing analytics, searching indexes, and more.2021## Building an app in 2 minutes with Searchcraft MCP Server (video link)2223<div align="center">24 <a href="https://youtu.be/Vs_98sUrFqA?si=m9aH-tvUAAFwQQVy" title="Watch the video">25 <img src="https://img.youtube.com/vi/Vs_98sUrFqA/hqdefault.jpg" alt="Building an app in 2 minutes with Searchcraft MCP Server">26 </a>27</div>2829## Sample Prompts3031Here is a sample prompt that could be used once Claude is connected to the Searchcraft MCP Server.3233```text34I'd like to create a product search application using the create_vite_app tool.3536Please use this JSON dataset https://dummyjson.com/products37First use the Searchcraft create_index_from_json tool to create the index and add the documents.3839Then create an API read key for the vite app using the create_key tool.4041App details:42- App name: "my-ecommerce-app"43- Endpoint: http://localhost:800044- Index name: my-ecommerce-app45```4647## Available Tools4849The Searchcraft MCP Server currently provides three categories of tools, import tools, engine api tools, and app generation tools:5051### Engine API Tools5253These tools provide direct access to your Searchcraft cluster's core functionality for managing indexes, documents, federations, authentication, and search operations.5455#### Index Management5657| Tool Name | Description |58|-----------|-------------|59| create_index | Create a new index with the specified schema. This will empty the index if it already exists. |60| delete_index | Delete an index and all its documents permanently. |61| get_all_index_stats | Get document counts and statistics for all indexes. |62| get_index_schema | Get the schema definition for a specific index. |63| get_index_stats | Get statistics and metadata for a specific index (document count, etc.). |64| list_all_indexes | Get a list of all indexes in the Searchcraft instance. |65| patch_index | Make partial configuration changes to an index schema (search_fields, weight_multipliers, etc.). |66| update_index | Replace the entire contents of an existing index with a new schema definition. |6768#### Document Management6970| Tool Name | Description |71|-----------|-------------|72| add_documents | Add one or multiple documents to an index. Documents should be provided as an array of JSON objects. |73| delete_all_documents | Delete all documents from an index. The index will continue to exist after all documents are deleted. |74| delete_document_by_id | Delete a single document from an index by its internal Searchcraft ID (_id). |75| delete_documents_by_field | Delete one or several documents from an index by field term match (e.g., {id: 'xyz'} or {title: 'foo'}). |76| delete_documents_by_query | Delete one or several documents from an index by query match. |77| get_document_by_id | Get a single document from an index by its internal Searchcraft ID (_id). |7879#### Federation Management8081| Tool Name | Description |82|-----------|-------------|83| create_federation | Create or update a federation with the specified configuration. |84| delete_federation | Delete a federation permanently. |85| get_federation_details | Get detailed information for a specific federation. |86| get_federation_stats | Get document counts per index for a federation as well as the total document count. |87| get_organization_federations | Get a list of all federations for a specific organization. |88| list_all_federations | Get a list of all federations in the Searchcraft instance. |89| update_federation | Replace the current federation entity with an updated one. |9091#### Authentication & Key Management9293| Tool Name | Description |94|-----------|-------------|95| create_key | Create a new authentication key with specified permissions and access controls. |96| delete_all_keys | Delete all authentication keys on the Searchcraft cluster. Use with extreme caution! |97| delete_key | Delete a specific authentication key permanently. |98| get_application_keys | Get a list of all authentication keys associated with a specific application. |99| get_federation_keys | Get a list of all authentication keys associated with a specific federation. |100| get_key_details | Get detailed information for a specific authentication key. |101| get_organization_keys | Get a list of all authentication keys associated with a specific organization. |102| list_all_keys | Get a list of all authentication keys on the Searchcraft cluster. |103| update_key | Update an existing authentication key with new configuration. |104105#### Stopwords Management106107| Tool Name | Description |108|-----------|-------------|109| add_stopwords | Add custom stopwords to an index. These are added on top of the default language-specific dictionary. |110| delete_all_stopwords | Delete all custom stopwords from an index. This only affects custom stopwords, not the default language dictionary. |111| delete_stopwords | Delete specific custom stopwords from an index. This only affects custom stopwords, not the default language dictionary. |112| get_index_stopwords | Get all stopwords for an index, including both default language dictionary and custom stopwords. |113114#### Synonyms Management115116| Tool Name | Description |117|-----------|-------------|118| add_synonyms | Add synonyms to an index. Synonyms only work with fuzzy queries, not exact match queries. |119| delete_all_synonyms | Delete all synonyms from an index. |120| delete_synonyms | Delete specific synonyms from an index by their keys. |121| get_index_synonyms | Get all synonyms defined for an index. |122123#### Search & Analytics124125| Tool Name | Description |126|-----------|-------------|127| get_measure_conversion | Get measurement conversion data with optional filtering and aggregation parameters. *requires Clickhouse if running locally |128| get_measure_summary | Get measurement summary data with optional filtering and aggregation parameters. *requires Clickhouse if running locally|129| get_search_results | Performs a search query using the Searchcraft API with support for fuzzy/exact matching, facets, and date ranges. |130| get_prelim_search_data | Get schema fields and facet information for a search index to understand available fields for constructing queries. |131| get_searchcraft_status | Get the current status of the Searchcraft search service. |132133### Import Tools134135These tools provide workflows for importing JSON data and automatically generating Searchcraft schemas. Perfect for quickly setting up new indexes from existing data sources.136137| Tool Name | Description |138|-----------|-------------|139| analyze_json_from_file | Read JSON data from a local file and analyze its structure to understand field types and patterns for Searchcraft index schema generation. |140| analyze_json_from_url | Fetch JSON data from a URL and analyze its structure to understand field types and patterns for Searchcraft index schema generation. |141| generate_searchcraft_schema | Generate a complete Searchcraft index schema from analyzed JSON structure, with customizable options for search fields, weights, and other index settings. |142| create_index_from_json | Complete workflow to create a Searchcraft index from JSON data. Fetches JSON from URL or file, analyzes structure, generates schema, creates the index, and adds all documents in one step. |143144#### Import Tools Workflow145146The import tools are designed to work together in a streamlined workflow:1471481. **Analyze** → Use `analyze_json_from_file` or `analyze_json_from_url` to examine your JSON data structure1492. **Generate** → Use `generate_searchcraft_schema` to create a customized Searchcraft schema from the analysis1503. **Create** → Use the Engine API `create_index` tool to create the index with your generated schema1514. **Import** → Use `add_documents` to populate your new index with data152153**Or use the all-in-one approach:**154155- **One-Step** → Use `create_index_from_json` to analyze, generate schema, create the index, and import all documents in one command156157### App Generation Tools158159These tools create complete, ready-to-run search applications from your JSON data, perfect for prototyping and demos.160161| Tool Name | Description |162|-----------|-------------|163| create_vite_app | Creates a complete Vite + React search application from JSON data. Analyzes your data structure, generates optimized search templates, and creates a fully functional web app with Searchcraft integration. |164165#### App Generation Workflow166167The app generation tools provide an end-to-end solution for creating search applications:1681691. **Data Analysis** → Automatically analyzes your JSON structure to understand field types and content1702. **Template Generation** → Creates optimized search result templates based on your data fields1713. **App Creation** → Clones and configures a complete Vite + React application1724. **Environment Setup** → Configures Searchcraft connection settings1735. **Ready to Run** → Provides a fully functional search app you can immediately start and customize174175## Detailed Tool Usage176177### Using create_index_from_json178179The `create_index_from_json` tool provides a complete workflow to create a Searchcraft index from JSON data in a single command. This is perfect for quickly setting up search indexes from existing datasets. Note, if you know the language of the data you are importing you should specify it with the `language` parameter (use the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two letter code for the language)180181#### Parameters182183| Parameter | Type | Required | Description |184|-----------|------|----------|-------------|185| `source` | `"url"` or `"file"` | ✅ | Whether to fetch data from a URL or read from a local file |186| `path` | `string` | ✅ | URL or file path to the JSON data |187| `index_name` | `string` | ✅ | Name for the new Searchcraft index |188| `sample_size` | `number` | ❌ | Number of items to analyze for schema generation (default: 10) |189| `search_fields` | `string[]` | ❌ | Override automatically detected search fields |190| `weight_multipliers` | `object` | ❌ | Custom field weights for search relevance (0.0-10.0) |191| `language` | `string` | ❌ | Language code for the index (e.g., "en", "es") |192| `auto_commit_delay` | `number` | ❌ | Auto commit delay in seconds |193| `exclude_stop_words` | `boolean` | ❌ | Whether to exclude stop words from search |194| `time_decay_field` | `string` | ❌ | Field name for time-based relevance decay |195196#### Example Usage197198**From a URL:**199200```json201{202 "source": "url",203 "path": "https://api.example.com/products.json",204 "index_name": "products",205 "sample_size": 50,206 "search_fields": ["title", "description", "category"],207 "weight_multipliers": {208 "title": 2.0,209 "description": 1.0,210 "category": 1.5211 }212}213```214215**From a local file:**216```json217{218 "source": "file",219 "path": "/path/to/data.json",220 "index_name": "my_data",221 "language": "en"222}223```224225#### What it does2262271. **Fetches/Reads Data** → Downloads from URL or reads from local file2282. **Analyzes Structure** → Examines JSON to understand field types and patterns2293. **Generates Schema** → Creates optimized Searchcraft index schema2304. **Creates Index** → Sets up the index in your Searchcraft cluster2315. **Imports Documents** → Adds all JSON data as searchable documents2326. **Returns Summary** → Provides detailed information about what was created233234#### Expected JSON Format235236The tool works with various JSON structures:237238- **Array of objects**: `[{...}, {...}, ...]`239- **Object with array property**: `{"data": [{...}, {...}], "meta": {...}}`240- **Single object**: `{...}` (will be treated as a single document)241242The tool automatically finds the best array of objects to use for the index.243244### Using create_vite_app245246The `create_vite_app` tool creates a complete, ready-to-run search application from your JSON data. It's perfect for quickly prototyping search interfaces or creating demo applications.247248#### Parameters249250| Parameter | Type | Required | Description |251|-----------|------|----------|-------------|252| `data_source` | `"url"` or `"file"` | ✅ | Whether to fetch data from a URL or read from a local file |253| `data_path` | `string` | ✅ | URL or file path to the JSON data |254| `app_name` | `string` | ✅ | Name for the generated app (used for directory name) |255| `VITE_ENDPOINT_URL` | `string` | ✅ | Your Searchcraft cluster endpoint URL |256| `VITE_INDEX_NAME` | `string` | ✅ | The Searchcraft index name to connect to |257| `VITE_READ_KEY` | `string` | ✅ | Searchcraft read key for the application |258| `sample_size` | `number` | ❌ | Number of items to analyze for template generation (default: 50) |259| `search_fields` | `string[]` | ❌ | Override automatically detected search fields |260| `weight_multipliers` | `object` | ❌ | Custom field weights for search relevance (0.0-10.0) |261262#### Example Usage263264If you saw the [prompt](#sample-prompts) earlier in the documentation you can easily use the `create_vite_app` tool with natural language. However, you want finer grain control you can use the tool with JSON parameters.265266**Creating a product search app:**267```json268{269 "data_source": "url",270 "data_path": "https://api.example.com/products.json",271 "app_name": "product-search",272 "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",273 "VITE_INDEX_NAME": "products",274 "VITE_READ_KEY": "your_read_key_here",275 "sample_size": 100,276 "search_fields": ["title", "description", "brand"],277 "weight_multipliers": {278 "title": 2.5,279 "description": 1.0,280 "brand": 1.8281 }282}283```284285**Creating a blog search app from local data:**286```json287{288 "data_source": "file",289 "data_path": "/path/to/blog-posts.json",290 "app_name": "blog-search",291 "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",292 "VITE_INDEX_NAME": "blog_posts",293 "VITE_READ_KEY": "your_read_key_here"294}295```296297#### What it does2982991. **Analyzes Data Structure** → Examines your JSON to understand field types and content patterns3002. **Generates Search Templates** → Creates optimized result display templates based on your data3013. **Clones Vite Template** → Downloads the official Searchcraft Vite + React template3024. **Installs Dependencies** → Sets up all required npm packages3035. **Configures Environment** → Creates `.env` file with your Searchcraft settings3046. **Customizes Templates** → Generates dynamic search result components3057. **Updates App Code** → Modifies the main app with your specific branding and configuration306307#### Generated App Features308309The created application includes:310311- **React + Vite** → Modern, fast development setup312- **Searchcraft SDK Integration** → Full search functionality out of the box313- **Responsive Design** → Works on desktop and mobile devices314- **Auto-generated Templates** → Smart result display based on your data structure315- **Environment Configuration** → Easy setup for different environments316- **Development Server** → Hot reload for rapid customization317318#### Template Generation Logic319320The tool intelligently analyzes your data to create optimal search result templates:321322- **Title Field Detection** → Finds the best field to use as the main title323- **Description Field Detection** → Identifies descriptive text fields324- **Image Field Detection** → Locates image URLs for visual results325- **Date Field Detection** → Finds timestamp fields for temporal sorting326- **Additional Fields** → Includes other relevant text fields for comprehensive results327328#### Next Steps After Creation329330Once the app is created, you can:3313321. **Start Vite Server**:333 ```bash334 cd apps/your-app-name335 yarn dev336 ```3373382. **Customize Styling** → Modify CSS and components to match your brand3393403. **Add Features** → Extend with filters, facets, or advanced search options3413424. **Deploy** → Build and deploy to your preferred hosting platform343344#### Prerequisites345346- **Existing Searchcraft Index** → The index specified in `VITE_INDEX_NAME` should already exist347- **Valid Read Key** → The `VITE_READ_KEY` must have read permissions for the index348- **Git Available** → The tool uses git to clone the template repository349- **Node.js & Yarn** → Required for dependency installation350351### Complete Workflow: From JSON to Search App352353Here's how to use both tools together to go from raw JSON data to a fully functional search application:354355#### Option 1: Two-Step Process (Recommended for Production)356357**Step 1: Create the Searchcraft Index**358```json359{360 "source": "url",361 "path": "https://api.example.com/products.json",362 "index_name": "products",363 "sample_size": 100,364 "search_fields": ["title", "description", "category", "brand"],365 "weight_multipliers": {366 "title": 2.5,367 "description": 1.0,368 "category": 1.8,369 "brand": 1.5370 },371 "language": "en"372}373```374375**Step 2: Create the Search Application**376```json377{378 "data_source": "url",379 "data_path": "https://api.example.com/products.json",380 "app_name": "product-search-app",381 "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",382 "VITE_INDEX_NAME": "products",383 "VITE_READ_KEY": "your_read_key_here",384 "sample_size": 100,385 "search_fields": ["title", "description", "category", "brand"],386 "weight_multipliers": {387 "title": 2.5,388 "description": 1.0,389 "category": 1.8,390 "brand": 1.5391 }392}393```394395#### Option 2: App-Only Process (For Existing Indexes)396397If you already have a Searchcraft index set up, you can jump straight to creating the app:398399```json400{401 "data_source": "url",402 "data_path": "https://api.example.com/products.json",403 "app_name": "my-search-app",404 "VITE_ENDPOINT_URL": "https://your-cluster.searchcraft.io",405 "VITE_INDEX_NAME": "existing_index",406 "VITE_READ_KEY": "your_read_key_here"407}408```409410#### Benefits of the Two-Step Approach411412- **Index Optimization** → Fine-tune your search index separately from the UI413- **Multiple Apps** → Create different search interfaces for the same data414- **Production Ready** → Better separation of concerns for production deployments415- **Easier Debugging** → Test search functionality independently of the UI416417## Getting Started418419### Environment Variables420Create `.env` file at the project's root and fill in the values:421422```423# Server Config424USER_AGENT=searchcraft-mcp-server/<project-version>425DEBUG=true426PORT=3100427428# Searchcraft Config429ENDPOINT_URL= # The endpoint url of your Searchcraft Cluster430CORE_API_KEY= # The Searchcraft API key of your Searchcraft cluster. Must match the permissions required by the tools you are using.431```432433[.env sample](.env.example)434435### Remote Usage436437If you have already created an index through Vektron on Searchcraft Cloud you may use the write key for the index you are trying to access and use the MCP server for API operations that don't require admin privileges.438**IMPORTANT**: If you use the MCP server with a write key it should **NOT** be publicly exposed to the internet. Write keys are intended to be secured and by running an MCP server any user with access to the MCP server will be able to write to the index or delete data.439440### Installation & Setup441442Make sure your environment has the correct version of node selected.443```bash444nvm use445```446447Install dependencies with yarn448```bash449yarn450```451452Build the server453```bash454yarn build455```456457This creates two server versions:458- `dist/server.js` - HTTP server for testing and remote deployment459- `dist/stdio-server.js` - stdio server for Claude Desktop460461## Usage462463### Option 1: Claude Desktop (stdio) - Recommended464465For local use with Claude Desktop, use the stdio version which provides better performance and reliability.466467**claude_desktop_config.json**468```json469{470 "mcpServers": {471 "searchcraft": {472 "command": "node",473 "args": [474 "/path/to/searchcraft-mcp-server/dist/stdio-server.js"475 ]476 }477 }478}479```480481The claude desktop config file can be found at:482- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`483- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`484485If the file doesn't exist, create it.486487### Option 2: Claude Code488489For use with Claude Code, use the CLI to configure the MCP server:490491**Basic setup:**492```bash493# Add the Searchcraft MCP server to Claude Code494claude mcp add searchcraft -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js495```496497**With environment variables:**498```bash499# Add with your Searchcraft cluster configuration500claude mcp add searchcraft \501 --env ENDPOINT_URL=https://your-cluster.searchcraft.io \502 --env CORE_API_KEY=YOUR_API_KEY \503 -- node /path/to/searchcraft-mcp-server/dist/stdio-server.js504```505506**Configuration scopes:**507- `--scope local` (default): Available only to you in the current project508- `--scope project`: Shared with team via `.mcp.json` file (recommended for teams)509- `--scope user`: Available to you across all projects510511**Managing servers:**512```bash513# List configured servers514claude mcp list515516# Check server status517/mcp518519# Remove server520claude mcp remove searchcraft521```522523### Option 3: Open WebUI (via Pipelines)524525Open WebUI supports MCP servers through its Pipelines framework. This requires creating a custom pipeline that bridges your MCP server to Open WebUI.526527**Step 1: Start the Searchcraft MCP HTTP server**528```bash529yarn start # Starts HTTP server on port 3100530```531532**Step 2: Create an MCP Pipeline for Open WebUI**533534Create a file called `searchcraft_mcp_pipeline.py`:535536```python537"""538title: Searchcraft MCP Pipeline539author: Searchcraft Team540version: 1.0.0541license: Apache-2.0542description: A pipeline that integrates Searchcraft MCP server with Open WebUI543requirements: requests544"""545546import requests547import json548from typing import List, Union, Generator, Iterator549from pydantic import BaseModel550551552class Pipeline:553 class Valves(BaseModel):554 MCP_SERVER_URL: str = "http://localhost:3100/mcp"555 ENDPOINT_URL: str = ""556 CORE_API_KEY: str = ""557558 def __init__(self):559 self.name = "Searchcraft MCP Pipeline"560 self.valves = self.Valves()561562 async def on_startup(self):563 print(f"on_startup:{__name__}")564565 async def on_shutdown(self):566 print(f"on_shutdown:{__name__}")567568 def pipe(569 self, user_message: str, model_id: str, messages: List[dict], body: dict570 ) -> Union[str, Generator, Iterator]:571 # This pipeline acts as a bridge between Open WebUI and your MCP server572 # You can customize this to handle specific Searchcraft operations573574 # Example: If user mentions search operations, route to MCP server575 if any(keyword in user_message.lower() for keyword in ['search', 'index', 'document', 'searchcraft']):576 try:577 # Initialize MCP session578 init_payload = {579 "jsonrpc": "2.0",580 "id": 1,581 "method": "initialize",582 "params": {583 "protocolVersion": "2025-06-18",584 "capabilities": {},585 "clientInfo": {"name": "open-webui-pipeline", "version": "1.0.0"}586 }587 }588589 response = requests.post(self.valves.MCP_SERVER_URL, json=init_payload)590591 if response.status_code == 200:592 # Add context about available Searchcraft tools593 enhanced_message = f"""594{user_message}595596[Available Searchcraft MCP Tools: create_index, delete_index, add_documents, get_search_results, list_all_indexes, get_index_stats, create_key, delete_key, and 20+ more tools for managing Searchcraft clusters]597"""598 return enhanced_message599600 except Exception as e:601 print(f"MCP connection error: {e}")602603 return user_message604```605606**Step 3: Install the Pipeline in Open WebUI**6076081. **Via Admin Panel:**609 - Go to Admin Settings → Pipelines610 - Click "Add Pipeline"611 - Paste the pipeline code above612 - Configure the valves with your Searchcraft settings:613 - `MCP_SERVER_URL`: `http://localhost:3100/mcp`614 - `ENDPOINT_URL`: Your Searchcraft cluster URL615 - `CORE_API_KEY`: Your Searchcraft API key6166172. **Via Docker Environment:**618 ```bash619 # Save the pipeline to a file and mount it620 docker run -d -p 3000:8080 \621 -v open-webui:/app/backend/data \622 -v ./searchcraft_mcp_pipeline.py:/app/backend/data/pipelines/searchcraft_mcp_pipeline.py \623 --name open-webui \624 ghcr.io/open-webui/open-webui:main625 ```626627**Step 4: Configure Open WebUI to use Pipelines**6286291. Start Open WebUI with Pipelines support:630 ```bash631 # Using Docker Compose (recommended)632 services:633 openwebui:634 image: ghcr.io/open-webui/open-webui:main635 ports:636 - "3000:8080"637 volumes:638 - open-webui:/app/backend/data639 environment:640 - OPENAI_API_BASE_URL=http://pipelines:9099641 - OPENAI_API_KEY=0p3n-w3bu!642643 pipelines:644 image: ghcr.io/open-webui/pipelines:main645 volumes:646 - pipelines:/app/pipelines647 environment:648 - PIPELINES_API_KEY=0p3n-w3bu!649 ```6506512. In Open WebUI Settings → Connections:652 - Set OpenAI API URL to your Pipelines instance653 - Enable the Searchcraft MCP Pipeline654655### Option 4: HTTP Server (for testing/remote deployment)656657Start the HTTP server for testing, debugging, or remote deployment:658659```bash660yarn start # Starts HTTP server on port 3100661```662663For Claude Desktop with HTTP server, you'll need [mcp-remote](https://github.com/geelen/mcp-remote):664665**claude_desktop_config.json**666```json667{668 "mcpServers": {669 "searchcraft": {670 "command": "npx",671 "args": [672 "mcp-remote",673 "http://localhost:3100/mcp"674 ]675 }676 }677}678```679680### Option 5: Docker681682Run the Searchcraft MCP server in a Docker container for easy deployment and portability.683684**Build the Docker image:**685```bash686docker build --load -t searchcraft-mcp-server .687```688689**Run the container:**690```bash691docker run -it -p 8000:8000 \692 --name searchcraft-mcp-server \693 -e ENDPOINT_URL="https://your-cluster.searchcraft.io" \694 -e CORE_API_KEY="your_searchcraft_core_API_key" \695 searchcraft-mcp-server696```697698**Test the server:**699```bash700# Health check701curl http://localhost:8000/health702703# Test MCP endpoint704curl -X POST http://localhost:8000/mcp \705 -H "Content-Type: application/json" \706 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'707```708709**Remote inspection with MCP Inspector:**710```bash711npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8000/mcp712```713714**Docker Configuration:**715- Uses Node.js 22-slim as the base image716- Exposes port 3100 by default (configurable via `PORT` environment variable)717- Automatically handles graceful shutdown on SIGINT/SIGTERM718- Optimized for production with minimal image size719720**Environment Variables:**721- `PORT` - HTTP server port (default: 8000)722- `ENDPOINT_URL` - Your Searchcraft cluster endpoint URL723- `CORE_API_KEY` - Your Searchcraft API key724- `DEBUG` - Enable debug logging (optional)725726### Available Scripts727728```bash729# Development730yarn dev # Watch HTTP server731yarn dev:stdio # Watch stdio server732733# Production734yarn start # Start HTTP server735yarn start:stdio # Start stdio server736737# Testing738yarn inspect # Launch MCP inspector739yarn claude-logs # View Claude Desktop logs740```741742## Deployment Options Comparison743744| Feature | stdio (Recommended) | HTTP (Local) | Docker |745|---------|---------------------|--------------|--------|746| **Performance** | ✅ Best (Direct IPC) | ⚠️ HTTP overhead | ✅ Good |747| **Security** | ✅ No exposed ports | ⚠️ Network port required | ✅ Isolated environment |748| **Setup Complexity** | ✅ Simple | ⚠️ Port management needed | ✅ Simple (one command) |749| **Claude Desktop** | ✅ Native support | ⚠️ Requires mcp-remote | ⚠️ Requires mcp-remote |750| **Claude Code** | ✅ Native support | ✅ Supported | ✅ Supported |751| **Open WebUI** | ❌ Not supported | ✅ Via Pipelines | ✅ Via Pipelines |752| **Remote Deployment** | ❌ Local only | ✅ Possible but manual | ✅ Easy containerization |753| **Testing** | ⚠️ Requires MCP tools | ✅ Easy with curl | ✅ Easy with curl |754| **Multiple Clients** | ❌ One at a time | ✅ Concurrent access | ✅ Concurrent access |755| **Portability** | ⚠️ Node.js required | ⚠️ Node.js required | ✅ Runs anywhere |756757**Use stdio when:**758- Using Claude Desktop or Claude Code locally759- You want the absolute best performance760- You prefer direct process communication761762**Use HTTP (local) when:**763- You need to test/debug the HTTP interface764- You're developing custom integrations765- You need multiple concurrent local clients766767**Use Docker when:**768- You need remote deployment769- You want easy, reproducible setup770- You're deploying to cloud platforms771- You want isolation and security772- You need to publish your server for inspection773774## Testing775776The Searchcraft MCP Server includes a comprehensive test suite built with Vitest.777778### Run Tests779780```bash781# Run all tests782npm test783784# Run tests in watch mode785npm run test:watch786787# Run tests with coverage788npm run test:coverage789790# Show test reports791npm run test:ui792```793794### Test Coverage795796- ✅ **89 tests** covering core functionality797- ✅ **84%+ coverage** on helpers and utilities798- ✅ **93%+ coverage** on JSON analyzer799- ✅ **100% coverage** on server creation800- ✅ Integration tests for HTTP endpoints801- ✅ Unit tests for all major components802803See [test/README.md](test/README.md) for detailed testing documentation.804805## Debugging806807### Claude Desktop Logs808809To view Claude Desktop's logs for debugging MCP connections:810```bash811yarn claude-logs812```813814### Testing with MCP Inspector815816The MCP Inspector allows you to test your server tools interactively.817818**For stdio server (recommended):**819```bash820yarn inspect821```822- Choose Transport Type: stdio823- Command: `node dist/stdio-server.js`824825**For HTTP server:**826```bash827yarn start # Start HTTP server first828yarn inspect829```830- Choose Transport Type: Streamable HTTP831- URL: `http://localhost:3100/mcp`832833### Manual Testing834835**Test HTTP server:**836```bash837# Health check838curl http://localhost:3100/health839840# Test MCP endpoint841curl -X POST http://localhost:3100/mcp \842 -H "Content-Type: application/json" \843 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'844```845846**Test stdio server:**847```bash848echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/stdio-server.js849```850851## Resources852853- 📘 [Searchcraft Docs](https://docs.searchcraft.io)854- 🛰️ [Vektron Dashboard](https://vektron.searchcraft.io)855- 💬 [Searchcraft Discord](https://discord.gg/RQnGD63qWw)856- 🧠 [Searchcraft Reddit](https://www.reddit.com/r/searchcraft/)857- 🧪 [Searchcraft SDK on npm](https://www.npmjs.com/package/@searchcraft/react-sdk)858859## Issues and Feature Requests860861Visit https://github.com/searchcraft-inc/searchcraft-issues862863## License864865Licensed under the [Apache 2.0 License](LICENSE).866867<p align="center">868Built with 🛰️ by the <a href="https://searchcraft.io">Searchcraft</a> team869</p>870
Full transparency — inspect the skill content before installing.