Skip to main content
Glama
deenesjakoruzh
mrgoonie

SearchAPI MCP Server

by mrgoonie
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

SearchAPI.site - Servidor MCP

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que conecta a los asistentes de IA con fuentes de datos externas (Google, Bing, etc.) a través de SearchAPI.site .

Plataformas disponibles

  • [x] Google - Búsqueda web

  • [x] Google - Búsqueda de imágenes

  • [x] Google - Búsqueda en YouTube

  • [ ] Búsqueda en Google Maps

  • [x] Bing - Búsqueda web

  • [ ] Bing - Búsqueda de imágenes

  • [ ] Reddit

  • [ ] X/Twitter

  • [ ] Búsqueda en Facebook

  • [ ] Búsqueda de grupos de Facebook

  • [ ] Instagram

  • [ ] TikTok

SearchAPI.site

Related MCP server: searchAPI-mcp

Transportes soportados

  • [x] Transporte "stdio" : transporte predeterminado para el uso de CLI

  • [x] Transporte"HTTP transmitible" : para clientes web

    • [ ] Implementar autenticación (encabezados "Autorización" con Bearer <token> )

  • [ ] transporte "sse" (Obsoleto)

  • [ ] Escribir pruebas

Cómo utilizar

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

Configuración de MCP

Para la configuración local con transporte stdio:

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

Para la configuración HTTP remota:

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

Variables de entorno para el transporte HTTP:

Puede configurar el servidor HTTP utilizando estas variables de entorno:

  • MCP_HTTP_HOST : El host al que vincularse (predeterminado: 127.0.0.1 )

  • MCP_HTTP_PORT : El puerto para escuchar (predeterminado: 8080 )

  • MCP_HTTP_PATH : La ruta del punto final (predeterminado: /mcp )

Descripción general del código fuente

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite a los sistemas de IA conectarse de forma segura y contextual con herramientas y fuentes de datos externas.

Esta plantilla implementa la especificación MCP con una arquitectura limpia y en capas que puede ampliarse para crear servidores MCP personalizados para cualquier API o fuente de datos.

¿Por qué utilizar este texto estándar?

  • Arquitectura lista para producción : sigue el mismo patrón utilizado en los servidores MCP publicados, con una clara separación entre CLI, herramientas, controladores y servicios.

  • Seguridad de tipos : creado con TypeScript para mejorar la experiencia del desarrollador, la calidad del código y la facilidad de mantenimiento.

  • Ejemplo de trabajo : incluye una herramienta de búsqueda de IP completamente implementada que demuestra el patrón completo desde la CLI hasta la integración de API.

  • Marco de pruebas : incluye infraestructura de pruebas para pruebas de integración unitarias y CLI, incluidos informes de cobertura.

  • Herramientas de desarrollo : incluye ESLint, Prettier, TypeScript y otras herramientas de calidad preconfiguradas para el desarrollo de servidores MCP.

Empezando

Prerrequisitos

  • Node.js (>=18.x): Descargar

  • Git : para el control de versiones

Paso 1: Clonar e instalar

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

# Install dependencies
npm install

Paso 2: Ejecutar el servidor de desarrollo

Inicie el servidor en modo de desarrollo con el transporte stdio (predeterminado):

npm run dev:server

O con el transporte HTTP Streamable:

npm run dev:server:http

Esto inicia el servidor MCP con recarga activa y habilita el Inspector MCP en http://localhost:5173 .

⚙️ El servidor proxy escucha en el puerto 6277 🔍 MCP Inspector está en funcionamiento en http://127.0.0.1:6274

Al utilizar el transporte HTTP, el servidor estará disponible en http://127.0.0.1:8080/mcp de forma predeterminada.

Paso 3: Pruebe la herramienta de ejemplo

Ejecute la herramienta de búsqueda de IP de ejemplo desde la CLI:

# 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"

Arquitectura

Este modelo sigue un patrón de arquitectura limpio y en capas que separa las preocupaciones y promueve la capacidad de mantenimiento.

Estructura del proyecto

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

Capas y responsabilidades

Capa CLI ( src/cli/*.cli.ts )

  • Propósito : Definir interfaces de línea de comandos que analizan argumentos y llaman a controladores.

  • Nombre : Los archivos deben llamarse <feature>.cli.ts

  • Pruebas : pruebas de integración de CLI en <feature>.cli.test.ts

Capa de herramientas ( src/tools/*.tool.ts )

  • Propósito : Definir herramientas MCP con esquemas y descripciones para asistentes de IA.

  • Nombre : Los archivos deben llamarse <feature>.tool.ts con tipos en <feature>.types.ts

  • Patrón : Cada herramienta debe usar zod para la validación de argumentos

Capa de controladores ( src/controllers/*.controller.ts )

  • Propósito : Implementar lógica empresarial, manejar errores y dar formato a respuestas.

  • Nombre : Los archivos deben llamarse <feature>.controller.ts

  • Patrón : Debe devolver objetos ControllerResponse estandarizados

Capa de servicios ( src/services/*.service.ts )

  • Propósito : Interactuar con API externas o fuentes de datos

  • Nombre : Los archivos deben llamarse <feature>.service.ts

  • Patrón : Interacciones de API puras con lógica mínima

Capa de utilidades ( src/utils/*.util.ts )

  • Propósito : Proporcionar funcionalidad compartida en toda la aplicación.

  • Utilidades clave :

    • logger.util.ts : Registro estructurado

    • error.util.ts : Manejo de errores y estandarización

    • formatter.util.ts : ayudantes de formato Markdown

Guía de desarrollo

Scripts de desarrollo

# 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]

Pruebas

# Run all tests
npm test

# Run specific tests
npm test -- src/path/to/test.ts

# Generate test coverage report
npm run test:coverage

evaluaciones

El paquete evals carga un cliente mcp que ejecuta el archivo index.ts, por lo que no es necesario reconstruir entre pruebas. Puede cargar variables de entorno prefijando el comando npx. Puede encontrar la documentación completa aquí .

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

Calidad del código

# Lint code
npm run lint

# Format code with Prettier
npm run format

# Check types
npm run typecheck

Creación de herramientas personalizadas

Siga estos pasos para agregar sus propias herramientas al servidor:

1. Definir la capa de servicio

Cree un nuevo servicio en src/services/ para interactuar con su API externa:

// 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. Crear controlador

Agregue un controlador en src/controllers/ para manejar la lógica empresarial:

// 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. Implementar la herramienta MCP

Crea una definición de herramienta en 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. Agregar compatibilidad con CLI

Cree un comando CLI en 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. Registrar componentes

Actualice los puntos de entrada para registrar sus nuevos componentes:

// 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);

Herramientas de depuración

Inspector de MCP

Acceda al Inspector visual de MCP para probar sus herramientas y ver los detalles de la solicitud/respuesta:

  1. Ejecutar npm run dev:server

  2. Abra http://localhost:5173 en su navegador

  3. Pruebe sus herramientas y vea los registros directamente en la interfaz de usuario

Registros del servidor

Habilitar registros de depuración para el desarrollo:

# Set environment variable
DEBUG=true npm run dev:server

# Or configure in ~/.mcp/configs.json

Publicación de su servidor MCP

Cuando esté listo para publicar su servidor MCP personalizado:

  1. Actualice package.json con sus datos

  2. Actualice README.md con la documentación de su herramienta

  3. Construya el proyecto: npm run build

  4. Pruebe la compilación de producción: npm run start:server

  5. Publicar en npm: npm publish

Licencia

Licencia ISC

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

Nota: Para garantizar la compatibilidad con versiones anteriores, el servidor también reconocerá las configuraciones con el nombre completo del paquete ( searchapi-mcp-server ) o con el nombre sin ámbito ( searchapi-mcp-server ) si no se encuentra la clave searchapi . Sin embargo, se recomienda usar la clave searchapi corta para las nuevas configuraciones.

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mrgoonie/searchapi-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server