SearchAPI.site - MCP-Server
Dieses Projekt stellt einen Model Context Protocol (MCP)-Server bereit, der KI-Assistenten über SearchAPI.site mit externen Datenquellen (Google, Bing usw.) verbindet.
- [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
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
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):
Oder mit dem Streamable HTTP-Transport:
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.
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
- 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 Protokollierenerror.util.ts : Fehlerbehandlung und Standardisierungformatter.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
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',
});
}
}
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);
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.