@amplify-studio/open-mcp 0.8.1 → 0.9.0

package/README.md

@@ -11,10 +11,9 @@ Open MCP is a comprehensive server solution that enables AI assistants (like Cla
 ## Current Features
 
 ### 🌐 Web Search
-- General web queries with pagination
-- Time-based filtering (day, month, year)
-- Language selection
-- Safe search levels
+- General web queries via Firecrawl API
+- Configurable result limit (default: 10, max: 100)
+- JSON-formatted structured output
 
 ### 📄 URL Content Reading
 - Extract web page content as text/markdown
@@ -80,56 +79,67 @@ Open MCP is a comprehensive server solution that enables AI assistants (like Cla
 
 ## Installation
 
-### Option 1: From npm (Recommended for Users)
-
-Install from npm registry:
+### Option 1: From npm (Recommended)
 
 **Using Claude CLI:**
 ```bash
-claude mcp add @amplify-studio/open-mcp
+claude mcp add-json -s user open-mcp '{
+  "command": "npx",
+  "args": ["-y", "@amplify-studio/open-mcp@latest"]
+}'
+```
+
+**With custom gateway:**
+```bash
+claude mcp add-json -s user open-mcp '{
+  "command": "npx",
+  "args": ["-y", "@amplify-studio/open-mcp@latest"],
+  "env": {
+    "GATEWAY_URL": "http://115.190.91.253:80"
+  }
+}'
 ```
 
-**Or with npx:**
+### Option 2: Claude Desktop Config
+
+Edit `claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
     "open-mcp": {
       "command": "npx",
-      "args": ["-y", "@amplify-studio/open-mcp"]
+      "args": ["-y", "@amplify-studio/open-mcp@latest"]
     }
   }
 }
 ```
 
-### Option 2: From GitHub
-
-No installation needed - runs directly from GitHub:
-
-**Claude Desktop Config**:
+**With custom gateway:**
 ```json
 {
   "mcpServers": {
     "open-mcp": {
       "command": "npx",
-      "args": ["-y", "github:amplify-studio/open-mcp"]
+      "args": ["-y", "@amplify-studio/open-mcp@latest"],
+      "env": {
+        "GATEWAY_URL": "http://115.190.91.253:80"
+      }
     }
   }
 }
 ```
 
-### Option 3: Custom Gateway
+### Option 3: From GitHub
 
-If you have your own gateway instance:
+Alternative: install directly from GitHub (no npm):
 
 ```json
 {
   "mcpServers": {
     "open-mcp": {
       "command": "npx",
-      "args": ["-y", "github:amplify-studio/open-mcp"],
-      "env": {
-        "GATEWAY_URL": "http://your-gateway.com:80"
-      }
+      "args": ["-y", "github:amplify-studio/open-mcp"]
     }
   }
 }
@@ -180,6 +190,79 @@ npm link
 # Then use: open-mcp
 ```
 
+## Updating
+
+To update to the latest version:
+
+### Using Claude CLI
+
+```bash
+# Remove old version
+claude mcp remove open-mcp
+
+# Install latest version
+claude mcp add-json -s user open-mcp '{
+  "command": "npx",
+  "args": ["-y", "@amplify-studio/open-mcp@latest"]
+}'
+```
+
+### Clear npx Cache (Optional)
+
+If you encounter issues after updating:
+
+```bash
+# Clear npx cache
+npm cache clean --force
+
+# Then reinstall
+claude mcp remove open-mcp
+claude mcp add-json -s user open-mcp '{
+  "command": "npx",
+  "args": ["-y", "@amplify-studio/open-mcp@latest"]
+}'
+```
+
+### Check Current Version
+
+```bash
+# View your configuration
+cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+## Output Format
+
+Both tools return JSON strings for structured data parsing.
+
+### Web Search Output
+
+```json
+{
+  "query": "search term",
+  "results": [
+    {
+      "title": "Result Title",
+      "content": "Description or snippet",
+      "url": "https://example.com"
+    }
+  ],
+  "totalCount": 1,
+  "duration": "234ms"
+}
+```
+
+### URL Read Output
+
+```json
+{
+  "url": "https://example.com",
+  "content": "Page content in markdown/text format...",
+  "charCount": 1500,
+  "duration": "456ms",
+  "cached": false
+}
+```
+
 ## Configuration
 
 | Variable | Required | Default | Description |
@@ -198,11 +281,119 @@ The server connects to a Gateway API that provides:
 
 | API | Method | Endpoint | Description |
 |-----|--------|----------|-------------|
-| Search | GET | `/api/search/` | Web search |
+| Search | POST | `/api/firecrawl-search` | Web search via Firecrawl |
 | Read | GET | `/api/read/{url}` | Extract web content |
 | Health | GET | `/health` | Health check |
 | Status | GET | `/api/status` | Service status |
 
+## HTTP Transport Mode
+
+The server supports two transport modes: **STDIO** (default) and **HTTP**.
+
+### STDIO Mode (Default)
+
+Standard MCP transport for local development and Claude Desktop integration. The server communicates via stdin/stdout.
+
+### HTTP Mode
+
+HTTP transport enables remote server deployment and multi-client connections. Uses the **Streamable HTTP** protocol from MCP specification.
+
+#### Starting HTTP Server
+
+```bash
+# Basic
+MCP_HTTP_PORT=3333 npm start
+
+# With custom gateway
+GATEWAY_URL=http://115.190.91.253:80 MCP_HTTP_PORT=3333 npm start
+
+# Background mode
+MCP_HTTP_PORT=3333 npm start &
+```
+
+#### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/mcp` | POST | Send JSON-RPC requests |
+| `/mcp` | GET | Receive SSE notifications |
+| `/mcp` | DELETE | Close session |
+
+#### Verify Connection
+
+```bash
+# Health check
+curl http://localhost:3333/health
+
+# Expected response
+# {"status":"healthy","server":"ihor-sokoliuk/mcp-searxng","version":"0.8.2","transport":"http"}
+```
+
+#### Claude Code Integration
+
+```bash
+# Add HTTP server to Claude Code
+claude mcp add --transport http open-mcp http://localhost:3333/mcp
+
+# Verify
+claude mcp list
+```
+
+#### Example curl Commands
+
+```bash
+# 1. Initialize session
+curl -X POST http://localhost:3333/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-06-18",
+      "capabilities": {},
+      "clientInfo": {"name": "test-client", "version": "1.0"}
+    }
+  }'
+
+# 2. List tools (use returned session-id)
+curl -X POST http://localhost:3333/mcp \
+  -H "Content-Type: application/json" \
+  -H "mcp-session-id: <session-id>" \
+  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
+
+# 3. Call search tool
+curl -X POST http://localhost:3333/mcp \
+  -H "Content-Type: application/json" \
+  -H "mcp-session-id: <session-id>" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+      "name": "searxng_web_search",
+      "arguments": {"query": "test"}
+    }
+  }'
+```
+
+#### Security Considerations
+
+For production deployments:
+
+1. **DNS Rebinding Protection** - Enable `enableDnsRebindingProtection` in `http-server.ts`
+2. **Bind to localhost** - Use `127.0.0.1` instead of `0.0.0.0` for local development
+3. **Authentication** - Use API Gateway, reverse proxy, or implement auth headers
+4. **CORS** - Configure `ALLOWED_ORIGINS` environment variable
+
+```bash
+# Example: Production configuration
+MCP_HTTP_PORT=3333
+ALLOWED_ORIGINS=https://yourdomain.com
+```
+
 ## Development
 
 ```bash
@@ -222,6 +413,60 @@ npm run inspector
 npm run build
 ```
 
+## Docker Deployment
+
+The server can be deployed in HTTP mode using Docker for remote access.
+
+### Quick Start (HTTP Mode)
+
+```bash
+# Build the Docker image
+docker build -t open-mcp:latest .
+
+# Run HTTP server on port 3333
+docker run -d -p 3333:3333 \
+  -e MCP_HTTP_PORT=3333 \
+  -e GATEWAY_URL=http://115.190.91.253:80 \
+  --name open-mcp \
+  open-mcp:latest
+
+# Verify deployment
+curl http://localhost:3333/health
+```
+
+### Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `MCP_HTTP_PORT` | HTTP server port | 3333 |
+| `GATEWAY_URL` | Gateway API base URL | `http://115.190.91.253:80` |
+| `ALLOWED_ORIGINS` | CORS allowed origins | `*` |
+
+### Claude Code Integration
+
+```bash
+# Add HTTP server to Claude Code
+claude mcp add --transport http open-mcp http://your-server:3333/mcp
+```
+
+### Docker Compose (Optional)
+
+For production deployments, you can use Docker Compose to manage the service:
+
+```yaml
+services:
+  open-mcp:
+    image: open-mcp:latest
+    container_name: open-mcp
+    ports:
+      - "3333:3333"
+    environment:
+      - MCP_HTTP_PORT=3333
+      - GATEWAY_URL=http://115.190.91.253:80
+      - ALLOWED_ORIGINS=https://yourdomain.com
+    restart: unless-stopped
+```
+
 ## Contributing
 
 We're building an open-source community for AI agent infrastructure. Contributions welcome!

package/dist/http-server.js

@@ -5,19 +5,54 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { logMessage } from "./logging.js";
 import { packageVersion } from "./index.js";
+// Get allowed origins from environment variable
+const getAllowedOrigins = () => {
+    const allowedOrigins = process.env.ALLOWED_ORIGINS;
+    if (!allowedOrigins) {
+        return '*'; // Default to allowing all origins
+    }
+    return allowedOrigins.split(',').map(o => o.trim());
+};
 export async function createHttpServer(server) {
     const app = express();
     app.use(express.json());
     // Add CORS support for web clients
     app.use(cors({
-        origin: '*', // Configure appropriately for production
+        origin: getAllowedOrigins(),
         exposedHeaders: ['Mcp-Session-Id'],
-        allowedHeaders: ['Content-Type', 'mcp-session-id'],
+        allowedHeaders: ['Content-Type', 'mcp-session-id', 'Accept'],
+        credentials: true,
     }));
     // Map to store transports by session ID  
     const transports = {};
+    // Validate Accept header for MCP specification compliance
+    const validateAcceptHeader = (acceptHeader) => {
+        if (!acceptHeader) {
+            return false;
+        }
+        const header = acceptHeader.toLowerCase();
+        return header.includes('application/json') || header.includes('text/event-stream');
+    };
     // Handle POST requests for client-to-server communication
     app.post('/mcp', async (req, res) => {
+        // Validate Accept header for MCP spec compliance
+        const acceptHeader = req.headers['accept'];
+        if (!validateAcceptHeader(acceptHeader)) {
+            console.warn(`⚠️  POST request rejected - missing/invalid Accept header:`, {
+                clientIP: req.ip || req.connection.remoteAddress,
+                accept: acceptHeader || 'undefined',
+                userAgent: req.headers['user-agent'],
+            });
+            res.status(406).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Not Acceptable: Accept header must include application/json or text/event-stream',
+                },
+                id: null,
+            });
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         let transport;
         if (sessionId && transports[sessionId]) {

package/dist/index.js

@@ -84,7 +84,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (!isSearXNGWebSearchArgs(args)) {
                 throw new Error("Invalid arguments for web search");
             }
-            const result = await performWebSearch(server, args.query, args.pageno, args.time_range, args.language, args.safesearch);
+            const result = await performWebSearch(server, args.query, args.limit);
             return {
                 content: [
                     {

package/dist/search.d.ts

@@ -1,2 +1,2 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export declare function performWebSearch(server: Server, query: string, pageno?: number, time_range?: string, language?: string, safesearch?: string): Promise<string>;
+export declare function performWebSearch(server: Server, query: string, limit?: number): Promise<string>;

package/dist/search.js

@@ -1,18 +1,11 @@
 import { createProxyAgent } from "./proxy.js";
 import { logMessage } from "./logging.js";
-import { createConfigurationError, createNetworkError, createServerError, createJSONError, createDataError, createNoResultsMessage } from "./error-handler.js";
-export async function performWebSearch(server, query, pageno = 1, time_range, language = "all", safesearch) {
+import { createConfigurationError, createNetworkError, createServerError } from "./error-handler.js";
+export async function performWebSearch(server, query, limit = 10) {
     const startTime = Date.now();
-    // Build detailed log message with all parameters
-    const searchParams = [
-        `page ${pageno}`,
-        `lang: ${language}`,
-        time_range ? `time: ${time_range}` : null,
-        safesearch ? `safesearch: ${safesearch}` : null
-    ].filter(Boolean).join(", ");
-    logMessage(server, "info", `Starting web search: "${query}" (${searchParams})`);
+    logMessage(server, "info", `Starting web search: "${query}" (limit: ${limit})`);
     const gatewayUrl = process.env.GATEWAY_URL || "http://115.190.91.253:80";
-    // Validate that gatewayUrl is a valid URL
+    // Validate gateway URL
     let parsedUrl;
     try {
         parsedUrl = new URL(gatewayUrl);
@@ -20,52 +13,41 @@ export async function performWebSearch(server, query, pageno = 1, time_range, la
     catch (error) {
         throw createConfigurationError(`Invalid GATEWAY_URL format: ${gatewayUrl}. Use format: http://115.190.91.253:80`);
     }
-    const url = new URL('/api/search/', parsedUrl);
-    url.searchParams.set("q", query);
-    url.searchParams.set("format", "json");
-    url.searchParams.set("pageno", pageno.toString());
-    if (time_range !== undefined &&
-        ["day", "month", "year"].includes(time_range)) {
-        url.searchParams.set("time_range", time_range);
-    }
-    if (language && language !== "all") {
-        url.searchParams.set("language", language);
-    }
-    if (safesearch !== undefined && ["0", "1", "2"].includes(safesearch)) {
-        url.searchParams.set("safesearch", safesearch);
-    }
-    // Prepare request options with headers
+    const url = new URL('/api/firecrawl-search', parsedUrl);
+    // Prepare request body
+    const requestBody = {
+        query,
+        limit
+    };
+    // Prepare request options
     const requestOptions = {
-        method: "GET"
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(requestBody)
     };
-    // Add proxy dispatcher if proxy is configured
-    // Node.js fetch uses 'dispatcher' option for proxy, not 'agent'
+    // Add proxy dispatcher if configured
     const proxyAgent = createProxyAgent(url.toString());
     if (proxyAgent) {
         requestOptions.dispatcher = proxyAgent;
     }
-    // Add basic authentication if credentials are provided
+    // Add basic authentication if configured
     const username = process.env.AUTH_USERNAME;
     const password = process.env.AUTH_PASSWORD;
     if (username && password) {
         const base64Auth = Buffer.from(`${username}:${password}`).toString('base64');
-        requestOptions.headers = {
-            ...requestOptions.headers,
-            'Authorization': `Basic ${base64Auth}`
-        };
+        requestOptions.headers['Authorization'] = `Basic ${base64Auth}`;
     }
-    // Add User-Agent header if configured
+    // Add User-Agent if configured
     const userAgent = process.env.USER_AGENT;
     if (userAgent) {
-        requestOptions.headers = {
-            ...requestOptions.headers,
-            'User-Agent': userAgent
-        };
+        requestOptions.headers['User-Agent'] = userAgent;
     }
-    // Fetch with enhanced error handling
+    // Fetch with error handling
     let response;
     try {
-        logMessage(server, "info", `Making request to: ${url.toString()}`);
+        logMessage(server, "info", `Making POST request to: ${url.toString()}`);
         response = await fetch(url.toString(), requestOptions);
     }
     catch (error) {
@@ -95,7 +77,7 @@ export async function performWebSearch(server, query, pageno = 1, time_range, la
     // Parse JSON response
     let data;
     try {
-        data = (await response.json());
+        data = await response.json();
     }
     catch (error) {
         let responseText;
@@ -106,25 +88,39 @@ export async function performWebSearch(server, query, pageno = 1, time_range, la
             responseText = '[Could not read response text]';
         }
         const context = { url: url.toString() };
-        throw createJSONError(responseText, context);
+        throw new Error(`Failed to parse JSON response: ${responseText}`);
     }
-    if (!data.results) {
-        const context = { url: url.toString(), query };
-        throw createDataError(data, context);
+    // Handle Firecrawl API response format: {success: true, data: [...]}
+    let results = data.results || data.data || [];
+    // If wrapped in success object
+    if (data.success && data.data) {
+        results = data.data;
+    }
+    if (!Array.isArray(results)) {
+        throw new Error(`Invalid response format: results is not an array`);
     }
-    const results = data.results.map((result) => ({
-        title: result.title || "",
-        content: result.content || "",
-        url: result.url || "",
-        score: result.score || 0,
-    }));
     if (results.length === 0) {
         logMessage(server, "info", `No results found for query: "${query}"`);
-        return createNoResultsMessage(query);
+        return JSON.stringify({
+            query,
+            results: [],
+            totalCount: 0,
+            duration: `${Date.now() - startTime}ms`
+        }, null, 2);
     }
+    // Format results (API returns: url, title, description)
+    const formattedResults = results.map((result) => ({
+        title: result.title || "",
+        content: result.description || result.content || "",
+        url: result.url || result.link || ""
+    }));
     const duration = Date.now() - startTime;
-    logMessage(server, "info", `Search completed: "${query}" (${searchParams}) - ${results.length} results in ${duration}ms`);
-    return results
-        .map((r) => `Title: ${r.title}\nDescription: ${r.content}\nURL: ${r.url}\nRelevance Score: ${r.score.toFixed(3)}`)
-        .join("\n\n");
+    logMessage(server, "info", `Search completed: "${query}" - ${formattedResults.length} results in ${duration}ms`);
+    // Return as JSON string
+    return JSON.stringify({
+        query,
+        results: formattedResults,
+        totalCount: formattedResults.length,
+        duration: `${duration}ms`
+    }, null, 2);
 }

package/dist/types.d.ts

@@ -4,15 +4,11 @@ export interface SearXNGWeb {
         title: string;
         content: string;
         url: string;
-        score: number;
     }>;
 }
 export declare function isSearXNGWebSearchArgs(args: unknown): args is {
     query: string;
-    pageno?: number;
-    time_range?: string;
-    language?: string;
-    safesearch?: string;
+    limit?: number;
 };
 export declare const WEB_SEARCH_TOOL: Tool;
 export declare const READ_URL_TOOL: Tool;

package/dist/types.js

@@ -6,35 +6,22 @@ export function isSearXNGWebSearchArgs(args) {
 }
 export const WEB_SEARCH_TOOL = {
     name: "searxng_web_search",
-    description: "Performs a web search using the SearXNG API, ideal for general queries, news, articles, and online content. " +
-        "Use this for broad information gathering, recent events, or when you need diverse web sources.",
+    description: "Performs web search using the Gateway API Firecrawl search. " +
+        "Returns search results with title, content, URL, and relevance score. " +
+        "Use this for general queries, news, articles, and online content.",
     inputSchema: {
         type: "object",
         properties: {
             query: {
                 type: "string",
-                description: "The search query. This is the main input for the web search",
+                description: "The search query string",
             },
-            pageno: {
+            limit: {
                 type: "number",
-                description: "Search page number (starts at 1)",
-                default: 1,
-            },
-            time_range: {
-                type: "string",
-                description: "Time range of search (day, month, year)",
-                enum: ["day", "month", "year"],
-            },
-            language: {
-                type: "string",
-                description: "Language code for search results (e.g., 'en', 'fr', 'de'). Default is instance-dependent.",
-                default: "all",
-            },
-            safesearch: {
-                type: "string",
-                description: "Safe search filter level (0: None, 1: Moderate, 2: Strict)",
-                enum: ["0", "1", "2"],
-                default: "0",
+                description: "Maximum number of results to return (default: 10, max: 100)",
+                default: 10,
+                minimum: 1,
+                maximum: 100,
             },
         },
         required: ["query"],

package/dist/url-reader.js

@@ -185,10 +185,17 @@ export async function fetchAndConvertToMarkdown(server, url, timeoutMs = 10000,
         // Cache the markdown content from gateway
         urlCache.set(url, "", markdownContent);
         // Apply pagination options
-        const result = applyPaginationOptions(markdownContent, paginationOptions);
+        const content = applyPaginationOptions(markdownContent, paginationOptions);
         const duration = Date.now() - startTime;
-        logMessage(server, "info", `Successfully fetched and converted URL: ${url} (${result.length} chars in ${duration}ms)`);
-        return result;
+        logMessage(server, "info", `Successfully fetched and converted URL: ${url} (${content.length} chars in ${duration}ms)`);
+        // Return as JSON string
+        return JSON.stringify({
+            url,
+            content,
+            charCount: content.length,
+            duration: `${duration}ms`,
+            cached: !!cachedEntry
+        }, null, 2);
     }
     catch (error) {
         if (error.name === "AbortError") {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@amplify-studio/open-mcp",
-    "version": "0.8.1",
+    "version": "0.9.0",
     "description": "Open MCP server for web search and URL reading via Gateway API",
     "license": "MIT",
     "author": "Amplify Studio (https://github.com/amplify-studio)",