desearch-mcp-server 0.0.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 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.
+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.
 
 ## 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 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`.
+-   **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,50 @@ 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/server/@Desearch-ai/desearch):
+
+```bash
+npx -y @smithery/cli install @Desearch-ai/desearch --client claude
+```
+
+Or for Cursor IDE:
+
+```bash
+npx -y @smithery/cli install @Desearch-ai/desearch --client cursor
+```
+
 ## Configuration ⚙️
 
 ### 1. Configure Cursor IDE to run the Desearch MCP server
@@ -105,6 +160,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. 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):
+
+- `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.
+
+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.
+
+## 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`.
+
+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 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.
+
+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 +289,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;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"}

package/build/http.js

@@ -0,0 +1,254 @@
+import { createServer } from "node:http";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createDesearchMcpServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Accept, Authorization, x-api-key, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID",
+    "Access-Control-Expose-Headers": "Mcp-Session-Id",
+    "Access-Control-Max-Age": "86400",
+};
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "content-length",
+]);
+/**
+ * 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 function requestWithPathname(request, pathname) {
+    const url = new URL(request.url);
+    url.pathname = pathname;
+    const method = request.method;
+    const init = {
+        method,
+        headers: request.headers,
+    };
+    if (method !== "GET" && method !== "HEAD") {
+        init.body = request.body;
+        init.duplex = "half";
+    }
+    return new Request(url, init);
+}
+export function extractDesearchApiKey(request) {
+    const authorization = request.headers.get("authorization")?.trim();
+    if (authorization) {
+        const bearer = /^Bearer\s+(\S+)$/i.exec(authorization);
+        if (bearer?.[1]) {
+            return bearer[1];
+        }
+        if (!/^Bearer\b/i.test(authorization) && !/\s/.test(authorization)) {
+            return authorization;
+        }
+    }
+    const headerKey = request.headers.get("x-api-key")?.trim();
+    if (headerKey) {
+        return headerKey;
+    }
+    return undefined;
+}
+function normalizePath(pathname) {
+    if (pathname.length > 1 && pathname.endsWith("/")) {
+        return pathname.slice(0, -1);
+    }
+    return pathname;
+}
+function isMcpPath(pathname) {
+    return pathname === "/mcp" || pathname === "/api/mcp";
+}
+function isHealthPath(pathname) {
+    return pathname === "/" || pathname === "/health";
+}
+function withCors(response) {
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(CORS_HEADERS)) {
+        headers.set(key, value);
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+function jsonRpcError(status, code, message, extra) {
+    const headers = new Headers({ "Content-Type": "application/json", ...extra });
+    return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: null,
+    }), { status, headers });
+}
+function healthResponse() {
+    return new Response(JSON.stringify({
+        ok: true,
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        transport: "streamable-http",
+        endpoint: "/mcp",
+        auth: "Authorization: Bearer <DESEARCH_API_KEY> or x-api-key: <DESEARCH_API_KEY>",
+    }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function unauthorized() {
+    // No OAuth challenge. Desearch auth is a per-user API key, and a
+    // 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.");
+}
+/**
+ * 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 async function handleMcpHttpRequest(request) {
+    if (request.method === "OPTIONS") {
+        return withCors(new Response(null, { status: 204 }));
+    }
+    const pathname = normalizePath(new URL(request.url).pathname);
+    if (isHealthPath(pathname)) {
+        if (request.method === "GET") {
+            return withCors(healthResponse());
+        }
+        return withCors(jsonRpcError(405, -32000, "Method not allowed.", { Allow: "GET" }));
+    }
+    if (!isMcpPath(pathname)) {
+        return withCors(new Response(JSON.stringify({ error: "Not found" }), {
+            status: 404,
+            headers: { "Content-Type": "application/json" },
+        }));
+    }
+    const apiKey = extractDesearchApiKey(request);
+    if (!apiKey) {
+        return withCors(unauthorized());
+    }
+    if (request.method === "GET" || request.method === "DELETE") {
+        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" }));
+    }
+    const server = createDesearchMcpServer(apiKey);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        enableJsonResponse: true,
+    });
+    transport.onerror = (error) => {
+        console.error(`MCP HTTP error: ${error.message}`);
+    };
+    try {
+        await server.connect(transport);
+        const response = await transport.handleRequest(request);
+        return withCors(response);
+    }
+    catch (error) {
+        console.error(`MCP HTTP handler error: ${error instanceof Error ? error.message : String(error)}`);
+        return withCors(jsonRpcError(500, -32603, "Internal server error"));
+    }
+    finally {
+        await transport.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+    }
+}
+function readRawBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+async function toWebRequest(req) {
+    const host = req.headers.host ?? "localhost";
+    const url = `http://${host}${req.url ?? "/"}`;
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined || HOP_BY_HOP.has(key.toLowerCase())) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                headers.append(key, entry);
+            }
+        }
+        else {
+            headers.set(key, value);
+        }
+    }
+    const method = req.method ?? "GET";
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const body = hasBody ? await readRawBody(req) : undefined;
+    return new Request(url, {
+        method,
+        headers,
+        body: body && body.byteLength > 0 ? body : undefined,
+    });
+}
+async function writeWebResponse(res, response) {
+    const body = Buffer.from(await response.arrayBuffer());
+    const headers = new Headers(response.headers);
+    headers.set("content-length", String(body.byteLength));
+    const outgoing = {};
+    headers.forEach((value, key) => {
+        outgoing[key] = value;
+    });
+    res.writeHead(response.status, outgoing);
+    res.end(body);
+}
+export function startHttpServer(options = {}) {
+    const host = options.host ?? "0.0.0.0";
+    const port = options.port ?? 3000;
+    const nodeServer = createServer(async (req, res) => {
+        try {
+            const request = await toWebRequest(req);
+            const response = await handleMcpHttpRequest(request);
+            await writeWebResponse(res, response);
+        }
+        catch (error) {
+            console.error(`HTTP server error: ${error instanceof Error ? error.message : String(error)}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                }));
+            }
+            else {
+                res.end();
+            }
+        }
+    });
+    return new Promise((resolve, reject) => {
+        nodeServer.once("error", reject);
+        nodeServer.listen(port, host, () => {
+            const address = nodeServer.address();
+            const boundPort = typeof address === "object" && address ? address.port : port;
+            console.error(`Desearch MCP listening on ${host}:${boundPort} (endpoint /mcp)`);
+            resolve({
+                host,
+                port: boundPort,
+                close: () => new Promise((closeResolve, closeReject) => {
+                    // Client transports abort the optional GET stream and can leave
+                    // a socket that close() would otherwise hold until timeout.
+                    nodeServer.closeAllConnections();
+                    nodeServer.close((error) => (error ? closeReject(error) : closeResolve()));
+                }),
+            });
+        });
+    });
+}