@moorchehai/mcp 1.3.1 → 1.3.3

package/README.md

@@ -1,296 +1,299 @@
-<div align="left">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="assets/moorcheh-logo-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="assets/moorcheh-logo-light.svg">
-    <img width="250px" alt="Moorcheh Logo" src="assets/moorcheh-logo-light.svg">
-  </picture>
-  <br />
-  <h1>Moorcheh MCP Server</h1>
-  <p>A Model Context Protocol (MCP) server that provides seamless integration with Moorcheh's Embedding, Vector Store, Search, and Gen AI Answer services. This server enables you to interact with Moorcheh's comprehensive AI capabilities including document embedding, vector storage, semantic search, and AI-powered answer generation through the Model Context Protocol.</p>
-</div>
-
-
-
-## Quick Start Guide
-
-There are two ways to use the Moorcheh MCP server:
-
-### Option 1: NPX (Recommended - No Installation Required)
-
-The easiest way to get started:
-
-```bash
-# Set your API key and run directly
-MOORCHEH_API_KEY=your_api_key_here npx -y @moorchehai/mcp
-```
-
-### Option 2: Manual Installation
-
-If you prefer to clone and run locally:
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/moorcheh-ai/moorcheh-mcp.git
-   cd moorcheh-mcp
-   ```
-
-2. **Install dependencies**
-   ```bash
-   npm install
-   ```
-
-### Step 2: Configure Your API Key
-
-1. **Get your Moorcheh API key**
-   - Visit [Moorcheh Dashboard](https://app.moorcheh.ai)
-   - Sign in to your account
-   - Go to your account settings
-   - Generate or copy your API key
-
-2. **Set up your environment**
-   ```bash
-   # Copy the example environment file
-   cp env.example .env
-   ```
-
-3. **Edit the .env file**
-   ```bash
-   # Open .env in your preferred editor
-   # Replace 'your_moorcheh_api_key_here' with your actual API key
-   MOORCHEH_API_KEY=your_actual_api_key_here
-   ```
-
-### Step 3: Start the Server
-
-```bash
-npm start
-```
-
-That's it! Your Moorcheh MCP server is now running and ready to use.
-
-## Setting Up with Claude Desktop
-
-To use the Moorcheh MCP server with Claude Desktop:
-
-
-
-https://github.com/user-attachments/assets/fccbba8e-7393-4b74-8a73-769b55b3f3a3
-
-
-### Step 1: Install Claude Desktop
-1. Download Claude Desktop from [https://claude.ai/download](https://claude.ai/download)
-2. Install and launch Claude Desktop
-
-### Step 2: Configure MCP Server
-
-**Option A: Using NPX (Recommended)**
-1. In Claude Desktop, go to **Settings** → **Developer** 
-2. Click **Edit Config**
-3. Configure the server with these settings:
-   ```json
-   {
-      "mcpServers": { 
-            "moorcheh": {
-               "command": "npx",
-               "args": ["-y", "@moorchehai/mcp"],
-               "env": {
-                  "MOORCHEH_API_KEY": "your_actual_api_key_here"
-               }
-            }
-      }
-   }
-   ```
-
-**Option B: Local Installation**
-1. In Claude Desktop, go to **Settings** → **Developer** 
-2. Click **Edit Config**
-3. Configure the server with these settings:
-   ```json
-   {
-      "mcpServers":{ 
-            "moorcheh": {
-               "command": "node",
-               "args": [
-               "path\\to\\moorcheh-mcp\\src\\server\\index.js"
-               ],
-               "env": {
-               "NODE_ENV": "development"
-               }
-            }
-      }
-   }
-   ```
-
-3. **Important**: 
-   - For **Option A**: Replace `your_actual_api_key_here` with your actual Moorcheh API key
-   - For **Option B**: Replace `path\\to\\moorcheh-mcp\\src\\server\\index.js` with the actual path to your `index.js` file and create .env in **moorcheh-mcp** with your API key
-4. Save the configuration file and restart Claude Desktop completely 
-
-### Step 3: Test the Connection
-1. Start a new conversation in Claude Desktop
-2. Ask Claude to list the available tools: "Can you list down my namespaces?"
-3. You should see tools like `list-namespaces`, `search`, `answer`, etc.
-
-## Setting Up with Cursor
-
-To use the Moorcheh MCP server with Cursor IDE:
-
-### Step 1: Install Cursor
-1. Download Cursor from [https://cursor.com](https://cursor.com)
-2. Install and launch Cursor
-
-### Step 2: Configure MCP Server
-
-**Option A: Using NPX (Recommended)**
-1. In Cursor, go to **Settings** → **Tools & integration** 
-2. Click **Add MCP Server**
-3. Configure the server with these settings:
-```json
-{
-   "mcpServers": { 
-         "moorcheh": {
-            "command": "npx",
-            "args": ["-y", "@moorchehai/mcp"],
-            "env": {
-               "MOORCHEH_API_KEY": "your_actual_api_key_here"
-            }
-         }
-   }
-}
-```
-
-**Option B: Local Installation**
-1. In Cursor, go to **Settings** → **Tools & integration** 
-2. Click **Add MCP Server**
-3. Configure the server with these settings:
-```json
-{
-   "mcpServers":{ 
-         "moorcheh": {
-            "command": "node",
-            "args": [
-            "path\\to\\moorcheh-mcp\\src\\server\\index.js"
-            ],
-            "env": {
-            "NODE_ENV": "development"
-            }
-         }
-   }
-}
-```
-
-### Step 3: Set Your API Key
-- **For Option A**: Replace `your_actual_api_key_here` with your actual Moorcheh API key in the configuration
-- **For Option B**: Create .env in **moorcheh-mcp** directory and add your API key with `MOORCHEH_API_KEY=your_key_here`
-
-### Step 4: Test the Connection
-1. Open a new chat in Cursor (Cmd/Ctrl + L)
-2. Ask the AI to list available Moorcheh tools: "What Moorcheh tools can I use?"
-3. You should see tools like `list-namespaces`, `search`, `answer`, etc.
-
-
-## What This Server Does
-
-The Moorcheh MCP server provides tools for:
-
-- **Namespace Management**: Create, list, and delete namespaces for organizing your data
-- **Document Operations**: Upload and manage text documents and vector embeddings
-- **Advanced Search**: Perform semantic search across your data 
-- **AI-Powered Answers**: Get intelligent responses based on your stored data 
-
-## Available Tools
-
-### Namespace Tools
-- **`list-namespaces`**: View all your available namespaces
-- **`create-namespace`**: Create a new namespace for storing data
-- **`delete-namespace`**: Remove a namespace and all its contents
-
-### Data Tools
-- **`upload-text`**: Upload text documents to a namespace
-- **`upload-vectors`**: Upload vector embeddings to a namespace
-- **`upload-file`**: Upload files directly to a text-type namespace (supports .pdf, .docx, .xlsx, .json, .txt, .csv, .md, max 10MB)
-- **`get-data`**: Retrieve text documents by ID from text namespaces
-- **`delete-data`**: Remove specific data items from a namespace
-
-### Search & AI Tools
-- **`search`**: Search across namespaces with vector similarity
-- **`answer`**: Get AI-generated answers based on top of your search 
-
-## Supported Bedrock Models
-
-| Model ID | Name | Provider | Description |
-|----------|------|----------|-------------|
-| `anthropic.claude-sonnet-4-20250514-v1:0` | Claude Sonnet 4 | Anthropic | Hybrid reasoning, extended thinking, efficient code generation |
-| `anthropic.claude-sonnet-4-5-20250929-v1:0` | Claude Sonnet 4.5 | Anthropic | Latest Claude model with enhanced capabilities and agentic search |
-| `meta.llama4-maverick-17b-instruct-v1:0` | Llama 4 Maverick 17B | Meta | 1M token context, fine tuning, text summarization, function calling |
-| `meta.llama3-3-70b-instruct-v1:0` | Llama 3.3 70B | Meta | Advanced reasoning and decision making capabilities |
-| `amazon.nova-pro-v1:0` | Amazon Nova Pro | Amazon | 300K context, chat optimized, complex reasoning, math |
-| `deepseek.r1-v1:0` | DeepSeek R1 | DeepSeek | Advanced reasoning and code generation |
-| `openai.gpt-oss-120b-1:0` | OpenAI GPT OSS 120B | OpenAI | Hybrid reasoning, extended thinking, efficient research |
-| `qwen.qwen3-32b-v1:0` | Qwen 3 32B | Qwen | Text generation and code generation |
-
-## Prerequisites
-
-- **Node.js**: Version 18.0.0 or higher
-- **Moorcheh Account**: Active account with API access
-- **Git**: For cloning the repository
-
-## Development
-
-### Development Mode
-For development with auto-reload:
-```bash
-npm run dev
-```
-
-### Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `npm start` | Start the MCP server |
-| `npm run dev` | Start in development mode with auto-reload |
-| `npm test` | Run tests (when available) |
-
-
-## Environment Variables
-
-| Variable | Description | Required | Default |
-|----------|-------------|----------|---------|
-| `MOORCHEH_API_KEY` | Your Moorcheh API key | Yes | None |
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Missing required API_KEY environment variable"**
-   - Make sure you've created a `.env` file
-   - Verify your API key is correctly set in the `.env` file
-   - Check that the API key is valid in your Moorcheh dashboard
-
-2. **"Forbidden: Check your API key"**
-   - Your API key may be invalid or expired
-   - Generate a new API key from the Moorcheh dashboard
-   - Update your `.env` file with the new key
-
-3. **"Network Error"**
-   - Check your internet connection
-   - Verify the API endpoints are accessible
-   - Try again in a few minutes
-
-### Getting Help
-
-- **GitHub Issues**: [https://github.com/moorcheh-ai/moorcheh-mcp/issues](https://github.com/moorcheh-ai/moorcheh-mcp/issues)
-- **Moorcheh Documentation**: [https://console.moorcheh.ai/docs/mcp](https://console.moorcheh.ai/docs/mcp)
-- **Moorcheh Dashboard**: [https://console.moorcheh.ai](https://console.moorcheh.ai)
-
-## License
-
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
-
-## Contributing
-
-We welcome contributions! Please feel free to submit a Pull Request.
-
-## Changelog
-
-For a detailed list of changes, see [CHANGELOG.md](CHANGELOG.md).
+<div align="left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/moorcheh-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/moorcheh-logo-light.svg">
+    <img width="250px" alt="Moorcheh Logo" src="assets/moorcheh-logo-light.svg">
+  </picture>
+  <br />
+  <h1>Moorcheh MCP Server</h1>
+  <p>A Model Context Protocol (MCP) server that provides seamless integration with Moorcheh's Embedding, Vector Store, Search, and Gen AI Answer services. This server enables you to interact with Moorcheh's comprehensive AI capabilities including document embedding, vector storage, semantic search, and AI-powered answer generation through the Model Context Protocol.</p>
+</div>
+
+
+
+## Quick Start Guide
+
+There are two ways to use the Moorcheh MCP server:
+
+### Option 1: NPX (Recommended - No Installation Required)
+
+The easiest way to get started:
+
+```bash
+# Set your API key and run directly
+MOORCHEH_API_KEY=your_api_key_here npx -y @moorchehai/mcp
+```
+
+### Option 2: Manual Installation
+
+If you prefer to clone and run locally:
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/moorcheh-ai/moorcheh-mcp.git
+   cd moorcheh-mcp
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+### Step 2: Configure Your API Key
+
+1. **Get your Moorcheh API key**
+   - Visit [Moorcheh Dashboard](https://app.moorcheh.ai)
+   - Sign in to your account
+   - Go to your account settings
+   - Generate or copy your API key
+
+2. **Set up your environment**
+   ```bash
+   # Copy the example environment file
+   cp env.example .env
+   ```
+
+3. **Edit the .env file**
+   ```bash
+   # Open .env in your preferred editor
+   # Replace 'your_moorcheh_api_key_here' with your actual API key
+   MOORCHEH_API_KEY=your_actual_api_key_here
+   ```
+
+### Step 3: Start the Server
+
+```bash
+npm start
+```
+
+That's it! Your Moorcheh MCP server is now running and ready to use.
+
+## Setting Up with Claude Desktop
+
+To use the Moorcheh MCP server with Claude Desktop:
+
+
+
+https://github.com/user-attachments/assets/fccbba8e-7393-4b74-8a73-769b55b3f3a3
+
+
+### Step 1: Install Claude Desktop
+1. Download Claude Desktop from [https://claude.ai/download](https://claude.ai/download)
+2. Install and launch Claude Desktop
+
+### Step 2: Configure MCP Server
+
+**Option A: Using NPX (Recommended)**
+1. In Claude Desktop, go to **Settings** → **Developer** 
+2. Click **Edit Config**
+3. Configure the server with these settings:
+   ```json
+   {
+      "mcpServers": { 
+            "moorcheh": {
+               "command": "npx",
+               "args": ["-y", "@moorchehai/mcp"],
+               "env": {
+                  "MOORCHEH_API_KEY": "your_actual_api_key_here"
+               }
+            }
+      }
+   }
+   ```
+
+**Option B: Local Installation**
+1. In Claude Desktop, go to **Settings** → **Developer** 
+2. Click **Edit Config**
+3. Configure the server with these settings:
+   ```json
+   {
+      "mcpServers":{ 
+            "moorcheh": {
+               "command": "node",
+               "args": [
+               "path\\to\\moorcheh-mcp\\src\\server\\index.js"
+               ],
+               "env": {
+               "NODE_ENV": "development"
+               }
+            }
+      }
+   }
+   ```
+
+3. **Important**: 
+   - For **Option A**: Replace `your_actual_api_key_here` with your actual Moorcheh API key
+   - For **Option B**: Replace `path\\to\\moorcheh-mcp\\src\\server\\index.js` with the actual path to your `index.js` file and create .env in **moorcheh-mcp** with your API key
+4. Save the configuration file and restart Claude Desktop completely 
+
+### Step 3: Test the Connection
+1. Start a new conversation in Claude Desktop
+2. Ask Claude to list the available tools: "Can you list down my namespaces?"
+3. You should see tools like `list-namespaces`, `search`, `answer`, etc.
+
+## Setting Up with Cursor
+
+To use the Moorcheh MCP server with Cursor IDE:
+
+### Step 1: Install Cursor
+1. Download Cursor from [https://cursor.com](https://cursor.com)
+2. Install and launch Cursor
+
+### Step 2: Configure MCP Server
+
+**Option A: Using NPX (Recommended)**
+1. In Cursor, go to **Settings** → **Tools & integration** 
+2. Click **Add MCP Server**
+3. Configure the server with these settings:
+```json
+{
+   "mcpServers": { 
+         "moorcheh": {
+            "command": "npx",
+            "args": ["-y", "@moorchehai/mcp"],
+            "env": {
+               "MOORCHEH_API_KEY": "your_actual_api_key_here"
+            }
+         }
+   }
+}
+```
+
+**Option B: Local Installation**
+1. In Cursor, go to **Settings** → **Tools & integration** 
+2. Click **Add MCP Server**
+3. Configure the server with these settings:
+```json
+{
+   "mcpServers":{ 
+         "moorcheh": {
+            "command": "node",
+            "args": [
+            "path\\to\\moorcheh-mcp\\src\\server\\index.js"
+            ],
+            "env": {
+            "NODE_ENV": "development"
+            }
+         }
+   }
+}
+```
+
+### Step 3: Set Your API Key
+- **For Option A**: Replace `your_actual_api_key_here` with your actual Moorcheh API key in the configuration
+- **For Option B**: Create .env in **moorcheh-mcp** directory and add your API key with `MOORCHEH_API_KEY=your_key_here`
+
+### Step 4: Test the Connection
+1. Open a new chat in Cursor (Cmd/Ctrl + L)
+2. Ask the AI to list available Moorcheh tools: "What Moorcheh tools can I use?"
+3. You should see tools like `list-namespaces`, `search`, `answer`, etc.
+
+
+## What This Server Does
+
+The Moorcheh MCP server provides tools for:
+
+- **Namespace Management**: Create, list, and delete namespaces for organizing your data
+- **Document Operations**: Upload and manage text documents and vector embeddings
+- **Advanced Search**: Perform semantic search across your data 
+- **AI-Powered Answers**: Get intelligent responses based on your stored data 
+
+## Available Tools
+
+### Namespace Tools
+- **`list-namespaces`**: View all your available namespaces
+- **`create-namespace`**: Create a new namespace for storing data
+- **`delete-namespace`**: Remove a namespace and all its contents
+
+### Data Tools
+- **`upload-text`**: Upload text documents to a namespace
+- **`upload-vectors`**: Upload vector embeddings to a namespace
+- **`upload-file`**: Upload files directly to a text-type namespace (supports .pdf, .docx, .xlsx, .json, .txt, .csv, .md, max 10MB)
+- **`get-data`**: Retrieve text documents by ID from text namespaces
+- **`delete-data`**: Remove specific data items from a namespace
+
+### Search & AI Tools
+- **`search`**: Search across namespaces with vector similarity
+- **`answer`**: Get AI-generated answers based on top of your search 
+
+## Supported AI models
+
+These IDs match the current Moorcheh [Available Models](https://docs.moorcheh.ai/python-sdk/ai/generate#available-models) list (REST `answer` / Python `answer.generate`).
+
+| Model ID | Name | Provider | Description |
+|----------|------|----------|-------------|
+| `anthropic.claude-sonnet-4-6` | Claude Sonnet 4.6 | Anthropic | Fast flagship: coding, tools, long docs and RAG (~1M context) |
+| `anthropic.claude-opus-4-6-v1` | Claude Opus 4.6 | Anthropic | Deepest reasoning and hardest tasks; pick when quality matters most (~1M context) |
+| `meta.llama4-maverick-17b-instruct-v1:0` | Llama 4 Maverick 17B | Meta | Long context, summarization, function calling, fine-tuning friendly |
+| `amazon.nova-pro-v1:0` | Amazon Nova Pro | Amazon | Chat, math, and structured answers for AWS-style workloads |
+| `deepseek.r1-v1:0` | DeepSeek R1 | DeepSeek | Step-by-step reasoning; math, logic, and technical explanations |
+| `deepseek.v3.2` | DeepSeek V3.2 | DeepSeek | Efficient general Q&A, multilingual, everyday RAG (~164K context) |
+| `openai.gpt-oss-120b-1:0` | OpenAI GPT OSS 120B | OpenAI | Large generalist: research-style answers and long-form writing |
+| `qwen.qwen3-32b-v1:0` | Qwen 3 32B | Qwen | Code and bilingual (EN/ZH) tasks in a smaller footprint |
+| `qwen.qwen3-next-80b-a3b` | Qwen3 Next 80B A3B | Qwen | MoE model for long chats, docs, and code at scale (~256K context) |
+
+## Prerequisites
+
+- **Node.js**: Version 18.0.0 or higher
+- **Moorcheh Account**: Active account with API access
+- **Git**: For cloning the repository
+
+## Development
+
+### Development Mode
+For development with auto-reload:
+```bash
+npm run dev
+```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm start` | Start the MCP server |
+| `npm run dev` | Start in development mode with auto-reload |
+| `npm test` | Run tests (when available) |
+
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `MOORCHEH_API_KEY` | Your Moorcheh API key | Yes | None |
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Missing required API_KEY environment variable"**
+   - Make sure you've created a `.env` file
+   - Verify your API key is correctly set in the `.env` file
+   - Check that the API key is valid in your Moorcheh dashboard
+
+2. **"Forbidden: Check your API key"**
+   - Your API key may be invalid or expired
+   - Generate a new API key from the Moorcheh dashboard
+   - Update your `.env` file with the new key
+
+3. **"Network Error"**
+   - Check your internet connection
+   - Verify the API endpoints are accessible
+   - Try again in a few minutes
+
+### Getting Help
+
+- **GitHub Issues**: [https://github.com/moorcheh-ai/moorcheh-mcp/issues](https://github.com/moorcheh-ai/moorcheh-mcp/issues)
+- **Moorcheh Documentation**: [https://console.moorcheh.ai/docs/mcp](https://console.moorcheh.ai/docs/mcp)
+- **Moorcheh Dashboard**: [https://console.moorcheh.ai](https://console.moorcheh.ai)
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+We welcome contributions! Please feel free to submit a Pull Request.
+
+## Changelog
+
+For a detailed list of changes, see [CHANGELOG.md](CHANGELOG.md).