SearchAPI.site - MCP-сервер
Этот проект предоставляет сервер Model Context Protocol (MCP), который подключает помощников на базе искусственного интеллекта к внешним источникам данных (Google, Bing и т. д.) через SearchAPI.site .
- [x] Google — поиск в Интернете
- [x] Google - Поиск изображений
- [x] Google - Поиск YouTube
- [ ] Google - Поиск на Картах
- [x] Bing — поиск в Интернете
- [ ] Bing — Поиск изображений
- [ ] Реддит
- [ ] X/Твиттер
- [ ] Поиск в Facebook
- [ ] Поиск группы Facebook
- [ ] Инстаграм
- [ ] ТикТок
SearchAPI.site
Поддерживаемые транспорты
- [x] "stdio" transport — транспорт по умолчанию для использования CLI
- [x] Транспорт«Streamable HTTP» — для веб-клиентов
- [ ] Реализовать аутентификацию (заголовки «Authorization» с
Bearer <token> )
- [ ]
"sse" транспорт (Устаревшее) - [ ] Написать тесты
Как использовать
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
Настройка МКП
Для локальной конфигурации с транспортом stdio:
{
"mcpServers": {
"searchapi": {
"command": "node",
"args": ["/path/to/searchapi-mcp-server/dist/index.js"],
"transportType": "stdio"
}
}
}
Для удаленной конфигурации HTTP:
{
"mcpServers": {
"searchapi": {
"type": "http",
"url": "http://mcp.searchapi.site/mcp"
}
}
}
Переменные среды для HTTP-транспорта:
Вы можете настроить HTTP-сервер, используя следующие переменные среды:
MCP_HTTP_HOST : Хост для привязки (по умолчанию: 127.0.0.1 )MCP_HTTP_PORT : Порт для прослушивания (по умолчанию: 8080 )MCP_HTTP_PATH : Путь к конечной точке (по умолчанию: /mcp )
Обзор исходного кода
Что такое МКП?
Model Context Protocol (MCP) — открытый стандарт, позволяющий системам искусственного интеллекта безопасно и контекстно подключаться к внешним инструментам и источникам данных.
Этот шаблон реализует спецификацию MCP с помощью чистой многоуровневой архитектуры, которую можно расширить для создания пользовательских серверов MCP для любого API или источника данных.
Зачем использовать этот шаблон?
- Архитектура, готовая к производству : следует той же схеме, которая используется в опубликованных серверах MCP, с четким разделением между CLI, инструментами, контроллерами и службами.
- Безопасность типов : создано с использованием TypeScript для улучшения опыта разработки, качества кода и удобства обслуживания.
- Рабочий пример : включает в себя полностью реализованный инструмент поиска IP-адресов, демонстрирующий полную модель от CLI до интеграции API.
- Тестовая среда : поставляется с тестовой инфраструктурой для модульных и интеграционных тестов CLI, включая отчеты о покрытии.
- Инструменты разработки : включают ESLint, Prettier, TypeScript и другие качественные инструменты, предварительно настроенные для разработки сервера MCP.
Начиная
Предпосылки
- Node.js (>=18.x): Загрузить
- Git : для контроля версий
Шаг 1: Клонирование и установка
# Clone the repository
git clone https://github.com/mrgoonie/searchapi-mcp-server.git
cd searchapi-mcp-server
# Install dependencies
npm install
Шаг 2: Запуск сервера разработки
Запустите сервер в режиме разработки с использованием транспорта stdio (по умолчанию):
Или с помощью потокового HTTP-транспорта:
Это запустит сервер MCP с горячей перезагрузкой и включит MCP Inspector по адресу http://localhost:5173 .
⚙️ Прокси-сервер прослушивает порт 6277 🔍 MCP Inspector запущен и работает по адресу http://127.0.0.1:6274
При использовании HTTP-транспорта сервер по умолчанию будет доступен по адресу http://127.0.0.1:8080/mcp .
Шаг 3: протестируйте пример инструмента
Запустите пример инструмента поиска IP-адресов из 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"
Архитектура
Этот шаблон следует четкой, многоуровневой архитектурной модели, которая разделяет проблемы и способствует удобству обслуживания.
Структура проекта
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
Уровни и обязанности
Уровень CLI ( src/cli/*.cli.ts )
- Цель : определение интерфейсов командной строки, которые анализируют аргументы и вызывают контроллеры.
- Именование : Файлы должны называться
<feature>.cli.ts - Тестирование : тесты интеграции CLI в
<feature>.cli.test.ts
- Цель : Определить инструменты MCP со схемами и описаниями для помощников ИИ.
- Именование : файлы должны иметь имена
<feature>.tool.ts с типами в <feature>.types.ts - Шаблон : Каждый инструмент должен использовать zod для проверки аргументов.
Уровень контроллеров ( src/controllers/*.controller.ts )
- Цель : Реализация бизнес-логики, обработка ошибок и форматирование ответов.
- Именование : Файлы должны называться
<feature>.controller.ts - Шаблон : Должен возвращать стандартизированные объекты
ControllerResponse
Уровень служб ( src/services/*.service.ts )
- Цель : Взаимодействие с внешними API или источниками данных.
- Именование : Файлы должны называться
<feature>.service.ts - Шаблон : чистое взаимодействие API с минимальной логикой
Уровень утилит ( src/utils/*.util.ts )
- Цель : Обеспечить общую функциональность для всего приложения.
- Ключевые возможности :
logger.util.ts : Структурированное ведение журналаerror.util.ts : Обработка ошибок и стандартизацияformatter.util.ts : Помощники форматирования Markdown
Руководство по разработке
Сценарии разработки
# 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]
Тестирование
# Run all tests
npm test
# Run specific tests
npm test -- src/path/to/test.ts
# Generate test coverage report
npm run test:coverage
оценки
Пакет evals загружает клиент mcp, который затем запускает файл index.ts, поэтому нет необходимости перестраиваться между тестами. Вы можете загрузить переменные среды, указав префикс команды npx. Полную документацию можно найти здесь .
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/searchapi.tool.ts
Качество кода
# Lint code
npm run lint
# Format code with Prettier
npm run format
# Check types
npm run typecheck
Создание пользовательских инструментов
Чтобы добавить собственные инструменты на сервер, выполните следующие действия:
1. Определите уровень обслуживания
Создайте новую службу в src/services/ для взаимодействия с вашим внешним API:
// 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. Создать контроллер
Добавьте контроллер в src/controllers/ для обработки бизнес-логики:
// 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. Внедрение инструмента MCP
Создайте определение инструмента в 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
Создайте команду CLI в 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. Регистрация компонентов
Обновите точки входа для регистрации новых компонентов:
// 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, чтобы протестировать свои инструменты и просмотреть сведения о запросах/ответах:
- Запустите
npm run dev:server - Откройте http://localhost:5173 в вашем браузере.
- Тестируйте свои инструменты и просматривайте журналы прямо в пользовательском интерфейсе
Журналы сервера
Включить журналы отладки для разработки:
# Set environment variable
DEBUG=true npm run dev:server
# Or configure in ~/.mcp/configs.json
Публикация вашего MCP-сервера
Когда вы будете готовы опубликовать свой собственный сервер MCP:
- Обновите package.json, указав свои данные.
- Обновите README.md документацией по вашему инструменту.
- Соберите проект:
npm run build - Протестируйте производственную сборку:
npm run start:server - Опубликовать в npm:
npm publish
Лицензия
Лицензия ISC
{
"searchapi": {
"environments": {
"DEBUG": "true",
"SEARCHAPI_API_KEY": "value"
}
}
}
Примечание: Для обратной совместимости сервер также распознает конфигурации под полным именем пакета ( searchapi-mcp-server ) или именем пакета без области действия ( searchapi-mcp-server ), если ключ searchapi не найден. Однако для новых конфигураций рекомендуется использовать короткий ключ searchapi .