desearch-mcp-server 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.3
+
+Tool copy no longer states unsourced speed or latency.
+
+- `ai-search` description is `AI search and analysis on web using Desearch AI`.
+- `x-search` description is `Search X (Twitter) using Desearch AI. Optional filters narrow by user, date, language, verification, media, and engagement. Sort stays Top.`
+- `ai-search` `model` is `Model to use for the search: NOVA (default) or ORBIT.`
+
+Removed from those strings: `Real-time`, `real-time`, and `Nova is 10s model, Orbit is 30s model`. The Vercel section of the README no longer says Orbit searches run about 30 seconds. The 60-second figure there is the `vercel.json` function duration.
+
 ## 0.1.2
 
 Migration from the published npm package `desearch-mcp-server@0.0.1`.

package/README.md

@@ -2,14 +2,14 @@
 
 [![npm version](https://badge.fury.io/js/desearch-mcp-server.svg)](https://www.npmjs.com/package/desearch-mcp-server)
 
-A Model Context Protocol (MCP) server lets clients like Claude or Cursor use Desearch for real-time AI search, X search, web search, page extraction, and X trends.
+AI search, X search and web search for AI agents, plus page extraction and X data tools. Bring your own Desearch API key.
 
 ## Tools
 
 The Desearch MCP server includes the following tools:
 
--   **AI Search** (`ai-search`): Performs real-time AI Twitter and web searches with relevant links and summary. `tools` uses short source ids (`web`, `twitter`, `arxiv`, `wikipedia`, `youtube`, `hackernews`, `reddit`). Older labels such as `Web Search` are still accepted and sent to the API as the short id. Default is `["web", "twitter"]`.
--   **X Search** (`x-search`): Real-time tweet search on X. Arguments: `query` (required), `count` (optional, default 20). Sort stays Top. Optional filters: `user`, `start_date`, `end_date` (YYYY-MM-DD), `lang`, `verified`, `blue_verified`, `is_quote`, `is_video`, `is_image`, `min_retweets`, `min_replies`, `min_likes`.
+-   **AI Search** (`ai-search`): Performs AI Twitter and web searches with relevant links and summary. `tools` uses short source ids (`web`, `twitter`, `arxiv`, `wikipedia`, `youtube`, `hackernews`, `reddit`). Older labels such as `Web Search` are still accepted and sent to the API as the short id. Default is `["web", "twitter"]`.
+-   **X Search** (`x-search`): Tweet search on X. Arguments: `query` (required), `count` (optional, default 20). Sort stays Top. Optional filters: `user`, `start_date`, `end_date` (YYYY-MM-DD), `lang`, `verified`, `blue_verified`, `is_quote`, `is_video`, `is_image`, `min_retweets`, `min_replies`, `min_likes`.
 -   **Web Search** (`web-search`): SERP-style web search. Arguments: `query` (required), `start` (optional pagination offset).
 -   **Web Links Search** (`web-links-search`): Web link search. Arguments: `prompt` (required), `tools` (optional, only `web`, default `["web"]`; `Web Search` is accepted and rewritten to `web`), `count` (optional, 10–200). The links/web API rejects other sources, so they are not in the enum.
 -   **Extract** (`extract`): Read a public URL as text or HTML. Preferred over crawl. Arguments: `url` (required), `format` (optional, `html` or `text`), `js` (optional), `wait` (optional milliseconds).
@@ -69,18 +69,94 @@ Cursor or Claude can start that bin directly:
 
 ### Using Smithery
 
-To install the Desearch MCP server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@Desearch-ai/desearch):
+To install the Desearch MCP server for Claude Desktop automatically via [Smithery](https://smithery.ai/servers/desearch/desearch):
 
 ```bash
-npx -y @smithery/cli install @Desearch-ai/desearch --client claude
+npx -y @smithery/cli install desearch/desearch --client claude
 ```
 
 Or for Cursor IDE:
 
 ```bash
-npx -y @smithery/cli install @Desearch-ai/desearch --client cursor
+npx -y @smithery/cli install desearch/desearch --client cursor
 ```
 
+### Windsurf
+
+Windsurf's Cascade agent reads MCP servers from `mcp_config.json` under the `mcpServers` key. Open it from the Cascade panel: click the `...` (Actions) menu, then `Open MCP config file`. Windsurf builds use `~/.codeium/windsurf/mcp_config.json` (on Windows, `%USERPROFILE%\.codeium\windsurf\mcp_config.json`). Newer builds may open `~/.config/devin/mcp_config.json` instead (Windows: `%APPDATA%\devin\mcp_config.json`); edit whichever file that action opens.
+
+Hosted server (no local install). Remote servers use `serverUrl` with `headers`:
+
+```json
+{
+    "mcpServers": {
+        "desearch": {
+            "serverUrl": "https://mcp.desearch.ai/mcp",
+            "headers": {
+                "x-api-key": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+To keep the key out of the file, Windsurf can interpolate an environment variable: `"x-api-key": "${env:DESEARCH_API_KEY}"`.
+
+Local stdio alternative:
+
+```json
+{
+    "mcpServers": {
+        "desearch": {
+            "command": "npx",
+            "args": ["-y", "desearch-mcp-server"],
+            "env": {
+                "DESEARCH_API_KEY": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+Save the file, then refresh the MCP servers list in Cascade.
+
+### Zed
+
+Zed calls MCP servers context servers. Open your settings file with the `zed: open settings file` action (or use Settings → AI → MCP Servers → `Add Server`) and add a `context_servers` entry.
+
+Hosted server:
+
+```json
+{
+    "context_servers": {
+        "desearch": {
+            "url": "https://mcp.desearch.ai/mcp",
+            "headers": {
+                "x-api-key": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+Local stdio alternative:
+
+```json
+{
+    "context_servers": {
+        "desearch": {
+            "command": "npx",
+            "args": ["-y", "desearch-mcp-server"],
+            "env": {
+                "DESEARCH_API_KEY": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+The server is ready when the dot next to `desearch` in Settings → AI → MCP Servers turns green ("Server is active").
+
 ## Configuration ⚙️
 
 ### 1. Configure Cursor IDE to run the Desearch MCP server
@@ -164,18 +240,18 @@ For the changes to take effect:
 
 The same server can run over MCP Streamable HTTP for a remote client. Local stdio (`desearch-mcp-server`, Smithery) is unchanged and still reads `DESEARCH_API_KEY` from the environment.
 
-Remote requests do not use that environment variable. Each request must carry the caller's own Desearch API key, the same key from [console.desearch.ai/api-keys](https://console.desearch.ai/api-keys):
+Remote requests do not use that environment variable. Discovery does not need a key: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list` return 200 so a marketplace scanner can read the tool list. `tools/call` and every other method still require the caller's own Desearch API key, the same key from [console.desearch.ai/api-keys](https://console.desearch.ai/api-keys):
 
 - `Authorization: Bearer <DESEARCH_API_KEY>` (preferred)
 - `x-api-key: <DESEARCH_API_KEY>`
 
-A bare `Authorization: <DESEARCH_API_KEY>` value is also accepted. The key is not read from the query string. There is no shared server secret: the hosted process forwards the per-request key to the Desearch API.
+A bare `Authorization: <DESEARCH_API_KEY>` value is also accepted. The key is not read from the query string. There is no shared server secret and no `WWW-Authenticate` challenge: the hosted process forwards the per-request key to the Desearch API only when a call needs it.
 
-The MCP endpoint is `POST /mcp`. Responses are JSON (stateless Streamable HTTP). `GET` and `DELETE` on `/mcp` return `405` because the server does not keep a session or push server-to-client messages. `GET /` and `GET /health` are unauthenticated health checks.
+The MCP endpoint is `POST /mcp`. Responses are JSON (stateless Streamable HTTP). `GET` and `DELETE` on `/mcp` return `405` because the server does not keep a session or push server-to-client messages. `GET /`, `GET /health`, and `GET /api/health` are unauthenticated health checks.
 
 ## Hosted endpoint
 
-The public Streamable HTTP endpoint is `https://mcp.desearch.ai/mcp`. Send your Desearch API key on each request in the `x-api-key` header. `Authorization: Bearer <key>` is also accepted. Use the key from [console.desearch.ai/api-keys](https://console.desearch.ai/api-keys). The server does not read a key from the query string. Remote requests do not use a process-level `DESEARCH_API_KEY`.
+The public Streamable HTTP endpoint is `https://mcp.desearch.ai/mcp`. Listing the tools does not need a key. Send your Desearch API key on each `tools/call` in the `x-api-key` header. `Authorization: Bearer <key>` is also accepted. Use the key from [console.desearch.ai/api-keys](https://console.desearch.ai/api-keys). The server does not read a key from the query string. Remote requests do not use a process-level `DESEARCH_API_KEY`.
 
 Cursor, or any remote MCP client:
 
@@ -265,7 +341,7 @@ docker run --rm -e MCP_TRANSPORT=http -p 3000:3000 desearch-mcp
 
 ### Deploy on Vercel
 
-Vercel fits this server because the handler is stateless and answers each JSON-RPC call in one response. `vercel.json` builds the project, serves `POST /mcp`, and allows tool calls up to 60 seconds (Orbit searches run about 30 seconds). Hobby plans cap function duration lower than that, so AI Search tool calls need a plan that allows at least 60 seconds. `initialize` and `tools/list` are short either way.
+Vercel fits this server because the handler is stateless and answers each JSON-RPC call in one response. `vercel.json` builds the project, serves `POST /mcp`, and sets the function duration to 60 seconds. Hobby plans cap function duration lower than that, so AI Search tool calls need a plan that allows at least 60 seconds. `initialize` and `tools/list` are short either way.
 
 No server-side Desearch API key is required in the Vercel project. After deploy, the endpoint is:
 

package/build/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../http.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa/E;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkB1E;AAoED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyD9E;AAoDD,wBAAgB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiD3F"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../http.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa/E;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkB1E;AAkID;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiE9E;AAuDD,wBAAgB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiD3F"}

package/build/http.js

@@ -68,7 +68,10 @@ function isMcpPath(pathname) {
     return pathname === "/mcp" || pathname === "/api/mcp";
 }
 function isHealthPath(pathname) {
-    return pathname === "/" || pathname === "/health";
+    // `/api/health` is the Vercel function path. The public rewrite of `/health`
+    // delivers that pathname when the function wrapper does not remap it, and
+    // `isMcpPath` already accepts both `/mcp` and `/api/mcp` for the same reason.
+    return pathname === "/" || pathname === "/health" || pathname === "/api/health";
 }
 function withCors(response) {
     const headers = new Headers(response.headers);
@@ -96,7 +99,7 @@ function healthResponse() {
         version: SERVER_VERSION,
         transport: "streamable-http",
         endpoint: "/mcp",
-        auth: "Authorization: Bearer <DESEARCH_API_KEY> or x-api-key: <DESEARCH_API_KEY>",
+        auth: "initialize and tools/list are public. tools/call requires Authorization: Bearer <DESEARCH_API_KEY> or x-api-key.",
     }), {
         status: 200,
         headers: { "Content-Type": "application/json" },
@@ -107,6 +110,62 @@ function unauthorized() {
     // WWW-Authenticate discovery hint makes some MCP clients start an OAuth flow.
     return jsonRpcError(401, -32001, "Unauthorized. Send your Desearch API key in the Authorization: Bearer <key> header or the x-api-key header.");
 }
+/**
+ * Methods a marketplace scanner can call with no Desearch API key.
+ * Anything else, including tools/call, stays on the 401 gate so a missing
+ * key never reaches the Desearch API.
+ */
+const KEYLESS_METHODS = new Set([
+    "initialize",
+    "notifications/initialized",
+    "ping",
+    "tools/list",
+    "prompts/list",
+    "resources/list",
+    "resources/templates/list",
+]);
+function isKeylessDiscovery(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    const messages = Array.isArray(parsed) ? parsed : [parsed];
+    return (messages.length > 0 &&
+        messages.every((message) => {
+            if (typeof message !== "object" || message === null) {
+                return false;
+            }
+            const method = message.method;
+            return typeof method === "string" && KEYLESS_METHODS.has(method);
+        }));
+}
+function copyRequestHeaders(headers) {
+    const copied = new Headers();
+    headers.forEach((value, key) => {
+        if (key.toLowerCase() === "content-length" || key.toLowerCase() === "host") {
+            return;
+        }
+        try {
+            copied.append(key, value);
+        }
+        catch {
+            // The Fetch constructor rejects forbidden request headers such as host.
+        }
+    });
+    return copied;
+}
+function requestWithJsonBody(request, body) {
+    const init = { method: "POST", headers: request.headers, body };
+    try {
+        return new Request(request.url, init);
+    }
+    catch {
+        return new Request(request.url, { ...init, headers: copyRequestHeaders(request.headers) });
+    }
+}
 /**
  * Stateless Streamable HTTP handler.
  * Each POST builds a fresh MCP server tied to that request's API key.
@@ -131,16 +190,24 @@ export async function handleMcpHttpRequest(request) {
             headers: { "Content-Type": "application/json" },
         }));
     }
-    const apiKey = extractDesearchApiKey(request);
-    if (!apiKey) {
-        return withCors(unauthorized());
-    }
     if (request.method === "GET" || request.method === "DELETE") {
+        if (!extractDesearchApiKey(request)) {
+            return withCors(unauthorized());
+        }
         return withCors(jsonRpcError(405, -32000, "Method not allowed. This server is stateless; use POST.", { Allow: "POST" }));
     }
     if (request.method !== "POST") {
         return withCors(jsonRpcError(405, -32000, "Method not allowed.", { Allow: "POST" }));
     }
+    let apiKey = extractDesearchApiKey(request);
+    if (!apiKey) {
+        const raw = await request.text();
+        if (!isKeylessDiscovery(raw)) {
+            return withCors(unauthorized());
+        }
+        request = requestWithJsonBody(request, raw);
+        apiKey = "";
+    }
     const server = createDesearchMcpServer(apiKey);
     const transport = new WebStandardStreamableHTTPServerTransport({
         enableJsonResponse: true,
@@ -168,7 +235,10 @@ function readRawBody(req) {
         req.on("data", (chunk) => {
             chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
         });
-        req.on("end", () => resolve(Buffer.concat(chunks)));
+        // TS 5.7+ DOM BodyInit accepts Uint8Array<ArrayBuffer> and rejects
+        // Uint8Array<ArrayBufferLike> (Node Buffer, whose buffer may be a
+        // SharedArrayBuffer). Copy into a plain ArrayBuffer.
+        req.on("end", () => resolve(new Uint8Array(Buffer.concat(chunks))));
         req.on("error", reject);
     });
 }

package/build/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare const SERVER_NAME = "Desearch";
-export declare const SERVER_VERSION = "0.1.2";
+export declare const SERVER_VERSION = "0.1.3";
 interface XSearchPayload {
     query: string;
     sort?: "Top" | "Latest";

package/build/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"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"}

package/build/server.js

@@ -1,9 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import DesearchImport from "desearch-js";
 import { z } from "zod";
 import { AI_SEARCH_TOOLS, WEB_LINK_TOOLS, toolIdSchema } from "./tool-sources.js";
 export const SERVER_NAME = "Desearch";
-export const SERVER_VERSION = "0.1.2";
+export const SERVER_VERSION = "0.1.3";
 // desearch-js 1.5 publishes a default class. Node16 resolution types that package
 // as a module namespace, so the constructor is applied through a cast.
 const Desearch = DesearchImport;
@@ -135,11 +136,22 @@ function fail(label, error) {
         isError: true,
     };
 }
-function registerTool(server, name, description, inputSchema, handler) {
+function registerTool(server, apiKey, name, title, description, inputSchema, handler) {
     // SDK 1.30's tool generics blow the TypeScript instantiation limit on these
     // schemas. Runtime registration is the same registerTool call.
     const register = server.registerTool.bind(server);
-    register(name, { description, inputSchema, annotations: READ_ONLY_OPEN_WORLD }, handler);
+    const guarded = async (args) => {
+        if (!apiKey) {
+            return fail("Desearch", new Error("Desearch API key required. Send it in the Authorization: Bearer <key> header or the x-api-key header."));
+        }
+        return handler(args);
+    };
+    register(name, {
+        title,
+        description,
+        inputSchema,
+        annotations: { ...READ_ONLY_OPEN_WORLD, title },
+    }, guarded);
 }
 /**
  * One MCP server bound to a single Desearch API key.
@@ -154,7 +166,7 @@ export function createDesearchMcpServer(apiKey, client) {
         name: SERVER_NAME,
         version: SERVER_VERSION,
     });
-    registerTool(server, "ai-search", "Real-time AI search and analysis on web using Desearch AI", {
+    registerTool(server, apiKey, "ai-search", "AI Search", "AI search and analysis on web using Desearch AI", {
         prompt: z.string().describe("Question, example: 'What is the latest news on AI?'"),
         tools: z
             .array(toolIdSchema(AI_SEARCH_TOOLS))
@@ -197,7 +209,7 @@ export function createDesearchMcpServer(apiKey, client) {
         model: z
             .enum(["NOVA", "ORBIT"])
             .default("NOVA")
-            .describe("Model to use for the search, example: 'NOVA', Nova is 10s model, Orbit is 30s model"),
+            .describe("Model to use for the search: NOVA (default) or ORBIT."),
     }, async ({ prompt, tools, date_filter, start_date, end_date, result_type, include_domains, exclude_domains, model }) => {
         try {
             const payload = {
@@ -218,7 +230,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("AI Search error", error);
         }
     });
-    registerTool(server, "x-search", "Search the X (Twitter) using Desearch AI - performs real-time tweet search on X. Optional filters narrow by user, date, language, verification, media, and engagement. Sort stays Top.", {
+    registerTool(server, apiKey, "x-search", "X Search", "Search X (Twitter) using Desearch AI. Optional filters narrow by user, date, language, verification, media, and engagement. Sort stays Top.", {
         query: z
             .string()
             .describe("Twitter advanced search query, example: 'from:elonmusk since:2023-01-01 min_replies:10'"),
@@ -271,7 +283,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Search error", error);
         }
     });
-    registerTool(server, "web-search", "SERP-style web search using Desearch. Returns ranked titles, links, and snippets.", {
+    registerTool(server, apiKey, "web-search", "Web Search", "SERP-style web search using Desearch. Returns ranked titles, links, and snippets.", {
         query: z.string().describe("Search query, example: 'latest news on AI'"),
         start: z
             .number()
@@ -287,7 +299,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("Web Search error", error);
         }
     });
-    registerTool(server, "web-links-search", "Search the web for links using Desearch. Only the web source is accepted.", {
+    registerTool(server, apiKey, "web-links-search", "Web Links Search", "Search the web for links using Desearch. Only the web source is accepted.", {
         prompt: z
             .string()
             .describe("Search query prompt, example: 'open source browser automation tools'"),
@@ -315,7 +327,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("Web Links Search error", error);
         }
     });
-    registerTool(server, "x-links-search", "AI search for X (Twitter) post links using Desearch. Returns links from posts that match the prompt.", {
+    registerTool(server, apiKey, "x-links-search", "X Links Search", "AI search for X (Twitter) post links using Desearch. Returns links from posts that match the prompt.", {
         prompt: z.string().describe("Search query prompt, example: 'Bittensor subnet updates'"),
         count: optionalLinksCount,
     }, async ({ prompt, count }) => {
@@ -326,7 +338,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Links Search error", error);
         }
     });
-    registerTool(server, "x-posts-by-urls", "Fetch full X (Twitter) posts for a list of post URLs.", {
+    registerTool(server, apiKey, "x-posts-by-urls", "Get X Posts by URLs", "Fetch full X (Twitter) posts for a list of post URLs.", {
         urls: z
             .array(z.string())
             .min(1)
@@ -339,7 +351,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Posts By URLs error", error);
         }
     });
-    registerTool(server, "x-post-by-id", "Fetch a single X (Twitter) post by its ID.", {
+    registerTool(server, apiKey, "x-post-by-id", "Get X Post by ID", "Fetch a single X (Twitter) post by its ID.", {
         id: z.string().describe("The unique ID of the post, example: '1234567890'"),
     }, async ({ id }) => {
         try {
@@ -349,7 +361,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Post By ID error", error);
         }
     });
-    registerTool(server, "x-posts-by-user", "Search X (Twitter) posts by a specific user, with an optional keyword query.", {
+    registerTool(server, apiKey, "x-posts-by-user", "Search X Posts by User", "Search X (Twitter) posts by a specific user, with an optional keyword query.", {
         user: z.string().describe("User to search for, example: 'elonmusk'"),
         query: z.string().optional().describe("Advanced search query to filter this user's posts."),
         count: optionalPostCount,
@@ -361,7 +373,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Posts By User error", error);
         }
     });
-    registerTool(server, "x-post-retweeters", "List users who retweeted an X (Twitter) post. Pass cursor to page through more users.", {
+    registerTool(server, apiKey, "x-post-retweeters", "List X Post Retweeters", "List users who retweeted an X (Twitter) post. Pass cursor to page through more users.", {
         id: z.string().describe("The ID of the post to get retweeters for."),
         cursor: z.string().optional().describe("Cursor for pagination from a previous response."),
     }, async ({ id, cursor }) => {
@@ -372,7 +384,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Post Retweeters error", error);
         }
     });
-    registerTool(server, "x-user-posts", "Retrieve a user's X (Twitter) timeline posts by username. Pass cursor to page through more posts.", {
+    registerTool(server, apiKey, "x-user-posts", "Get X User Timeline", "Retrieve a user's X (Twitter) timeline posts by username. Pass cursor to page through more posts.", {
         username: z.string().describe("Username to fetch posts for, example: 'elonmusk'"),
         cursor: z.string().optional().describe("Cursor for pagination from a previous response."),
     }, async ({ username, cursor }) => {
@@ -383,7 +395,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X User Posts error", error);
         }
     });
-    registerTool(server, "x-user-replies", "Fetch posts and replies by an X (Twitter) user, with an optional keyword query.", {
+    registerTool(server, apiKey, "x-user-replies", "Get X User Replies", "Fetch posts and replies by an X (Twitter) user, with an optional keyword query.", {
         user: z.string().describe("Username of the user to search for, example: 'elonmusk'"),
         count: optionalPostCount,
         query: z.string().optional().describe("Advanced search query to filter this user's posts and replies."),
@@ -395,7 +407,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X User Replies error", error);
         }
     });
-    registerTool(server, "x-post-replies", "Fetch replies to an X (Twitter) post, with an optional keyword query.", {
+    registerTool(server, apiKey, "x-post-replies", "Get X Post Replies", "Fetch replies to an X (Twitter) post, with an optional keyword query.", {
         post_id: z.string().describe("The ID of the post to fetch replies for."),
         count: optionalPostCount,
         query: z.string().optional().describe("Advanced search query to filter replies."),
@@ -407,7 +419,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Post Replies error", error);
         }
     });
-    registerTool(server, "extract", "Extract a public URL and return its content as plain text or HTML using Desearch. Preferred over web-crawl for new integrations.", pageContentFields(), async ({ url, format, js, wait }) => {
+    registerTool(server, apiKey, "extract", "Extract Page Content", "Extract a public URL and return its content as plain text or HTML using Desearch. Preferred over web-crawl for new integrations.", pageContentFields(), async ({ url, format, js, wait }) => {
         try {
             return ok(await desearch.extract({ url, format, js, wait }));
         }
@@ -415,7 +427,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("Extract error", error);
         }
     });
-    registerTool(server, "web-crawl", "Crawl a public URL and return its content as plain text or HTML on the legacy Desearch /web/crawl route. The SDK marks webCrawl deprecated in favor of extract; this tool stays for parity with that route. Prefer extract for new integrations.", pageContentFields(), async ({ url, format, js, wait }) => {
+    registerTool(server, apiKey, "web-crawl", "Crawl Web Page (Legacy)", "Crawl a public URL and return its content as plain text or HTML on the legacy Desearch /web/crawl route. The SDK marks webCrawl deprecated in favor of extract; this tool stays for parity with that route. Prefer extract for new integrations.", pageContentFields(), async ({ url, format, js, wait }) => {
         try {
             return ok(await desearch.webCrawl({ url, format, js, wait }));
         }
@@ -423,7 +435,7 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("Web Crawl error", error);
         }
     });
-    registerTool(server, "x-trends", "Retrieve trending topics on X (Twitter) for a location by its WOEID using Desearch.", {
+    registerTool(server, apiKey, "x-trends", "Get X Trends", "Retrieve trending topics on X (Twitter) for a location by its WOEID using Desearch.", {
         woeid: z
             .number()
             .int()
@@ -443,5 +455,17 @@ export function createDesearchMcpServer(apiKey, client) {
             return fail("X Trends error", error);
         }
     });
+    // Scanners ask for these lists during discovery. There is nothing to return,
+    // but an empty list is a successful response. Method-not-found looks like a
+    // broken server to some directory crawlers.
+    server.server.registerCapabilities({
+        prompts: {},
+        resources: {},
+    });
+    server.server.setRequestHandler(ListPromptsRequestSchema, () => ({ prompts: [] }));
+    server.server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
+    server.server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({
+        resourceTemplates: [],
+    }));
     return server;
 }

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "desearch-mcp-server",
-    "version": "0.1.2",
+    "version": "0.1.3",
     "mcpName": "io.github.Desearch-ai/mcp-desearch",
-    "description": "A Model Context Protocol server with Desearch for real-time AI search, X search and web search.",
+    "description": "AI search, X search and web search for AI agents, plus page extraction and X data tools. Bring your own Desearch API key.",
     "license": "MIT",
     "homepage": "https://www.desearch.ai/docs/guide/sdk/mcp",
     "type": "module",