airweave-mcp-search 0.5.7

package/README.md

@@ -0,0 +1,360 @@
+# Airweave MCP Search Server
+
+An MCP (Model Context Protocol) server that provides comprehensive search capabilities for Airweave collections. This server allows AI assistants to search through your Airweave data using natural language queries with full parameter control.
+
+## Features
+
+- 🔍 **Enhanced Search Tool**: Query Airweave collections with natural language and full parameter control
+- 🤖 **AI Completion**: Get AI-processed responses from search results
+- 📊 **Pagination Control**: Limit results and control pagination with offset
+- ⏰ **Recency Bias**: Prioritize recent results with configurable recency weighting
+- ⚙️ **Configuration Tool**: View current server configuration
+- 🔐 **Secure**: Uses API key authentication
+- 🌐 **Flexible**: Configurable base URL for different environments
+- 🧪 **Comprehensive Testing**: Full test suite with LLM testing strategy
+- 🏗️ **Simple Architecture**: Clean, maintainable code structure without over-engineering
+
+## Version History
+
+### v2.1.0 - Advanced Search Features
+
+🚀 **New advanced search capabilities:**
+
+- **Advanced Parameters**: Added `score_threshold`, `search_method`, `expansion_strategy`, `enable_reranking`, `enable_query_interpretation`
+- **Smart Endpoint Selection**: Automatically uses POST endpoint for advanced features, GET for basic search
+- **Enhanced AI Integration**: Better parameter extraction from natural language queries
+- **Comprehensive Testing**: Full test suite including LLM simulation tests
+
+### v2.0.0 - Enhanced Search Parameters
+
+⚠️ **Major version update with breaking changes:**
+
+- **Parameter Structure**: The search tool now uses an object-based parameter structure instead of positional arguments
+- **New Parameters**: Added `limit`, `offset`, and `recency_bias` parameters
+- **Enhanced Validation**: Improved parameter validation with detailed error messages
+- **Version Bump**: Updated from v1.0.7 to v2.0.0
+
+**Migration Guide:**
+```typescript
+// Old format (v1.0.7)
+search("customer feedback", "raw")
+
+// New format (v2.0.0+)
+search({ query: "customer feedback", response_type: "raw" })
+```
+
+## Quick Start
+
+### Installation from npm
+
+The easiest way to use this server is via npx:
+
+```bash
+npx airweave-mcp-search
+```
+
+### Installation from GitHub
+THIS IS NOT CORRECT, THE MCP IS NOT A SEPARATE REPO YET
+
+You can also install directly from the GitHub repository:
+
+```bash
+npm install -g https://github.com/your-org/airweave-mcp-search.git
+```
+
+## Configuration
+
+The server requires environment variables to connect to your Airweave instance:
+
+### Required Environment Variables
+
+- `AIRWEAVE_API_KEY`: Your Airweave API key (get this from your Airweave dashboard)
+- `AIRWEAVE_COLLECTION`: The readable ID of the collection to search
+
+### Optional Environment Variables
+
+- `AIRWEAVE_BASE_URL`: Base URL for the Airweave API (default: `https://api.airweave.ai`)
+
+## Usage with Cursor/Claude Desktop
+
+### 1. Configure in Claude Desktop
+
+Add the following to your Claude Desktop configuration file (`~/.cursor/mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "airweave-search": {
+      "command": "npx",
+      "args": ["airweave-mcp-search"],
+      "env": {
+        "AIRWEAVE_API_KEY": "your-api-key-here",
+        "AIRWEAVE_COLLECTION": "your-collection-id",
+        "AIRWEAVE_BASE_URL": "https://api.airweave.ai"
+      }
+    }
+  }
+}
+```
+
+### 2. Local Development Configuration
+
+For local development with a self-hosted Airweave instance:
+
+```json
+{
+  "mcpServers": {
+    "airweave-search": {
+      "command": "node",
+      "args": ["/absolute/path/to/airweave/mcp/build/index.js"],
+      "env": {
+        "AIRWEAVE_API_KEY": "your-api-key-here",
+        "AIRWEAVE_COLLECTION": "your-collection-id",
+        "AIRWEAVE_BASE_URL": "http://localhost:8001"
+      }
+    }
+  }
+}
+```
+
+### 3. Using the Tools
+
+Once configured, you can use natural language to search:
+
+- "Search for customer feedback about pricing"
+- "Find documents related to API documentation"
+- "Look up information about data privacy policies"
+
+## Available Tools
+
+### `search-{collection}`
+
+Searches within the configured Airweave collection with full parameter control.
+
+**Parameters:**
+
+**Core Parameters:**
+- `query` (required): The search query text to find relevant documents and data
+- `response_type` (optional, default: "raw"): Format of the response: 'raw' returns search results, 'completion' returns AI-generated answers
+- `limit` (optional, default: 100): Maximum number of results to return (1-1000)
+- `offset` (optional, default: 0): Number of results to skip for pagination (≥0)
+- `recency_bias` (optional): How much to weigh recency vs similarity (0..1). 0 = no recency effect; 1 = rank by recency only
+
+**Advanced Parameters:**
+- `score_threshold` (optional): Minimum similarity score threshold (0..1). Only return results above this score
+- `search_method` (optional): Search method: 'hybrid' (default, combines neural + keyword), 'neural' (semantic only), 'keyword' (text matching only)
+- `expansion_strategy` (optional): Query expansion strategy: 'auto' (default, generates query variations), 'llm' (AI-powered expansion), 'no_expansion' (use exact query)
+- `enable_reranking` (optional): Enable LLM-based reranking to improve result relevance (default: true)
+- `enable_query_interpretation` (optional): Enable automatic filter extraction from natural language query (default: true)
+
+**Examples:**
+```typescript
+// Basic search
+search({ query: "customer feedback about pricing" })
+
+// Search with AI completion
+search({ 
+  query: "billing issues", 
+  response_type: "completion" 
+})
+
+// Paginated search
+search({ 
+  query: "API documentation", 
+  limit: 10, 
+  offset: 20 
+})
+
+// Recent results with recency bias
+search({ 
+  query: "customer complaints", 
+  recency_bias: 0.8 
+})
+
+// Advanced search with high-quality results
+search({ 
+  query: "customer complaints", 
+  score_threshold: 0.8,
+  search_method: "neural",
+  enable_reranking: true
+})
+
+// Fast keyword search without expansion
+search({ 
+  query: "API documentation", 
+  search_method: "keyword",
+  expansion_strategy: "no_expansion",
+  enable_reranking: false
+})
+
+// Full parameter search
+search({ 
+  query: "support tickets", 
+  response_type: "completion",
+  limit: 5,
+  offset: 0,
+  recency_bias: 0.7,
+  score_threshold: 0.6,
+  search_method: "hybrid",
+  expansion_strategy: "llm",
+  enable_reranking: true,
+  enable_query_interpretation: true
+})
+```
+
+### `get-config`
+
+Shows the current server configuration and status.
+
+**Parameters:** None
+
+**Example:**
+```
+get-config()
+```
+
+## API Integration
+
+This server interfaces with the Airweave Collections API:
+
+- **Endpoint**: `GET /collections/{collection_id}/search`
+- **Authentication**: `x-api-key` header
+- **Query Parameters**:
+  - `query`: Search query string
+  - `response_type`: `RAW` or `COMPLETION`
+
+## Testing
+
+This MCP server includes comprehensive testing to ensure reliability and proper LLM interaction.
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run LLM-specific tests
+npm run test:llm
+```
+
+### Test Categories
+
+1. **Unit Tests**: Parameter validation and schema testing
+2. **Integration Tests**: API calls and error handling
+3. **LLM Tests**: How AI assistants interact with the enhanced parameters
+
+### LLM Testing Strategy
+
+The server includes a comprehensive LLM testing framework to evaluate how different AI assistants use the enhanced parameters:
+
+- **Basic Tests**: Simple parameter usage
+- **Advanced Tests**: Complex parameter combinations
+- **Error Tests**: Invalid parameter handling
+- **Edge Tests**: Boundary conditions and special cases
+
+See `tests/llm-testing-strategy.md` for detailed testing methodology.
+
+## Development
+
+### Building from Source
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd airweave/mcp
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+4. Run locally:
+```bash
+AIRWEAVE_API_KEY=your-key AIRWEAVE_COLLECTION=your-collection npm run start
+```
+
+### Development Workflow
+
+```bash
+# Build and run
+npm run dev
+
+# Build only
+npm run build
+
+# Run built version
+npm run start
+
+# Run tests
+npm test
+```
+
+## Error Handling
+
+The server provides detailed error messages for common issues:
+
+- **Missing API Key**: Clear message when `AIRWEAVE_API_KEY` is not set
+- **Missing Collection**: Clear message when `AIRWEAVE_COLLECTION` is not set
+- **API Errors**: Detailed error messages from the Airweave API
+- **Network Issues**: Connection and timeout error handling
+
+## Security
+
+- API keys are never logged or exposed in responses
+- All requests use HTTPS (when using the default base URL)
+- Environment variables are validated at startup
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Error: AIRWEAVE_API_KEY environment variable is required"**
+   - Make sure you've set the `AIRWEAVE_API_KEY` environment variable
+   - Check that your API key is valid and has access to the collection
+
+2. **"Error: AIRWEAVE_COLLECTION environment variable is required"**
+   - Set the `AIRWEAVE_COLLECTION` environment variable to your collection's readable ID
+   - Verify the collection ID exists in your Airweave instance
+
+3. **"Airweave API error (404)"**
+   - Check that the collection ID is correct
+   - Verify the collection exists and you have access to it
+
+4. **"Airweave API error (401)"**
+   - Check that your API key is valid
+   - Ensure the API key has the necessary permissions
+
+### Debug Mode
+
+For debugging, you can check the stderr output where the server logs its startup information:
+
+```bash
+# The server logs to stderr (won't interfere with MCP protocol)
+# Look for messages like:
+# "Airweave MCP Search Server started"
+# "Collection: your-collection-id"
+# "Base URL: https://api.airweave.ai"
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For issues and questions:
+- Check the [Airweave documentation](https://docs.airweave.ai)
+- Open an issue on GitHub
+- Contact your Airweave administrator for API key and access issues

package/build/api/airweave-client.d.ts

@@ -0,0 +1,10 @@
+import { AirweaveConfig, SearchResponse } from './types.js';
+export declare class AirweaveClient {
+    private config;
+    private client;
+    constructor(config: AirweaveConfig);
+    search(searchRequest: any): Promise<SearchResponse>;
+    private hasAdvancedParameters;
+    private getMockResponse;
+}
+//# sourceMappingURL=airweave-client.d.ts.map

package/build/api/airweave-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"airweave-client.d.ts","sourceRoot":"","sources":["../../src/api/airweave-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,qBAAa,cAAc;IAGX,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,MAAM,CAAoB;gBAEd,MAAM,EAAE,cAAc;IAOpC,MAAM,CAAC,aAAa,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC;IAoCzD,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,eAAe;CAkD1B"}

package/build/api/airweave-client.js

@@ -0,0 +1,102 @@
+// Airweave API client using the official SDK
+import { AirweaveSDKClient } from '@airweave/sdk';
+export class AirweaveClient {
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        this.client = new AirweaveSDKClient({
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl
+        });
+    }
+    async search(searchRequest) {
+        // Mock mode for testing
+        if (this.config.apiKey === 'test-key' && this.config.baseUrl.includes('localhost')) {
+            return this.getMockResponse(searchRequest);
+        }
+        try {
+            // Check if this should use advanced search (POST endpoint)
+            const hasAdvancedParams = this.hasAdvancedParameters(searchRequest);
+            if (hasAdvancedParams) {
+                // Use the official SDK for advanced search
+                const response = await this.client.collections.searchAdvanced(this.config.collection, searchRequest);
+                return response;
+            }
+            else {
+                // Use the official SDK for basic search
+                const { query, response_type, limit, offset, recency_bias } = searchRequest;
+                const response = await this.client.collections.search(this.config.collection, {
+                    query,
+                    response_type,
+                    limit,
+                    offset,
+                    recency_bias
+                });
+                return response;
+            }
+        }
+        catch (error) {
+            // Handle SDK errors and convert to our error format
+            if (error.statusCode) {
+                throw new Error(`Airweave API error (${error.statusCode}): ${error.message}`);
+            }
+            else {
+                throw new Error(`Airweave API error: ${error.message}`);
+            }
+        }
+    }
+    hasAdvancedParameters(params) {
+        return !!(params.score_threshold !== undefined ||
+            params.search_method !== undefined ||
+            params.expansion_strategy !== undefined ||
+            params.enable_reranking !== undefined ||
+            params.enable_query_interpretation !== undefined);
+    }
+    getMockResponse(request) {
+        const { query, response_type, limit, offset, recency_bias, score_threshold, search_method, expansion_strategy, enable_reranking, enable_query_interpretation } = request;
+        // Generate mock results based on the query
+        const mockResults = [];
+        const resultCount = Math.min(limit || 100, 5); // Limit to 5 for testing
+        const hasAdvancedParams = this.hasAdvancedParameters(request);
+        for (let i = 0; i < resultCount; i++) {
+            const score = 0.95 - (i * 0.1);
+            // Apply score threshold if specified
+            if (score_threshold !== undefined && score < score_threshold) {
+                continue;
+            }
+            mockResults.push({
+                score: score,
+                payload: {
+                    source_name: `Mock Source ${i + 1}`,
+                    entity_id: `mock_${i + 1}`,
+                    title: `Mock Document ${i + 1} about "${query}"`,
+                    md_content: `This is a mock response for the query "${query}". This document contains relevant information about ${query} and demonstrates how the MCP server would return search results.`,
+                    created_at: new Date(Date.now() - (i * 24 * 60 * 60 * 1000)).toISOString(), // Different dates
+                    metadata: {
+                        test: true,
+                        query: query,
+                        limit: limit,
+                        offset: offset,
+                        recency_bias: recency_bias,
+                        score_threshold: score_threshold,
+                        search_method: search_method,
+                        expansion_strategy: expansion_strategy,
+                        enable_reranking: enable_reranking,
+                        enable_query_interpretation: enable_query_interpretation,
+                        used_advanced_search: hasAdvancedParams
+                    }
+                }
+            });
+        }
+        return {
+            results: mockResults,
+            response_type: response_type || "raw",
+            status: "success",
+            completion: response_type === "completion"
+                ? `Based on the search results for "${query}", here's a comprehensive summary of the findings...`
+                : undefined
+        };
+    }
+}
+//# sourceMappingURL=airweave-client.js.map

package/build/api/airweave-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"airweave-client.js","sourceRoot":"","sources":["../../src/api/airweave-client.ts"],"names":[],"mappings":"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"}

package/build/api/types.d.ts

@@ -0,0 +1,9 @@
+import { AirweaveSDK } from '@airweave/sdk';
+export type SearchResponse = AirweaveSDK.SearchResponse;
+export type SearchRequest = AirweaveSDK.SearchRequest;
+export interface AirweaveConfig {
+    apiKey: string;
+    collection: string;
+    baseUrl: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,cAAc,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,aAAa,CAAC;AAGtD,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACnB"}

package/build/api/types.js

@@ -0,0 +1,3 @@
+// Type definitions for Airweave API responses
+export {};
+//# sourceMappingURL=types.js.map

package/build/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA,8CAA8C"}

package/build/config/constants.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_BASE_URL = "https://api.airweave.ai";
+export declare const DEFAULT_LIMIT = 100;
+export declare const DEFAULT_OFFSET = 0;
+export declare const DEFAULT_RESPONSE_TYPE = "raw";
+export declare const PARAMETER_LIMITS: {
+    readonly QUERY_MIN_LENGTH: 1;
+    readonly QUERY_MAX_LENGTH: 1000;
+    readonly LIMIT_MIN: 1;
+    readonly LIMIT_MAX: 1000;
+    readonly OFFSET_MIN: 0;
+    readonly RECENCY_BIAS_MIN: 0;
+    readonly RECENCY_BIAS_MAX: 1;
+};
+export declare const ERROR_MESSAGES: {
+    readonly MISSING_API_KEY: "Error: AIRWEAVE_API_KEY environment variable is required";
+    readonly MISSING_COLLECTION: "Error: AIRWEAVE_COLLECTION environment variable is required";
+    readonly INVALID_JSON_RESPONSE: "Invalid JSON response";
+    readonly API_ERROR: "Airweave API error";
+    readonly PARAMETER_VALIDATION_ERROR: "Parameter Validation Errors";
+};
+//# sourceMappingURL=constants.d.ts.map

package/build/config/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/config/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,eAAO,MAAM,gBAAgB;;;;;;;;CAQnB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC"}

package/build/config/constants.js

@@ -0,0 +1,22 @@
+// Configuration constants for the MCP server
+export const DEFAULT_BASE_URL = "https://api.airweave.ai";
+export const DEFAULT_LIMIT = 100;
+export const DEFAULT_OFFSET = 0;
+export const DEFAULT_RESPONSE_TYPE = "raw";
+export const PARAMETER_LIMITS = {
+    QUERY_MIN_LENGTH: 1,
+    QUERY_MAX_LENGTH: 1000,
+    LIMIT_MIN: 1,
+    LIMIT_MAX: 1000,
+    OFFSET_MIN: 0,
+    RECENCY_BIAS_MIN: 0.0,
+    RECENCY_BIAS_MAX: 1.0
+};
+export const ERROR_MESSAGES = {
+    MISSING_API_KEY: "Error: AIRWEAVE_API_KEY environment variable is required",
+    MISSING_COLLECTION: "Error: AIRWEAVE_COLLECTION environment variable is required",
+    INVALID_JSON_RESPONSE: "Invalid JSON response",
+    API_ERROR: "Airweave API error",
+    PARAMETER_VALIDATION_ERROR: "Parameter Validation Errors"
+};
+//# sourceMappingURL=constants.js.map

package/build/config/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/config/constants.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAE7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,gBAAgB,EAAE,CAAC;IACnB,gBAAgB,EAAE,IAAI;IACtB,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,CAAC;IACb,gBAAgB,EAAE,GAAG;IACrB,gBAAgB,EAAE,GAAG;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG;IAC1B,eAAe,EAAE,0DAA0D;IAC3E,kBAAkB,EAAE,6DAA6D;IACjF,qBAAqB,EAAE,uBAAuB;IAC9C,SAAS,EAAE,oBAAoB;IAC/B,0BAA0B,EAAE,6BAA6B;CACnD,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/build/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Main entry point for the Airweave MCP Search Server
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer, validateEnvironment } from "./server.js";
+// Validate environment variables and get configuration
+const config = validateEnvironment();
+// Create MCP server
+const server = createMcpServer(config);
+// Main function to start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr so it doesn't interfere with MCP protocol
+    console.error("Airweave MCP Search Server started");
+    console.error(`Collection: ${config.collection}`);
+    console.error(`Base URL: ${config.baseUrl}`);
+}
+// Handle graceful shutdown
+process.on("SIGINT", () => {
+    console.error("Shutting down Airweave MCP server...");
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    console.error("Shutting down Airweave MCP server...");
+    process.exit(0);
+});
+// Start the server
+main().catch((error) => {
+    console.error("Fatal error in Airweave MCP server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,sDAAsD;AAEtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEnE,uDAAuD;AACvD,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;AAErC,oBAAoB;AACpB,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAEvC,oCAAoC;AACpC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,CAAC,KAAK,CAAC,eAAe,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,2BAA2B;AAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;IACzB,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,mBAAmB;AACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AirweaveConfig } from "./api/types.js";
+export declare function createMcpServer(config: AirweaveConfig): McpServer;
+export declare function validateEnvironment(): AirweaveConfig;
+//# sourceMappingURL=server.d.ts.map

package/build/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKhD,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,aAoCrD;AAED,wBAAgB,mBAAmB,IAAI,cAAc,CAgBpD"}

package/build/server.js

@@ -0,0 +1,42 @@
+// MCP server setup and tool registration
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AirweaveClient } from "./api/airweave-client.js";
+import { createSearchTool } from "./tools/search-tool.js";
+import { createConfigTool } from "./tools/config-tool.js";
+import { DEFAULT_BASE_URL, ERROR_MESSAGES } from "./config/constants.js";
+export function createMcpServer(config) {
+    // Create MCP server instance
+    const server = new McpServer({
+        name: "airweave-search",
+        version: "2.1.0", // Minor version bump for advanced search features
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Create dynamic tool name based on collection
+    const toolName = `search-${config.collection}`;
+    // Initialize Airweave client
+    const airweaveClient = new AirweaveClient(config);
+    // Create tools
+    const searchTool = createSearchTool(toolName, config.collection, airweaveClient);
+    const configTool = createConfigTool(toolName, config.collection, config.baseUrl, config.apiKey);
+    // Register tools
+    server.tool(searchTool.name, searchTool.description, searchTool.schema, searchTool.handler);
+    server.tool(configTool.name, configTool.description, configTool.schema, configTool.handler);
+    return server;
+}
+export function validateEnvironment() {
+    const apiKey = process.env.AIRWEAVE_API_KEY;
+    const collection = process.env.AIRWEAVE_COLLECTION;
+    const baseUrl = process.env.AIRWEAVE_BASE_URL || DEFAULT_BASE_URL;
+    if (!apiKey) {
+        console.error(ERROR_MESSAGES.MISSING_API_KEY);
+        process.exit(1);
+    }
+    if (!collection) {
+        console.error(ERROR_MESSAGES.MISSING_COLLECTION);
+        process.exit(1);
+    }
+    return { apiKey, collection, baseUrl };
+}
+//# sourceMappingURL=server.js.map

package/build/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,yCAAyC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEzE,MAAM,UAAU,eAAe,CAAC,MAAsB;IAClD,6BAA6B;IAC7B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QACzB,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,OAAO,EAAE,kDAAkD;QACpE,YAAY,EAAE;YACV,KAAK,EAAE,EAAE;SACZ;KACJ,CAAC,CAAC;IAEH,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,UAAU,MAAM,CAAC,UAAU,EAAE,CAAC;IAE/C,6BAA6B;IAC7B,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IAElD,eAAe;IACf,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACjF,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAEhG,iBAAiB;IACjB,MAAM,CAAC,IAAI,CACP,UAAU,CAAC,IAAI,EACf,UAAU,CAAC,WAAW,EACtB,UAAU,CAAC,MAAM,EACjB,UAAU,CAAC,OAAO,CACrB,CAAC;IAEF,MAAM,CAAC,IAAI,CACP,UAAU,CAAC,IAAI,EACf,UAAU,CAAC,WAAW,EACtB,UAAU,CAAC,MAAM,EACjB,UAAU,CAAC,OAAO,CACrB,CAAC;IAEF,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,mBAAmB;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACnD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,gBAAgB,CAAC;IAElE,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC"}

package/build/tools/config-tool.d.ts

@@ -0,0 +1,12 @@
+export declare function createConfigTool(toolName: string, collection: string, baseUrl: string, apiKey: string): {
+    name: string;
+    description: string;
+    schema: {};
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=config-tool.d.ts.map

package/build/tools/config-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-tool.d.ts","sourceRoot":"","sources":["../../src/tools/config-tool.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;;;;;;;EA0BrG"}

package/build/tools/config-tool.js

@@ -0,0 +1,29 @@
+// Configuration tool implementation
+export function createConfigTool(toolName, collection, baseUrl, apiKey) {
+    return {
+        name: "get-config",
+        description: "Get the current Airweave MCP server configuration",
+        schema: {}, // Empty schema for no parameters
+        handler: async () => {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "**Airweave MCP Server Configuration:**",
+                            "",
+                            `- **Collection ID:** ${collection}`,
+                            `- **Base URL:** ${baseUrl}`,
+                            `- **API Key:** ${apiKey ? "✓ Configured" : "✗ Missing"}`,
+                            "",
+                            "**Available Commands:**",
+                            `- \`${toolName}\`: Search within the configured Airweave collection`,
+                            "- `get-config`: Show this configuration information",
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+    };
+}
+//# sourceMappingURL=config-tool.js.map

package/build/tools/config-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-tool.js","sourceRoot":"","sources":["../../src/tools/config-tool.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,UAAkB,EAAE,OAAe,EAAE,MAAc;IAClG,OAAO;QACH,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,mDAAmD;QAChE,MAAM,EAAE,EAAE,EAAE,iCAAiC;QAC7C,OAAO,EAAE,KAAK,IAAI,EAAE;YAChB,OAAO;gBACH,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACF,wCAAwC;4BACxC,EAAE;4BACF,wBAAwB,UAAU,EAAE;4BACpC,mBAAmB,OAAO,EAAE;4BAC5B,kBAAkB,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE;4BACzD,EAAE;4BACF,yBAAyB;4BACzB,OAAO,QAAQ,sDAAsD;4BACrE,qDAAqD;yBACxD,CAAC,IAAI,CAAC,IAAI,CAAC;qBACf;iBACJ;aACJ,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/build/tools/search-tool.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { AirweaveClient } from "../api/airweave-client.js";
+export declare function createSearchTool(toolName: string, collection: string, airweaveClient: AirweaveClient): {
+    name: string;
+    description: string;
+    schema: {
+        query: z.ZodString;
+        response_type: z.ZodDefault<z.ZodOptional<z.ZodEnum<["raw", "completion"]>>>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        recency_bias: z.ZodOptional<z.ZodNumber>;
+        score_threshold: z.ZodOptional<z.ZodNumber>;
+        search_method: z.ZodOptional<z.ZodEnum<["hybrid", "neural", "keyword"]>>;
+        expansion_strategy: z.ZodOptional<z.ZodEnum<["auto", "llm", "no_expansion"]>>;
+        enable_reranking: z.ZodOptional<z.ZodBoolean>;
+        enable_query_interpretation: z.ZodOptional<z.ZodBoolean>;
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=search-tool.d.ts.map

package/build/tools/search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tool.d.ts","sourceRoot":"","sources":["../../src/tools/search-tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,cAAc;;;;;;;;;;;;;;;sBA2DF,GAAG;;;;;;EA4BlC"}

package/build/tools/search-tool.js

@@ -0,0 +1,84 @@
+// Search tool implementation
+import { z } from "zod";
+import { formatSearchResponse, formatErrorResponse } from "../utils/error-handling.js";
+export function createSearchTool(toolName, collection, airweaveClient) {
+    // Define the enhanced schema shape for MCP SDK (ZodRawShape format)
+    const searchSchema = {
+        // Core parameters (existing)
+        query: z.string().min(1).max(1000).describe("The search query text to find relevant documents and data"),
+        response_type: z.enum(["raw", "completion"]).optional().default("raw").describe("Format of the response: 'raw' returns search results, 'completion' returns AI-generated answers"),
+        limit: z.number().min(1).max(1000).optional().default(100).describe("Maximum number of results to return"),
+        offset: z.number().min(0).optional().default(0).describe("Number of results to skip for pagination"),
+        recency_bias: z.number().min(0).max(1).optional().describe("How much to weigh recency vs similarity (0..1). 0 = no recency effect; 1 = rank by recency only"),
+        // Advanced parameters (Phase 1 - safe parameters)
+        score_threshold: z.number().min(0).max(1).optional().describe("Minimum similarity score threshold (0..1). Only return results above this score"),
+        search_method: z.enum(["hybrid", "neural", "keyword"]).optional().describe("Search method: 'hybrid' (combines neural + keyword), 'neural' (semantic only), 'keyword' (text matching only)"),
+        expansion_strategy: z.enum(["auto", "llm", "no_expansion"]).optional().describe("Query expansion strategy: 'auto' (generates query variations), 'llm' (AI-powered expansion), 'no_expansion' (use exact query)"),
+        enable_reranking: z.boolean().optional().describe("Enable LLM-based reranking to improve result relevance"),
+        enable_query_interpretation: z.boolean().optional().describe("Enable automatic filter extraction from natural language query")
+    };
+    // Create the full schema for validation
+    const fullSchema = z.object(searchSchema);
+    const parameterDescriptions = [
+        "**Core Parameters:**",
+        "- `query`: The search query text to find relevant documents and data (required)",
+        "- `response_type`: Format of the response: 'raw' returns search results, 'completion' returns AI-generated answers (optional, default: raw)",
+        "- `limit`: Maximum number of results to return (optional, default: 100)",
+        "- `offset`: Number of results to skip for pagination (optional, default: 0)",
+        "- `recency_bias`: How much to weigh recency vs similarity (0..1). 0 = no recency effect; 1 = rank by recency only (optional)",
+        "",
+        "**Advanced Parameters:**",
+        "- `score_threshold`: Minimum similarity score threshold (0..1). Only return results above this score (optional)",
+        "- `search_method`: Search method: 'hybrid' (default, combines neural + keyword), 'neural' (semantic only), 'keyword' (text matching only) (optional)",
+        "- `expansion_strategy`: Query expansion strategy: 'auto' (default, generates query variations), 'llm' (AI-powered expansion), 'no_expansion' (use exact query) (optional)",
+        "- `enable_reranking`: Enable LLM-based reranking to improve result relevance (default: true) (optional)",
+        "- `enable_query_interpretation`: Enable automatic filter extraction from natural language query (default: true) (optional)"
+    ].join("\n");
+    const naturalLanguageExamples = [
+        "**Natural Language Examples:**",
+        "",
+        "**Basic Search:**",
+        "- 'Find the first 5 results' → limit: 5",
+        "- 'Show me results 11-20' → limit: 10, offset: 10",
+        "- 'Give me a summary' → response_type: 'completion'",
+        "- 'Find the most recent documents' → recency_bias: 0.8",
+        "",
+        "**Advanced Search:**",
+        "- 'Find high-quality results only' → score_threshold: 0.8",
+        "- 'Use keyword search instead of semantic' → search_method: 'keyword'",
+        "- 'Don't expand my query' → expansion_strategy: 'no_expansion'",
+        "- 'Disable reranking' → enable_reranking: false",
+        "- 'Find recent high-quality results' → recency_bias: 0.7, score_threshold: 0.8"
+    ].join("\n");
+    return {
+        name: toolName,
+        description: `Enhanced search within the Airweave collection '${collection}' with advanced filtering and ranking options.\n\n**Parameters:**\n${parameterDescriptions}\n\n${naturalLanguageExamples}`,
+        schema: searchSchema, // Use the shape, not the full ZodObject
+        handler: async (params) => {
+            try {
+                // Zod will automatically validate and apply defaults
+                const validatedParams = fullSchema.parse(params);
+                const { response_type } = validatedParams;
+                const searchResponse = await airweaveClient.search(validatedParams);
+                return formatSearchResponse(searchResponse, response_type);
+            }
+            catch (error) {
+                console.error("Error in search tool:", error);
+                if (error instanceof z.ZodError) {
+                    // Handle validation errors
+                    const errorMessages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `**Parameter Validation Errors:**\n${errorMessages.join("\n")}`,
+                            },
+                        ],
+                    };
+                }
+                return formatErrorResponse(error, params);
+            }
+        }
+    };
+}
+//# sourceMappingURL=search-tool.js.map

package/build/tools/search-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tool.js","sourceRoot":"","sources":["../../src/tools/search-tool.ts"],"names":[],"mappings":"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"}

package/build/utils/error-handling.d.ts

@@ -0,0 +1,14 @@
+import { SearchResponse } from "../api/types.js";
+export declare function formatSearchResponse(searchResponse: SearchResponse, responseType: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function formatErrorResponse(error: Error, searchRequest: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+//# sourceMappingURL=error-handling.d.ts.map

package/build/utils/error-handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.d.ts","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM;;;;;EA2CxF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG;;;;;EAWnE"}

package/build/utils/error-handling.js

@@ -0,0 +1,55 @@
+// Error handling utilities
+export function formatSearchResponse(searchResponse, responseType) {
+    if (responseType === "completion") {
+        // For AI completion, return the completion text
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: searchResponse.completion || "No response generated",
+                },
+            ],
+        };
+    }
+    else {
+        // For raw results, format the search results simply
+        const formattedResults = searchResponse.results
+            .map((result, index) => {
+            const parts = [
+                `**Result ${index + 1}${result.score ? ` (Score: ${result.score.toFixed(3)})` : ""}:**`
+            ];
+            // Extract content from various possible fields
+            const content = result.content || result.text || result.payload?.content || result.payload?.text || JSON.stringify(result, null, 2);
+            parts.push(content);
+            return parts.join("\n");
+        })
+            .join("\n\n---\n\n");
+        const summaryText = [
+            `**Collection:** ${process.env.AIRWEAVE_COLLECTION}`,
+            `**Results:** ${searchResponse.results.length}`,
+            "",
+            formattedResults || "No results found.",
+        ].join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: summaryText,
+                },
+            ],
+        };
+    }
+}
+export function formatErrorResponse(error, searchRequest) {
+    const errorMessage = error.message;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `**Error:** Failed to search collection.\n\n**Details:** ${errorMessage}\n\n**Debugging Info:**\n- Collection: ${process.env.AIRWEAVE_COLLECTION}\n- Base URL: ${process.env.AIRWEAVE_BASE_URL || "https://api.airweave.ai"}\n- Endpoint: /collections/${process.env.AIRWEAVE_COLLECTION}/search\n- Parameters: ${JSON.stringify(searchRequest, null, 2)}`,
+            },
+        ],
+    };
+}
+// Validation errors are now handled directly in the search tool
+//# sourceMappingURL=error-handling.js.map

package/build/utils/error-handling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.js","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAK3B,MAAM,UAAU,oBAAoB,CAAC,cAA8B,EAAE,YAAoB;IACrF,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;QAChC,gDAAgD;QAChD,OAAO;YACH,OAAO,EAAE;gBACL;oBACI,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,cAAc,CAAC,UAAU,IAAI,uBAAuB;iBAC7D;aACJ;SACJ,CAAC;IACN,CAAC;SAAM,CAAC;QACJ,oDAAoD;QACpD,MAAM,gBAAgB,GAAG,cAAc,CAAC,OAAO;aAC1C,GAAG,CAAC,CAAC,MAAW,EAAE,KAAK,EAAE,EAAE;YACxB,MAAM,KAAK,GAAG;gBACV,YAAY,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;aAC1F,CAAC;YAEF,+CAA+C;YAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACpI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC;aACD,IAAI,CAAC,aAAa,CAAC,CAAC;QAEzB,MAAM,WAAW,GAAG;YAChB,mBAAmB,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE;YACpD,gBAAgB,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE;YAC/C,EAAE;YACF,gBAAgB,IAAI,mBAAmB;SAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO;YACH,OAAO,EAAE;gBACL;oBACI,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,WAAW;iBACpB;aACJ;SACJ,CAAC;IACN,CAAC;AACL,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAY,EAAE,aAAkB;IAChE,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC;IAEnC,OAAO;QACH,OAAO,EAAE;YACL;gBACI,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,2DAA2D,YAAY,0CAA0C,OAAO,CAAC,GAAG,CAAC,mBAAmB,iBAAiB,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,yBAAyB,8BAA8B,OAAO,CAAC,GAAG,CAAC,mBAAmB,0BAA0B,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;aACnW;SACJ;KACJ,CAAC;AACN,CAAC;AAED,gEAAgE"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "airweave-mcp-search",
+  "version": "0.5.7",
+  "description": "MCP server for searching Airweave collections",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "airweave-mcp-search": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "start": "node build/index.js",
+    "dev": "npm run build && npm run start",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run tests/integration-live.test.ts --reporter=verbose",
+    "test:llm": "node tests/run-llm-tests.js",
+    "test:ci": "npm run test && npm run test:integration && npm run test:llm",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "airweave",
+    "search",
+    "model-context-protocol",
+    "ai",
+    "vector-search",
+    "claude",
+    "cursor"
+  ],
+  "author": "Airweave",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/airweave-ai/airweave.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://airweave.ai",
+  "bugs": {
+    "url": "https://github.com/airweave-ai/airweave/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@airweave/sdk": "^0.5.4",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@vitest/coverage-v8": "^2.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ]
+}