desearch-mcp-server 0.0.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# 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`.
+
+### npm 0.0.1 versus this release
+
+`0.0.1` exposed two tools and called desearch-js methods that 1.5.0 does not have (`AISearch`, `twitterSearch`). Those calls throw. `0.1.2` depends on desearch-js 1.5.0 and calls `aiSearch` and `xSearch`.
+
+`0.0.1` did not include `web-links-search` or the other tools below. npm users are not losing a source list they already had.
+
+### Tools
+
+| Tool | In 0.0.1 |
+| --- | --- |
+| `ai-search` | Present, under the broken `AISearch` call. Arguments now include date range, `result_type`, and domain filters. `tools` uses short ids (`web`, `twitter`, and the other sources this tool already exposed). Older labels such as `"Web Search"` are accepted and rewritten to the short id before the API call. Default is `["web", "twitter"]`. |
+| `x-search` | Present, under the broken `twitterSearch` call. Optional filters were added later (`user`, dates, language, verification, media, engagement). Sort stays Top. |
+| `web-search` | New. |
+| `web-links-search` | New. `tools` accepts only `web` and defaults to `["web"]`. |
+| `x-links-search` | New. |
+| `x-posts-by-urls`, `x-post-by-id`, `x-posts-by-user`, `x-post-retweeters`, `x-user-posts`, `x-user-replies`, `x-post-replies` | New. |
+| `extract`, `web-crawl` | New. Prefer `extract`. |
+| `x-trends` | New. |
+
+The same process can serve MCP Streamable HTTP (`--http` or `MCP_TRANSPORT=http`). Stdio is unchanged: it reads `DESEARCH_API_KEY`.
+
+### `web-links-search` sources
+
+Hosted `https://mcp.desearch.ai/mcp` already lists `web-links-search`. After this release, that tool's schema accepts only `web`. `"Web Search"` is rewritten to `web`. Callers that send `hackernews`, `reddit`, `wikipedia`, `youtube`, or `arxiv` fail input validation. The live `POST /desearch/ai/search/links/web` route rejects those ids with HTTP 422 (`supported tools are Web Search`). npm `0.0.1` never shipped this tool, so this is a break for hosted MCP clients, not for existing npm installs.
+
+### Link payloads
+
+When `web-links-search` or `ai-search` gets a body with no links (billing fields only, or an empty link list), the tool text includes `message: "no links in response"` and the billing fields. A non-empty link list is returned as the API sent it. The API still sometimes omits links; that fix is in desearch-public-api.
+
+### Docker
+
+The image command is `node build/index.js` (stdio). Streamable HTTP is `node build/index.js --http` or `MCP_TRANSPORT=http`.
+
+### Runtime
+
+Node.js `>=20.18.1`. Node 22 is supported. Node 18 is not. `desearch-js` loads `undici` at runtime with a range of `>=5`, which a lockfile-free install resolves to undici 8 (Node `>=22.19`, and it crashes on Node 20). This package depends on `undici@^7.29.1` so a clean install stays on undici 7.
+
+### Tool annotations
+
+`tools/list` sets MCP tool annotations on every tool:
+
+- `readOnlyHint: true` — the tool reads Desearch, the web, or X and does not write caller state
+- `destructiveHint: false` — it does not perform a destructive update
+- `openWorldHint: true` — results come from live external sources
+
+These are hints. A call still bills the Desearch API key. Repeating a call is not free.

package/README.md

@@ -2,19 +2,34 @@
 
 [![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 the Desearch AI for real-time AI X search and web search.
+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**: Performs real-time AI Twitter and web searches with relevant links and summary.
--   **X Search**: Real-time tweet search on X.
+-   **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).
+-   **Web Crawl** (`web-crawl`): Same arguments as `extract`, on the legacy `/web/crawl` route. The SDK marks `webCrawl` deprecated in favor of `extract`; this tool stays so that route remains reachable. Prefer `extract` for new integrations.
+-   **X Links Search** (`x-links-search`): AI search for X post links. Arguments: `prompt` (required), `count` (optional, 10–200).
+-   **X Posts By URLs** (`x-posts-by-urls`): Full posts for a list of URLs. Argument: `urls` (required).
+-   **X Post By ID** (`x-post-by-id`): One post by ID. Argument: `id` (required).
+-   **X Posts By User** (`x-posts-by-user`): Posts by a user. Arguments: `user` (required), `query` (optional), `count` (optional, 1–100).
+-   **X Post Retweeters** (`x-post-retweeters`): Users who retweeted a post. Arguments: `id` (required), `cursor` (optional).
+-   **X User Posts** (`x-user-posts`): A user's timeline. Arguments: `username` (required), `cursor` (optional).
+-   **X User Replies** (`x-user-replies`): Posts and replies by a user. Arguments: `user` (required), `count` (optional, 1–100), `query` (optional).
+-   **X Post Replies** (`x-post-replies`): Replies to a post. Arguments: `post_id` (required), `count` (optional, 1–100), `query` (optional).
+-   **X Trends** (`x-trends`): Trending topics for a location. Arguments: `woeid` (required), `count` (optional, 30–100).
+
+The full SDK method → endpoint → MCP tool map is in [docs/API_MCP_PARITY.md](docs/API_MCP_PARITY.md). Every public `desearch-js` 1.5 method is a tool. `latestTweets` was removed from the SDK (`GET /twitter/latest` in 1.0.1) and is not exposed.
 
 ## Prerequisites 📋
 
 -   An [Desearch API Key](https://console.desearch.ai/api-keys)
--   [Node.js](https://nodejs.org/) (v18 or higher)
+-   [Node.js](https://nodejs.org/) (v20.18.1 or higher; Node 22 is supported. Node 18 is not.)
 -   [Claude Desktop](https://claude.ai/download) installed
 -   [Cursor IDE](https://www.cursor.com/)
 
@@ -22,10 +37,126 @@ The Desearch MCP server includes the following tools:
 
 ### NPM Installation
 
+The package name is `desearch-mcp-server`. The first npm publish of this tree is `0.1.2` (the registry still has `0.0.1`). See [CHANGELOG.md](CHANGELOG.md) for the 0.0.1 → 0.1.2 migration. The stdio entry is the `desearch-mcp-server` bin (`build/index.js`), which requires `DESEARCH_API_KEY`.
+
 ```bash
 npm install -g desearch-mcp-server
 ```
 
+Or run it without a global install:
+
+```bash
+npx -y desearch-mcp-server
+```
+
+Cursor or Claude can start that bin directly:
+
+```json
+{
+    "mcpServers": {
+        "desearch": {
+            "command": "npx",
+            "args": ["-y", "desearch-mcp-server"],
+            "env": {
+                "DESEARCH_API_KEY": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+`command: "desearch-mcp-server"` (no `args`) is the same entry after the global install above.
+
+### Using Smithery
+
+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/desearch --client claude
+```
+
+Or for Cursor IDE:
+
+```bash
+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
@@ -105,6 +236,121 @@ For the changes to take effect:
 2. Start Claude Desktop again
 3. You can verify the server by checking status in Settings > Developer > desearch
 
+## Remote Streamable HTTP
+
+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. 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 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 /`, `GET /health`, and `GET /api/health` are unauthenticated health checks.
+
+## Hosted endpoint
+
+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:
+
+```json
+{
+    "mcpServers": {
+        "desearch": {
+            "url": "https://mcp.desearch.ai/mcp",
+            "headers": {
+                "x-api-key": "your-api-key"
+            }
+        }
+    }
+}
+```
+
+### Use with Claude (custom connector)
+
+Desearch is not in the Claude Connectors Directory yet. You can add the hosted server as a custom connector with your Desearch API key.
+
+Sources: [Custom remote MCP connectors](https://claude.com/docs/connectors/custom/remote-mcp) and [connector authentication](https://claude.com/docs/connectors/building/authentication). Request-header authentication is a beta feature in Claude.
+
+**Claude.ai / Claude Desktop (organization admin)**
+
+1. Open **Organization settings > Connectors**.
+2. Select **Add**, then **Custom**. If asked for the connector type, choose **Web**.
+3. Server URL: `https://mcp.desearch.ai/mcp`
+4. Sign-in option: **No sign-in**.
+5. Under **Request headers**, add `x-api-key` with your Desearch API key as the value.
+6. Select **Add**.
+
+The header value is stored once and shared by everyone in the organization who uses the connector.
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \
+  --header "x-api-key: YOUR_DESEARCH_API_KEY"
+```
+
+### Run locally
+
+```bash
+npm install
+npm run build
+npm run start:http
+```
+
+This listens on `0.0.0.0:3000` (`PORT` and `HOST` override that). `MCP_TRANSPORT=http` is the same as `--http`.
+
+```bash
+curl -sS http://127.0.0.1:3000/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'Authorization: Bearer your-api-key' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}'
+```
+
+Cursor (or any remote MCP client):
+
+```json
+{
+    "mcpServers": {
+        "desearch": {
+            "url": "http://127.0.0.1:3000/mcp",
+            "headers": {
+                "Authorization": "Bearer your-api-key"
+            }
+        }
+    }
+}
+```
+
+The image default is stdio MCP (`node build/index.js`). Registries such as Glama start the container and speak MCP on stdin/stdout, so the image does not pass `--http` unless you override it. Stdio requires `DESEARCH_API_KEY`. Smithery does not use this image command; `smithery.yaml` starts `node build/index.js` and injects `DESEARCH_API_KEY` itself.
+
+Streamable HTTP is an override. Replace the command with `--http`, or set `MCP_TRANSPORT=http` and keep the default command. The image still exposes port 3000 for that mode.
+
+```bash
+docker build -t desearch-mcp .
+# stdio (image default)
+docker run --rm -e DESEARCH_API_KEY=your-api-key -i desearch-mcp
+# Streamable HTTP
+docker run --rm -p 3000:3000 desearch-mcp node build/index.js --http
+# same HTTP mode via env, without replacing the command
+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 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:
+
+`https://<project>.vercel.app/mcp`
+
+`https://mcp.desearch.ai/mcp` is the public hostname. This repo does not create DNS records. Clients send `x-api-key`, or `Authorization: Bearer <key>`.
+
+The same `node build/index.js --http` process is the fallback if you would rather run a long-lived Node host instead of Vercel. The Docker image defaults to stdio; pass `--http` or set `MCP_TRANSPORT=http` to serve Streamable HTTP from it.
+
 ## Troubleshooting 🔧
 
 ### Common Issues
@@ -119,6 +365,7 @@ For the changes to take effect:
     - Confirm your `DESEARCH_API_KEY` is valid
     - Check the `DESEARCH_API_KEY` is correctly set in the Cursor or Claude Desktop config
     - Verify that there are no spaces around the API key
+    - For the remote HTTP server, send `Authorization: Bearer <key>` or `x-api-key`. A hosted `DESEARCH_API_KEY` environment variable is not used for those requests.
 
 3. **Connection Issues**
 

package/build/http.d.ts

@@ -0,0 +1,32 @@
+export interface HttpListenOptions {
+    port?: number;
+    host?: string;
+}
+export interface RunningHttpServer {
+    port: number;
+    host: string;
+    close: () => Promise<void>;
+}
+/**
+ * Desearch API key from the remote client.
+ * Prefer `Authorization: Bearer <key>` (what MCP clients send). `x-api-key` is
+ * accepted as well. A bare `Authorization: <key>` value is accepted so the same
+ * string used as `DESEARCH_API_KEY` for stdio can be sent without a scheme.
+ * Query strings are ignored so keys do not land in access logs.
+ */
+/**
+ * Copy a request onto another path. Used by the Vercel functions, which see
+ * the rewritten URL (`/api/mcp`) rather than the public path (`/mcp`).
+ */
+export declare function requestWithPathname(request: Request, pathname: string): Request;
+export declare function extractDesearchApiKey(request: Request): string | undefined;
+/**
+ * Stateless Streamable HTTP handler.
+ * Each POST builds a fresh MCP server tied to that request's API key.
+ * JSON responses (not a long-lived SSE session) so the same handler runs
+ * in a local Node process and in a Vercel function.
+ * GET and DELETE return 405: this server does not push messages or store sessions.
+ */
+export declare function handleMcpHttpRequest(request: Request): Promise<Response>;
+export declare function startHttpServer(options?: HttpListenOptions): Promise<RunningHttpServer>;
+//# sourceMappingURL=http.d.ts.map

package/build/http.d.ts.map

@@ -0,0 +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;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"}