@agentsearchhq/agentsearch-mcp 1.0.0

package/.env.example

@@ -0,0 +1,18 @@
+# AgentSearch MCP configuration
+# Copy to .env for local testing (never commit .env)
+
+# Mode: "direct" (default) talks to a local/self-hosted AgentSearch API
+#       "portal" uses the Pocket Network agent portal (may require x402 payment)
+AGENTSEARCH_MODE=direct
+
+# Base URL for direct mode (no trailing slash)
+# Default: http://127.0.0.1:8000
+AGENTSEARCH_BASE_URL=http://127.0.0.1:8000
+
+# Optional Bearer token for direct mode Authorization header
+# If the server returns 401 with the key, the client retries once without it
+AGENTSEARCH_API_KEY=
+
+# Portal reference (used when AGENTSEARCH_MODE=portal):
+#   POST https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search
+#   body: {"query":"...","max_results":5}

package/.mcpbignore

@@ -0,0 +1,43 @@
+# Extra exclusions for `mcpb pack` (combined with the CLI defaults:
+# .git, *.map, node_modules/.cache, node_modules/.bin, logs, lockfiles).
+# Leading / anchors a pattern to the repo root so it does not strip
+# files inside bundled node_modules.
+
+.git/
+.github/
+.cursor/
+.vscode/
+.idea/
+
+# TypeScript sources; the Node entry is dist/index.js.
+# Source maps (dist/*.js.map from tsc sourceMap) are excluded by default;
+# listed here so they stay out if that default changes.
+/src/
+*.js.map
+*.mjs.map
+*.cjs.map
+*.ts.map
+*.tsbuildinfo
+
+# Secrets and local env. .env.example has no secrets and may ship.
+.env
+.env.*
+!.env.example
+
+# Tests and coverage
+/tests/
+/test/
+/coverage/
+/__tests__/
+
+# Dev-only trees if packing the repo root (the pack script installs
+# production dependencies in a staging directory instead).
+/node_modules/typescript/
+/node_modules/@types/
+/node_modules/@anthropic-ai/
+/scripts/
+
+# Pack output and npm tarballs
+*.mcpb
+*.tgz
+*.log

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentSearch / Angel Mendez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# agentsearch-mcp
+
+MCP (Model Context Protocol) server that exposes **AgentSearch** web search — and optional URL extract — to Cursor, Claude Desktop, and other MCP hosts over **stdio**.
+
+[AgentSearch](https://agentsearchhq.com) is a web-search API aimed at agents. You can run it against a **local/self-hosted** AgentSearch instance (`direct` mode) or the **Pocket Network agent portal** (`portal` mode).
+
+- Portal search endpoint (reference):  
+  `POST https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search`  
+  body: `{ "query": "...", "max_results": 5 }`
+- Direct search: `POST {AGENTSEARCH_BASE_URL}/v1/search` with the same body  
+- Direct extract: `POST {AGENTSEARCH_BASE_URL}/v1/extract`
+
+Pocket explorer: [agentsearch-web-search-v1](https://explorer.pocket.network/service/agentsearch-web-search-v1)
+
+> **Discovery:** This package is free to list and use. There is no paid promotion channel — discovery comes from MCP Registry / Smithery / Glama listings and real usage.
+
+---
+
+## Tools
+
+| Tool | Args | Description |
+|------|------|-------------|
+| `agentsearch_web_search` | `query` (string, required), `max_results` (number, optional, default 5, clamped 1–10) | Web search in direct or portal mode. Returns pretty-printed JSON. Use for a query; use extract when you already have a URL. Read-only HTTP. |
+| `agentsearch_extract` | `url` (absolute URL, required), `formats` (string[], optional), `max_chars` (positive integer, optional) | Page extract via `POST /v1/extract`. **Direct mode only** — portal fails before any request. Use when you already have a URL. Read-only HTTP. |
+
+On portal **HTTP 402**, the search tool returns a clear MCP error that **x402 payment is required** (or switch to `AGENTSEARCH_MODE=direct`). In portal mode, `agentsearch_extract` does not call the network; it returns an MCP error telling you to switch to direct mode or use search.
+
+---
+
+## Requirements
+
+- Node.js **20+**
+- An AgentSearch backend for `direct` mode (default `http://127.0.0.1:8000`), **or** portal access for `portal` mode
+
+---
+
+## Install & build
+
+Published package:
+
+```bash
+npx -y @agentsearchhq/agentsearch-mcp
+# or install into a project
+npm i @agentsearchhq/agentsearch-mcp
+```
+
+From a local checkout:
+
+```bash
+cd agentsearch-mcp
+npm install
+npm run build
+```
+
+Scripts: `build` → `tsc`, `start` → `node dist/index.js`, `prepare` → runs build (for publish).
+
+Binary: `agentsearch-mcp` → `dist/index.js`
+
+---
+
+## Environment variables
+
+| Variable | Default | Notes |
+|----------|---------|--------|
+| `AGENTSEARCH_MODE` | `direct` | `direct` \| `portal` |
+| `AGENTSEARCH_BASE_URL` | `http://127.0.0.1:8000` | Direct mode base URL (no trailing slash) |
+| `AGENTSEARCH_API_KEY` | _(empty)_ | Optional `Authorization: Bearer …` for direct; on **401** the client retries once **without** the key |
+
+See `.env.example`. Never commit a real `.env`.
+
+---
+
+## Cursor `mcp.json`
+
+**Project** (`.cursor/mcp.json`) or **user** (`~/.cursor/mcp.json` / Cursor Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "agentsearch": {
+      "command": "node",
+      "args": [
+        "C:/Users/Holla/OneDrive/Desktop/AgentSearch/agentsearch-mcp/dist/index.js"
+      ],
+      "env": {
+        "AGENTSEARCH_MODE": "direct",
+        "AGENTSEARCH_BASE_URL": "http://127.0.0.1:8000"
+      }
+    }
+  }
+}
+```
+
+After `npm install && npm run build`, optionally use the bin:
+
+```json
+{
+  "mcpServers": {
+    "agentsearch": {
+      "command": "npx",
+      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
+      "env": {
+        "AGENTSEARCH_MODE": "direct",
+        "AGENTSEARCH_BASE_URL": "http://127.0.0.1:8000"
+      }
+    }
+  }
+}
+```
+
+Use `npx -y @agentsearchhq/agentsearch-mcp` (or `npm i @agentsearchhq/agentsearch-mcp`) once the package is on npm. The local path form is for a checkout of this repo.
+
+Optional API key (direct only):
+
+```json
+"env": {
+  "AGENTSEARCH_MODE": "direct",
+  "AGENTSEARCH_BASE_URL": "http://127.0.0.1:8000",
+  "AGENTSEARCH_API_KEY": "your-key-here"
+}
+```
+
+---
+
+## Claude Desktop
+
+Edit Claude Desktop config (`claude_desktop_config.json`):
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "agentsearch": {
+      "command": "node",
+      "args": [
+        "C:/Users/Holla/OneDrive/Desktop/AgentSearch/agentsearch-mcp/dist/index.js"
+      ],
+      "env": {
+        "AGENTSEARCH_MODE": "direct",
+        "AGENTSEARCH_BASE_URL": "http://127.0.0.1:8000"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+## Local run (smoke)
+
+```bash
+npm run build
+# MCP hosts spawn the process; for a quick boot check:
+node dist/index.js
+# (process waits on stdin — Ctrl+C to stop)
+```
+
+---
+
+## Publish (high level)
+
+No paid promo — list the package so tools can discover it via registries and usage.
+
+### npm
+
+1. `npm login` (the `@agentsearchhq` org must allow the publisher)
+2. Confirm `name` is `@agentsearchhq/agentsearch-mcp` and `version` is `1.0.0` in `package.json` (`publishConfig.access` is `public`)
+3. `npm publish` (ensure `prepare`/`build` succeed; no secrets in the tarball)
+
+### MCP Registry
+
+1. Ensure `server.json` matches your npm package + stdio transport
+2. Follow the [MCP Registry](https://github.com/modelcontextprotocol/registry) publish flow (authenticate publisher, submit server metadata)
+3. Verify the listing resolves `@agentsearchhq/agentsearch-mcp` / stdio
+
+### Smithery
+
+Publish with the durable helper (preferred):
+
+```bash
+npm run smithery:publish
+```
+
+That runs `scripts/publish-smithery.mjs`, which ensures `agentsearch-mcp.mcpb` exists (`npm run mcpb:pack` if missing), idempotently patches the global Smithery CLI so the deploy payload always includes a tool `inputSchema` object when the MCPB omitted it, then runs `smithery mcp publish ./agentsearch-mcp.mcpb -n agentsearchhq/agentsearch-mcp`.
+
+**MCPB note:** `manifest.json` must **omit** tool `inputSchema` — `mcpb validate` rejects it. The publish helper patches the CLI payload side instead.
+
+Manual equivalent (after CLI is patched):
+
+```bash
+npm run mcpb:pack
+smithery mcp publish ./agentsearch-mcp.mcpb -n agentsearchhq/agentsearch-mcp
+```
+
+`npm run mcpb:pack` compiles TypeScript to `dist/index.js`, installs production dependencies, then writes `agentsearch-mcp.mcpb`. Check the manifest with `npm run mcpb:validate`. `manifest.json` (MCPB 0.3) launches `node ${__dirname}/dist/index.js` and maps optional `AGENTSEARCH_MODE` (default `direct`), `AGENTSEARCH_BASE_URL` (default `http://127.0.0.1:8000`), and sensitive `AGENTSEARCH_API_KEY`. `smithery.yaml` remains as start-command metadata. Dry-run patch detection only: `node scripts/publish-smithery.mjs --dry-patch`.
+
+### Glama
+
+1. Submit the GitHub (or npm) package to [Glama](https://glama.ai) MCP directory
+2. Link README + tools list; keep env docs in sync
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP client for AgentSearch search + extract backends.
+ * Modes: direct (local/self-hosted) | portal (Pocket agent portal).
+ */
+export type AgentSearchMode = "direct" | "portal";
+export interface AgentSearchConfig {
+    mode: AgentSearchMode;
+    baseUrl: string;
+    apiKey?: string;
+}
+export interface SearchRequest {
+    query: string;
+    max_results: number;
+}
+export interface ExtractRequest {
+    url: string;
+    formats?: string[];
+    max_chars?: number;
+}
+export declare class AgentSearchHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly paymentRequired: boolean;
+    constructor(status: number, body: string);
+}
+export declare function loadConfig(): AgentSearchConfig;
+export declare function webSearch(cfg: AgentSearchConfig, req: SearchRequest): Promise<unknown>;
+export declare function extractPage(cfg: AgentSearchConfig, req: ExtractRequest): Promise<unknown>;
+export declare function clampMaxResults(n: number | undefined, fallback?: number): number;

package/dist/client.js

@@ -0,0 +1,93 @@
+/**
+ * HTTP client for AgentSearch search + extract backends.
+ * Modes: direct (local/self-hosted) | portal (Pocket agent portal).
+ */
+export class AgentSearchHttpError extends Error {
+    status;
+    body;
+    paymentRequired;
+    constructor(status, body) {
+        const paymentRequired = status === 402;
+        super(paymentRequired
+            ? `AgentSearch portal returned 402 Payment Required (x402). Use AGENTSEARCH_MODE=direct with a local/self-hosted AgentSearch API, or complete portal payment.`
+            : `AgentSearch HTTP ${status}: ${body.slice(0, 500)}`);
+        this.name = "AgentSearchHttpError";
+        this.status = status;
+        this.body = body;
+        this.paymentRequired = paymentRequired;
+    }
+}
+const PORTAL_SEARCH_URL = "https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search";
+export function loadConfig() {
+    const rawMode = (process.env.AGENTSEARCH_MODE ?? "direct").trim().toLowerCase();
+    const mode = rawMode === "portal" ? "portal" : "direct";
+    const baseUrl = (process.env.AGENTSEARCH_BASE_URL ?? "http://127.0.0.1:8000").replace(/\/+$/, "");
+    const apiKey = process.env.AGENTSEARCH_API_KEY?.trim() || undefined;
+    return { mode, baseUrl, apiKey };
+}
+function searchUrl(cfg) {
+    if (cfg.mode === "portal")
+        return PORTAL_SEARCH_URL;
+    return `${cfg.baseUrl}/v1/search`;
+}
+function extractUrl(cfg) {
+    // Extract is only defined for direct in this package; portal extract may differ.
+    return `${cfg.baseUrl}/v1/extract`;
+}
+async function postJson(url, body, apiKey, opts) {
+    const headers = {
+        "content-type": "application/json",
+        accept: "application/json",
+    };
+    if (apiKey) {
+        headers.authorization = `Bearer ${apiKey}`;
+    }
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (res.status === 401 &&
+        apiKey &&
+        opts?.retryWithoutKeyOn401 !== false) {
+        // Direct mode: some deployments reject a present key; retry once without it.
+        return postJson(url, body, undefined, { retryWithoutKeyOn401: false });
+    }
+    if (res.status === 402) {
+        throw new AgentSearchHttpError(402, text);
+    }
+    if (!res.ok) {
+        throw new AgentSearchHttpError(res.status, text || res.statusText);
+    }
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+export async function webSearch(cfg, req) {
+    const url = searchUrl(cfg);
+    const key = cfg.mode === "direct" ? cfg.apiKey : undefined;
+    return postJson(url, { query: req.query, max_results: req.max_results }, key, { retryWithoutKeyOn401: cfg.mode === "direct" });
+}
+export async function extractPage(cfg, req) {
+    if (cfg.mode === "portal") {
+        throw new Error("agentsearch_extract is only supported in AGENTSEARCH_MODE=direct (POST {BASE}/v1/extract). Switch to direct mode or call search only.");
+    }
+    const url = extractUrl(cfg);
+    const body = { url: req.url };
+    if (req.formats)
+        body.formats = req.formats;
+    if (req.max_chars !== undefined)
+        body.max_chars = req.max_chars;
+    return postJson(url, body, cfg.apiKey, { retryWithoutKeyOn401: true });
+}
+export function clampMaxResults(n, fallback = 5) {
+    const v = typeof n === "number" && Number.isFinite(n) ? Math.trunc(n) : fallback;
+    return Math.min(10, Math.max(1, v));
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * AgentSearch MCP server — stdio transport.
+ * Tools: agentsearch_web_search, agentsearch_extract
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * AgentSearch MCP server — stdio transport.
+ * Tools: agentsearch_web_search, agentsearch_extract
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerSearchTools } from "./tools/search.js";
+import { loadConfig } from "./client.js";
+async function main() {
+    const cfg = loadConfig();
+    const server = new McpServer({
+        name: "agentsearch-mcp",
+        version: "1.0.0",
+    });
+    registerSearchTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for MCP JSON-RPC; log to stderr only
+    console.error(`agentsearch-mcp listening on stdio (mode=${cfg.mode}, base=${cfg.baseUrl})`);
+}
+main().catch((err) => {
+    console.error("agentsearch-mcp failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,KAAK,CACX,4CAA4C,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,OAAO,GAAG,CAC7E,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/search.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSearchTools(server: McpServer): void;

package/dist/tools/search.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { AgentSearchHttpError, clampMaxResults, loadConfig, webSearch, extractPage, } from "../client.js";
+function formatResult(data) {
+    try {
+        return JSON.stringify(data, null, 2);
+    }
+    catch {
+        return String(data);
+    }
+}
+function errorContent(err) {
+    let text;
+    if (err instanceof AgentSearchHttpError) {
+        text = err.message;
+    }
+    else if (err instanceof Error) {
+        text = err.message;
+    }
+    else {
+        text = String(err);
+    }
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+const WEB_SEARCH_DESCRIPTION = [
+    "Search the web through AgentSearch and return the backend response as pretty-printed JSON text (a non-JSON body is wrapped as {raw: text}).",
+    "Use this when you have a query and need hits rather than a page body; if you already have a URL, use agentsearch_extract instead.",
+    "Works in AGENTSEARCH_MODE=direct (default; POST {AGENTSEARCH_BASE_URL}/v1/search) or portal (Pocket).",
+    "Read-only HTTP POST: not destructive, but it uses the network and can hit backend rate limits.",
+    "Direct mode sends a Bearer token from AGENTSEARCH_API_KEY when that variable is set, and retries once without the key on HTTP 401; portal ignores the key, and HTTP 402 is an MCP error that x402 payment is required (or switch to direct).",
+    "Other HTTP failures are MCP errors with the status and a truncated body.",
+    "Integers for max_results outside 1–10 are clamped (default 5), not rejected.",
+].join(" ");
+const EXTRACT_DESCRIPTION = [
+    "Extract the content of one absolute URL through AgentSearch and return the backend response as pretty-printed JSON text (a non-JSON body is wrapped as {raw: text}).",
+    "Use this only when you already have the page URL and need its body; to find pages from a query, use agentsearch_web_search instead.",
+    "Direct mode only: AGENTSEARCH_MODE=portal fails immediately with an MCP error telling you to switch to direct or call search, and no HTTP request is sent; direct mode POSTs {AGENTSEARCH_BASE_URL}/v1/extract.",
+    "Read-only HTTP POST: not destructive, but it fetches through AgentSearch and can hit network or backend rate limits.",
+    "When AGENTSEARCH_API_KEY is set it is sent as a Bearer token, and HTTP 401 is retried once without the key; HTTP 402 is an MCP error that x402 payment is required (or switch to direct), and any other HTTP failure includes the status and a truncated body.",
+    'formats, when provided, is forwarded unchanged (for example "markdown" or "text") and is not limited to an enum; max_chars, when set, is a positive integer cap sent to the API rather than applied by this server.',
+].join(" ");
+export function registerSearchTools(server) {
+    server.registerTool("agentsearch_web_search", {
+        title: "AgentSearch Web Search",
+        description: WEB_SEARCH_DESCRIPTION,
+        inputSchema: {
+            query: z
+                .string()
+                .min(1)
+                .describe("Keywords or a natural-language question to search for."),
+            max_results: z
+                .number()
+                .int()
+                .optional()
+                .describe("How many hits to request (1–10, default 5)."),
+        },
+    }, async ({ query, max_results }) => {
+        try {
+            const cfg = loadConfig();
+            const clamped = clampMaxResults(max_results);
+            const data = await webSearch(cfg, {
+                query,
+                max_results: clamped,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatResult(data),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    server.registerTool("agentsearch_extract", {
+        title: "AgentSearch Extract",
+        description: EXTRACT_DESCRIPTION,
+        inputSchema: {
+            url: z.string().url().describe("Absolute URL of the page to extract."),
+            formats: z
+                .array(z.string())
+                .optional()
+                .describe('Optional format names to request, e.g. ["markdown","text"].'),
+            max_chars: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Optional positive limit on extracted characters."),
+        },
+    }, async ({ url, formats, max_chars }) => {
+        try {
+            const cfg = loadConfig();
+            const data = await extractPage(cfg, { url, formats, max_chars });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatResult(data),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

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

package/manifest.json

@@ -0,0 +1,78 @@
+{
+  "manifest_version": "0.3",
+  "name": "agentsearch-mcp",
+  "display_name": "AgentSearch MCP",
+  "version": "1.0.0",
+  "description": "MCP server for AgentSearch web search and optional page extract (direct API or Pocket portal).",
+  "long_description": "Stdio MCP server that calls AgentSearch web search and, in direct mode, URL extract. Configure AGENTSEARCH_MODE (direct or portal), AGENTSEARCH_BASE_URL, and an optional AGENTSEARCH_API_KEY.",
+  "author": {
+    "name": "AgentSearch",
+    "url": "https://github.com/agentsearchhq-coder"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentsearchhq-coder/agentsearch-mcp"
+  },
+  "homepage": "https://agentsearchhq.com",
+  "documentation": "https://github.com/agentsearchhq-coder/agentsearch-mcp#readme",
+  "support": "https://github.com/agentsearchhq-coder/agentsearch-mcp/issues",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "agentsearch",
+    "web-search",
+    "pocket-network"
+  ],
+  "compatibility": {
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "node": ">=20"
+    }
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/dist/index.js"],
+      "env": {
+        "AGENTSEARCH_MODE": "${user_config.AGENTSEARCH_MODE}",
+        "AGENTSEARCH_BASE_URL": "${user_config.AGENTSEARCH_BASE_URL}",
+        "AGENTSEARCH_API_KEY": "${user_config.AGENTSEARCH_API_KEY}"
+      }
+    }
+  },
+  "tools": [
+    {
+      "name": "agentsearch_web_search",
+      "description": "Search the web via AgentSearch (direct or Pocket portal) and return JSON text. Use extract when you already have a URL. Read-only."
+    },
+    {
+      "name": "agentsearch_extract",
+      "description": "Extract one page from a URL (direct mode only). Use web search to find URLs. Read-only; returns JSON text."
+    }
+  ],
+  "user_config": {
+    "AGENTSEARCH_MODE": {
+      "type": "string",
+      "title": "AgentSearch mode",
+      "description": "direct (local or self-hosted API) or portal (Pocket Network). Default direct.",
+      "default": "direct",
+      "required": false
+    },
+    "AGENTSEARCH_BASE_URL": {
+      "type": "string",
+      "title": "AgentSearch base URL",
+      "description": "Base URL for direct mode, without a trailing slash.",
+      "default": "http://127.0.0.1:8000",
+      "required": false
+    },
+    "AGENTSEARCH_API_KEY": {
+      "type": "string",
+      "title": "AgentSearch API key",
+      "description": "Optional Bearer token for direct mode. Leave blank if the API does not require a key.",
+      "sensitive": true,
+      "required": false
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agentsearchhq/agentsearch-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.agentsearchhq-coder/agentsearch-mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "MCP server for AgentSearch web search (and optional extract) — direct or Pocket portal",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentsearch-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example",
+    "server.json",
+    "smithery.yaml",
+    "manifest.json",
+    ".mcpbignore"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "mcpb:validate": "mcpb validate manifest.json",
+    "mcpb:pack": "npm run build && node scripts/pack-mcpb.mjs",
+    "smithery:publish": "node scripts/publish-smithery.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agentsearch",
+    "web-search",
+    "pocket-network"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.agentsearchhq-coder/agentsearch-mcp",
+  "description": "AgentSearch web search (and optional page extract) via MCP stdio. Direct local API or Pocket portal.",
+  "repository": {
+    "url": "https://github.com/agentsearchhq-coder/agentsearch-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@agentsearchhq/agentsearch-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "AGENTSEARCH_MODE",
+          "description": "direct | portal (default direct)",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "AGENTSEARCH_BASE_URL",
+          "description": "Base URL for direct mode (default http://127.0.0.1:8000)",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "AGENTSEARCH_API_KEY",
+          "description": "Optional Bearer token for direct mode",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,30 @@
+# Smithery.ai publish metadata for agentsearch-mcp
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      agentsearchMode:
+        type: string
+        enum: [direct, portal]
+        default: direct
+        description: direct local API or Pocket portal
+      agentsearchBaseUrl:
+        type: string
+        default: http://127.0.0.1:8000
+        description: Base URL for direct mode
+      agentsearchApiKey:
+        type: string
+        description: Optional Bearer token for direct mode
+  commandFunction: |-
+    (config) => ({
+      command: 'node',
+      args: ['dist/index.js'],
+      env: {
+        AGENTSEARCH_MODE: config.agentsearchMode ?? 'direct',
+        AGENTSEARCH_BASE_URL: config.agentsearchBaseUrl ?? 'http://127.0.0.1:8000',
+        ...(config.agentsearchApiKey
+          ? { AGENTSEARCH_API_KEY: config.agentsearchApiKey }
+          : {})
+      }
+    })