SearchAPI.site - MCP-Server

Name: SearchAPI MCP Server
Author: mrgoonie

Dieses Projekt stellt einen Model Context Protocol (MCP)-Server bereit, der KI-Assistenten über SearchAPI.site mit externen Datenquellen (Google, Bing usw.) verbindet.

Verfügbare Plattformen

[x] Google - Websuche
[x] Google - Bildersuche
[x] Google - YouTube-Suche
[ ] Google - Maps Suche
[x] Bing - Websuche
[ ] Bing - Bildersuche
[ ] Reddit
[ ] X/Twitter
[ ] Facebook-Suche
[ ] Facebook-Gruppensuche
[ ] Instagram
[ ] TikTok

SearchAPI.site

Webseite
API-Dokumente
Swagger UI-Konfiguration
Erstellen Sie hier den Such-API-Schlüssel
GitHub

Related MCP server: searchAPI-mcp

Unterstützte Transporte

[x] "stdio" -Transport - Standardtransport für die CLI-Nutzung
[x]"Streamable HTTP" -Transport - Für webbasierte Clients
- [ ] Implementieren Sie Auth ("Authorization"-Header mit Bearer <token> )
[ ] ~~"sse"-Transport~~ (Veraltet)
[ ] Tests schreiben

Anwendung

Befehlszeilenschnittstelle (CLI)

# Google search via CLI npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key" # Google image search via CLI npm run dev:cli -- search-google-images --query "your search query" --api-key "your-api-key" # YouTube search via CLI npm run dev:cli -- search-youtube --query "your search query" --api-key "your-api-key" --max-results 5

MCP-Einrichtung

Für die lokale Konfiguration mit stdio-Transport:

{ "mcpServers": { "searchapi": { "command": "node", "args": ["/path/to/searchapi-mcp-server/dist/index.js"], "transportType": "stdio" } } }

Für die Remote-HTTP-Konfiguration:

{ "mcpServers": { "searchapi": { "type": "http", "url": "http://mcp.searchapi.site/mcp" } } }

Umgebungsvariablen für den HTTP-Transport:

Sie können den HTTP-Server mit diesen Umgebungsvariablen konfigurieren:

MCP_HTTP_HOST : Der Host, an den die Verbindung hergestellt werden soll (Standard: 127.0.0.1 )
MCP_HTTP_PORT : Der Port, auf dem gewartet werden soll (Standard: 8080 )
MCP_HTTP_PATH : Der Endpunktpfad (Standard: /mcp )

Quellcodeübersicht

Was ist MCP?

Model Context Protocol (MCP) ist ein offener Standard, der es KI-Systemen ermöglicht, sich sicher und kontextbezogen mit externen Tools und Datenquellen zu verbinden.

Dieses Boilerplate implementiert die MCP-Spezifikation mit einer sauberen, geschichteten Architektur, die erweitert werden kann, um benutzerdefinierte MCP-Server für jede API oder Datenquelle zu erstellen.

Warum diesen Standardtext verwenden?

Produktionsreife Architektur : Folgt dem gleichen Muster wie veröffentlichte MCP-Server, mit klarer Trennung zwischen CLI, Tools, Controllern und Diensten.
Typsicherheit : Erstellt mit TypeScript für verbesserte Entwicklererfahrung, Codequalität und Wartbarkeit.
Funktionierendes Beispiel : Enthält ein vollständig implementiertes IP-Lookup-Tool, das das komplette Muster von der CLI- bis zur API-Integration demonstriert.
Testframework : Wird mit einer Testinfrastruktur für Unit- und CLI-Integrationstests geliefert, einschließlich Abdeckungsberichten.
Entwicklungstools : Enthält ESLint, Prettier, TypeScript und andere hochwertige Tools, die für die MCP-Serverentwicklung vorkonfiguriert sind.

Erste Schritte

Voraussetzungen

Node.js (>=18.x): Herunterladen
Git : Zur Versionskontrolle

Schritt 1: Klonen und installieren

# Clone the repository git clone https://github.com/mrgoonie/searchapi-mcp-server.git cd searchapi-mcp-server # Install dependencies npm install

Schritt 2: Entwicklungsserver ausführen

Starten Sie den Server im Entwicklungsmodus mit stdio-Transport (Standard):

npm run dev:server

Oder mit dem Streamable HTTP-Transport:

npm run dev:server:http

Dadurch wird der MCP-Server mit Hot-Reloading gestartet und der MCP Inspector unter http://localhost:5173 aktiviert.

⚙️ Proxyserver lauscht auf Port 6277 🔍 MCP Inspector ist unter http://127.0.0.1:6274 aktiv

Bei Verwendung des HTTP-Transports ist der Server standardmäßig unter http://127.0.0.1:8080/mcp verfügbar.

Schritt 3: Testen Sie das Beispieltool

Führen Sie das Beispiel-IP-Lookup-Tool über die CLI aus:

# Using CLI in development mode npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key" # Or with a specific IP npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key" --limit 10 --offset 0 --sort "date:d" --from_date "2023-01-01" --to_date "2023-12-31"

Architektur

Dieser Standardtext folgt einem klaren, geschichteten Architekturmuster, das Belange trennt und die Wartbarkeit fördert.

Projektstruktur

src/ ├── cli/ # Command-line interfaces ├── controllers/ # Business logic ├── resources/ # MCP resources: expose data and content from your servers to LLMs ├── services/ # External API interactions ├── tools/ # MCP tool definitions ├── types/ # Type definitions ├── utils/ # Shared utilities └── index.ts # Entry point

Ebenen und Verantwortlichkeiten

CLI-Schicht ( `src/cli/*.cli.ts` )

Zweck : Definieren Sie Befehlszeilenschnittstellen, die Argumente analysieren und Controller aufrufen
Benennung : Dateien sollten <feature>.cli.ts heißen
Testen : CLI-Integrationstests in <feature>.cli.test.ts

Tools-Ebene ( `src/tools/*.tool.ts` )

Zweck : Definieren Sie MCP-Tools mit Schemata und Beschreibungen für KI-Assistenten
Benennung : Dateien sollten <feature>.tool.ts mit Typen in <feature>.types.ts benannt werden
Muster : Jedes Tool sollte zod zur Argumentvalidierung verwenden

Controller-Ebene ( `src/controllers/*.controller.ts` )

Zweck : Implementieren Sie Geschäftslogik, behandeln Sie Fehler und formatieren Sie Antworten
Benennung : Dateien sollten <feature>.controller.ts heißen
Muster : Sollte standardisierte ControllerResponse Objekte zurückgeben

Serviceebene ( `src/services/*.service.ts` )

Zweck : Interaktion mit externen APIs oder Datenquellen
Benennung : Dateien sollten <feature>.service.ts heißen
Muster : Reine API-Interaktionen mit minimaler Logik

Utils-Ebene ( `src/utils/*.util.ts` )

Zweck : Bereitstellung gemeinsamer Funktionen für die gesamte Anwendung
Wichtige Dienstprogramme :
- logger.util.ts : Strukturiertes Protokollieren
- error.util.ts : Fehlerbehandlung und Standardisierung
- formatter.util.ts : Markdown-Formatierungshilfen

Entwicklungshandbuch

Entwicklungsskripte

# Start server in development mode (hot-reload & inspector) npm run dev:server # Run CLI in development mode npm run dev:cli -- [command] [args] # Build the project npm run build # Start server in production mode npm run start:server # Run CLI in production mode npm run start:cli -- [command] [args]

Testen

# Run all tests npm test # Run specific tests npm test -- src/path/to/test.ts # Generate test coverage report npm run test:coverage

Bewertungen

Das Evals-Paket lädt einen MCP-Client, der anschließend die Datei index.ts ausführt, sodass zwischen den Tests kein Neuaufbau erforderlich ist. Sie können Umgebungsvariablen laden, indem Sie dem Befehl npx voranstellen. Die vollständige Dokumentation finden Sie hier .

OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/searchapi.tool.ts

Codequalität

# Lint code npm run lint # Format code with Prettier npm run format # Check types npm run typecheck

Erstellen benutzerdefinierter Tools

Befolgen Sie diese Schritte, um dem Server Ihre eigenen Tools hinzuzufügen:

1. Service-Layer definieren

Erstellen Sie einen neuen Dienst in src/services/ um mit Ihrer externen API zu interagieren:

// src/services/example.service.ts import { Logger } from '../utils/logger.util.js'; const logger = Logger.forContext('services/example.service.ts'); export async function getData(param: string): Promise<any> { logger.debug('Getting data', { param }); // API interaction code here return { result: 'example data' }; }

2. Controller erstellen

Fügen Sie einen Controller in src/controllers/ hinzu, um die Geschäftslogik zu handhaben:

// src/controllers/example.controller.ts import { Logger } from '../utils/logger.util.js'; import * as exampleService from '../services/example.service.js'; import { formatMarkdown } from '../utils/formatter.util.js'; import { handleControllerError } from '../utils/error-handler.util.js'; import { ControllerResponse } from '../types/common.types.js'; const logger = Logger.forContext('controllers/example.controller.ts'); export interface GetDataOptions { param?: string; } export async function getData( options: GetDataOptions = {}, ): Promise<ControllerResponse> { try { logger.debug('Getting data with options', options); const data = await exampleService.getData(options.param || 'default'); const content = formatMarkdown(data); return { content }; } catch (error) { throw handleControllerError(error, { entityType: 'ExampleData', operation: 'getData', source: 'controllers/example.controller.ts', }); } }

3. Implementieren Sie das MCP-Tool

Erstellen Sie eine Tooldefinition in src/tools/ :

// src/tools/example.tool.ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { z } from 'zod'; import { Logger } from '../utils/logger.util.js'; import { formatErrorForMcpTool } from '../utils/error.util.js'; import * as exampleController from '../controllers/example.controller.js'; const logger = Logger.forContext('tools/example.tool.ts'); const GetDataArgs = z.object({ param: z.string().optional().describe('Optional parameter'), }); type GetDataArgsType = z.infer<typeof GetDataArgs>; async function handleGetData(args: GetDataArgsType) { try { logger.debug('Tool get_data called', args); const result = await exampleController.getData({ param: args.param, }); return { content: [{ type: 'text' as const, text: result.content }], }; } catch (error) { logger.error('Tool get_data failed', error); return formatErrorForMcpTool(error); } } export function register(server: McpServer) { server.tool( 'get_data', `Gets data from the example API, optionally using \`param\`. Use this to fetch example data. Returns formatted data as Markdown.`, GetDataArgs.shape, handleGetData, ); }

4. CLI-Unterstützung hinzufügen

Erstellen Sie einen CLI-Befehl in src/cli/ :

// src/cli/example.cli.ts import { program } from 'commander'; import { Logger } from '../utils/logger.util.js'; import * as exampleController from '../controllers/example.controller.js'; import { handleCliError } from '../utils/error-handler.util.js'; const logger = Logger.forContext('cli/example.cli.ts'); program .command('get-data') .description('Get example data') .option('--param <value>', 'Optional parameter') .action(async (options) => { try { logger.debug('CLI get-data called', options); const result = await exampleController.getData({ param: options.param, }); console.log(result.content); } catch (error) { handleCliError(error); } });

5. Komponenten registrieren

Aktualisieren Sie die Einstiegspunkte, um Ihre neuen Komponenten zu registrieren:

// In src/cli/index.ts import '../cli/example.cli.js'; // In src/index.ts (for the tool) import exampleTool from './tools/example.tool.js'; // Then in registerTools function: exampleTool.register(server);

Debugging-Tools

MCP-Inspektor

Greifen Sie auf den visuellen MCP-Inspektor zu, um Ihre Tools zu testen und Anforderungs-/Antwortdetails anzuzeigen:

Führen Sie npm run dev:server
Öffnen Sie http://localhost:5173 in Ihrem Browser
Testen Sie Ihre Tools und zeigen Sie Protokolle direkt in der Benutzeroberfläche an

Serverprotokolle

Aktivieren Sie Debug-Protokolle für die Entwicklung:

# Set environment variable DEBUG=true npm run dev:server # Or configure in ~/.mcp/configs.json

Veröffentlichen Ihres MCP-Servers

Wenn Sie bereit sind, Ihren benutzerdefinierten MCP-Server zu veröffentlichen:

Aktualisieren Sie package.json mit Ihren Details
Aktualisieren Sie README.md mit Ihrer Tool-Dokumentation
Erstellen Sie das Projekt: npm run build
Testen Sie den Produktionsbuild: npm run start:server
Auf npm veröffentlichen: npm publish

Lizenz

ISC-Lizenz

{ "searchapi": { "environments": { "DEBUG": "true", "SEARCHAPI_API_KEY": "value" } } }

Hinweis: Aus Gründen der Abwärtskompatibilität erkennt der Server auch Konfigurationen mit dem vollständigen Paketnamen ( searchapi-mcp-server ) oder dem Paketnamen ohne Gültigkeitsbereich ( searchapi-mcp-server ), wenn der searchapi Schlüssel nicht gefunden wird. Für neue Konfigurationen wird jedoch die Verwendung des kurzen searchapi -Schlüssels empfohlen.