Search1API Connector Server

中文文档

A Model Context Protocol (MCP) adapter engineered to expose web search, content harvesting, and indexing capabilities leveraging the proprietary Search1API service.

Essential Prerequisites

• Runtime Environment: Node.js version 18.0.0 or newer.
• Authentication Credential: A valid, active Search1API access token (Consult the Configuration Manual below for provisioning details).

Deployment Instructions (Self-Contained Mode)

1. Source Code Acquisition: bash git clone https://github.com/fatwang2/search1api-mcp.git cd search1api-mcp

2. Credential Provisioning: Prior to compilation, the Search1API key must be injected. Refer to the Configuration Manual for established methods (e.g., using environment variables or a dedicated .env file).

3. Dependency Resolution and Artifact Generation: bash npm install npm run build

   Guidance: If utilizing the local .env configuration for key injection, ensure that file is present before executing the dependency installation and build process.

Operational Execution (Self-Contained Mode)

Verify that the requisite API credential has been successfully provisioned (see Configuration Manual).

Initiate the host process: bash npm start

The service endpoint will subsequently be active, prepared to process incoming requests from MCP-compliant client applications.

Configuration Manual

1. Acquiring the Search1API Token

1. Sign up via the official portal: Search1API
2. Retrieve your API access key from the administrative dashboard interface.

2. Token Injection Methods

Select and implement one of the subsequent configuration strategies to expose the API token to the service:

Strategy A: Project Local Configuration File (Recommended for Standalone or LibreChat Deployment)

This method is mandatory when integrating with the current iteration of LibreChat (refer to the dedicated integration chapter).

1. In the root directory of the search1api-mcp deployment, construct a file named .env: bash # Within the search1api-mcp directory context echo "SEARCH1API_KEY=your_api_key_here" > .env

2. Substitute your_api_key_here with your genuine credential.

3. This file must be in place preceding the execution of npm install && npm run build.

Strategy B: System Environment Variable (Standalone Operation Only)

Define the SEARCH1API_KEY variable within the operating environment prior to launching the server process.

bash export SEARCH1API_KEY="your_api_key_here" npm start

Strategy C: MCP Client Configuration Payload (Advanced Use Cases)

Certain specialized MCP clients permit direct specification of execution environment parameters within their respective configuration definitions. This is pertinent for utilities such as Cursor, VS Code extensions, etc.

{ "mcpServers": { "search1api": { "command": "npx", "args": [ "-y", "search1api-mcp" ], "env": { "SEARCH1API_KEY": "YOUR_SEARCH1API_KEY" } } } }

Note for LibreChat Integrators: Due to extant constraints within the LibreChat framework, Strategy A (Project .env File) is the mandatory approach. Consult the subsequent dedicated integration module for comprehensive instructions.

LibreChat Integration Protocol (Docker Environment)

This segment details the necessary sequence for weaving this server component into a LibreChat deployment managed via Docker.

Operational Summary:

1. Replicate this server's repository structure into a location accessible by your LibreChat docker-compose.yml orchestration file.
2. Finalize the requisite API token configuration utilizing the Project .env File strategy within this server's designated directory.
3. Compile the server artifacts.
4. Modify librechat.yaml to instruct LibreChat on executing this adapter service.
5. Establish a Docker volume mapping to ensure the compiled server binary is accessible within the LibreChat API container.
6. Trigger a restart of the LibreChat stack.

Sequential Implementation Steps:

1. Repository Cloning: Navigate to the directory on your host system dedicated to managing external services for LibreChat (this is typically co-located with the docker-compose.yml file). A conventional location might be a mcp-server subdirectory. bash # Illustrative path: Navigate to LibreChat root, then into the mcp-server container directory cd /path/to/your/librechat/setup git clone https://github.com/fatwang2/search1api-mcp.git

2. Enter Server Context: bash cd search1api-mcp

3. Token Configuration (Mandatory .env Strategy for LibreChat): bash # Generate the required .env configuration file echo "SEARCH1API_KEY=your_api_key_here" > .env # CRITICAL: Substitute 'your_api_key_here' with your actual Search1API credential

4. Artifact Compilation: This action generates the executable code within the build subdirectory. bash npm install npm run build

5. librechat.yaml Adaptation: Modify your primary librechat.yaml manifest to define the execution parameters for this MCP service. Augment the mcp_servers section: yaml # Within your primary librechat.yaml file mcp_servers: # You may include definitions for other MCP adaptors here search1api: # Optional: UI label displayed within the LibreChat interface # name: Search1API Tools

   # Specifies the runtime interpreter ('node' in this context)
   command: node
   
   # Arguments defining the script path *relative to the container's filesystem*
   args:
     - /app/mcp-server/search1api-mcp/build/index.js
   

   • Note on args path (/app/...): This path must accurately reflect the location inside the LibreChat API container where the compiled code resides (established by the volume mapping in the subsequent step).

6. Docker Volume Mapping Definition: Update your docker-compose.yml (or preferably docker-compose.override.yml) to establish a bidirectional bind between the host system's search1api-mcp directory and the LibreChat API container. Locate the volumes: block for the api: service: yaml # In your docker-compose.yml or docker-compose.override.yml services: api: # ... existing service configuration ... volumes: # ... existing volume entries ...

     # Add the new mapping for the search service:
     - ./mcp-server/search1api-mcp:/app/mcp-server/search1api-mcp
   

   • Host Location (./mcp-server/search1api-mcp): This path is relative to the location of your docker-compose.yml. Adjust if the repository was cloned to an alternative host location.
   • Container Destination (:/app/mcp-server/search1api-mcp): This path within the container must be consistent with the path specified in the librechat.yaml args directive.

7. Stack Restart: Apply the configuration adjustments by rebuilding (if docker-compose.yml changed) and restarting the entire LibreChat environment. bash docker compose down && docker compose up -d --build # Alternatively, if only librechat.yaml was altered: docker compose restart api

Upon successful restart, the Search1API adapter will function as an available utility provider within the LibreChat application interface.

Core Capabilities

• Standardized web search retrieval.
• Current events querying.
• Extraction of full textual content from web documents.
• Harvesting of URL navigation structures (sitemaps).
• Advanced cognitive processing and intricate query resolution via DeepSeek R1 integration.
• Native interoperability with diverse MCP clients including Claude Desktop, Cursor, Windsurf, Cline, and others.

Available Service Interfaces (Tools)

1. Search Utility

• Identifier: search
• Purpose: Execute standard web queries via Search1API.
• Inputs:
• query (Mandatory): Natural language articulation of the search request. Precision in phrasing yields superior outcomes.
• max_results (Optional, Default: 10): Limit on the quantity of search result snippets returned.
• search_service (Optional, Default: "google"): Engine selection for query execution (Options include: google, bing, duckduckgo, yahoo, x, reddit, github, youtube, arxiv, wechat, bilibili, imdb, wikipedia).
• crawl_results (Optional, Default: 0): Count of top results subjected to full page content extraction.
• include_sites (Optional): A list specifying domains that must be included in the search scope.
• exclude_sites (Optional): A list specifying domains to omit from search results.
• time_range (Optional): Constraint for result recency ("day", "month", "year").

2. News Aggregator Utility

• Identifier: news
• Purpose: Fetch indexed news articles using Search1API.
• Inputs:
• query (Mandatory): Descriptive term for the news subject.
• max_results (Optional, Default: 10): Upper bound for the number of retrieved articles.
• search_service (Optional, Default: "bing"): News source engine selection (Options include: google, bing, duckduckgo, yahoo, hackernews).
• crawl_results (Optional, Default: 0): Count of articles targeted for detailed content harvesting.
• include_sites (Optional): Domain whitelist for news sourcing.
• exclude_sites (Optional): Domain blacklist for news sourcing.
• time_range (Optional): Temporal filter for articles ("day", "month", "year").

3. Content Extraction Utility

• Identifier: crawl
• Purpose: Retrieve and parse the primary content body from a specified uniform resource locator (URL) using Search1API.
• Inputs:
• url (Mandatory): The precise web address to be processed.

4. Site Index Utility

• Identifier: sitemap
• Purpose: Discover and enumerate all referenced linkages associated with a given URL.
• Inputs:
• url (Mandatory): The foundational URL whose navigational structure is to be mapped.

5. Complex Reasoning Utility

• Identifier: reasoning
• Purpose: Engage in deep, multi-step analytical problem resolution, benefiting from the speed of the DeepSeek R1 model augmented with integrated web search capabilities (Note: Performance is optimized for R1; substituting models via the Search1API portal may impact speed guarantees).
• Inputs:
• content (Mandatory): The specific complex query or problem requiring analytical decomposition.

6. Trending Data Utility

• Identifier: trending
• Purpose: Report on currently popular subjects across designated digital platforms.
• Inputs:
• search_service (Mandatory): Selection of the platform to monitor for trends (currently supports: github, hackernews).
• max_results (Optional, Default: 10): Maximum cardinality of trending items to be outputted.

Revision Chronology

• v0.2.0: Introduced resilient configuration fallback mechanisms via .env for enhanced LibreChat deployment compatibility; dependency set upgraded.
• v0.1.8: Incorporated X (formerly Twitter) and Reddit search endpoints.
• v0.1.7: Launched the trending service interface, supporting GitHub and Hacker News data streams.
• v0.1.6: Integrated Wikipedia as a supported search provider.
• v0.1.5: Added nuanced search parameter controls (include_sites, exclude_sites, time_range) and broadened service availability (arxiv, wechat, bilibili, imdb).
• v0.1.4: Deployed the analytical reasoning tool utilizing DeepSeek R1; updated configuration guides for Cursor and Windsurf clients.
• v0.1.3: Implemented functionality for news article aggregation.
• v0.1.2: Established URL structure mapping capability (sitemap).
• v0.1.1: Activated core web document data harvesting (crawl).
• v0.1.0: Initial production release featuring foundational web search operations.

Licensing

This software artifact is distributed under the terms of the MIT License; consult the LICENSE file for comprehensive particulars.

WIKIPEDIA: XMLHttpRequest (XHR) constitutes an Application Programming Interface realized as a JavaScript object, facilitating the transmission of HTTP communications between a web browser client and a remote web server. These methods empower browser-resident applications to dispatch requests subsequent to initial page rendering, enabling the asynchronous reception of server data. XMLHttpRequest forms the bedrock of Ajax methodologies. Before its advent, user interaction with the server was principally mediated via standard hyperlinks or HTML form submissions, usually necessitating a full page reload.

== Genesis == The foundational concept for XMLHttpRequest was first conceptualized in the year 2000 by the engineering team responsible for Microsoft Outlook development. This notion was subsequently implemented within the Internet Explorer 5 browser environment (released in 1999). However, the initial syntax did not employ the standardized XMLHttpRequest identifier. Instead, developers relied upon instantiating COM objects using identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 arrived in 2006, comprehensive support for the formal XMLHttpRequest identifier had been universally adopted across all major browser platforms. The XMLHttpRequest identifier has since matured into the prevailing standard across the principal browser engines, including Mozilla's Gecko platform (2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Process === The World Wide Web Consortium (W3C) formally published the first iteration of the specification for the XMLHttpRequest object as a Working Draft on April 5, 2006. On February 25, 2008, the W3C released the Working Draft Level 2 specification. The Level 2 revision introduced enhancements such as event progress monitoring capabilities, explicit support for cross-site request execution, and methods for handling binary byte streams. By the conclusion of 2011, the specific features delineated in the Level 2 specification were formally integrated back into the primary, consolidated specification document. Toward the end of 2012, stewardship of the standard's ongoing maintenance and evolution transitioned to the WHATWG group, which currently maintains a dynamic document utilizing the Web IDL (Interface Definition Language) specification format.

== Operational Paradigm == Generally, orchestrating a data transmission utilizing XMLHttpRequest involves a defined sequence of programming actions.

1. Instantiation of an XMLHttpRequest object via a constructor call:
2. Invocation of the "open" method to define the transaction modality (request type), specify the target resource Uniform Resource Identifier (URI), and designate operational behavior as synchronous or asynchronous:
3. For asynchronous transactions, registration of an event listener function designed to intercept and process notifications regarding state transitions:
4. Initiation of the actual network request sequence by executing the "send" method, optionally supplying request body data:
5. Monitoring the state changes transmitted via the registered event listener. Upon reception of server response data, this information is typically aggregated within the "responseText" property. When the object completes all processing, its state transitions to 4, signifying the "done" status.

Beyond these fundamental stages, XMLHttpRequest affords numerous configuration levers to govern the request transmission dynamics and the ensuing response handling. Custom request header fields can be appended to mandate specific server behaviors, and data payloads can be uploaded during the "send" invocation. Furthermore, server responses can be automatically parsed from JSON structure into immediately usable JavaScript objects, or processed incrementally as data streams arrive instead of awaiting complete text assembly. The request operation retains the flexibility to be prematurely terminated or subjected to a defined timeout constraint.

== Inter-Origin Communications ==

During the nascent stages of the World Wide Web's evolution, it was discovered that allowing unrestricted access to resources across different security domains could facilitate malicious activities, leading to the implementation of restrictions on cross-domain data retrieval.