SearchAPI MCP 서버

SearchAPI.site - MCP 서버

이 프로젝트는 SearchAPI.site를 통해 AI 어시스턴트를 외부 데이터 소스(Google, Bing 등)에 연결하는 MCP(Model Context Protocol) 서버를 제공합니다.

사용 가능한 플랫폼

[x] Google - 웹 검색
[x] Google - 이미지 검색
[x] Google - YouTube 검색
[ ] Google - 지도 검색
[x] Bing - 웹 검색
[ ] Bing - 이미지 검색
[ ] 레딧
[ ] X/트위터
[ ] 페이스북 검색
[ ] 페이스북 그룹 검색
[ ] 인스타그램
[ ] 틱톡

SearchAPI.site

지원되는 전송

[x] "stdio" 전송 - CLI 사용을 위한 기본 전송
[x]"스트리밍 가능한 HTTP" 전송 - 웹 기반 클라이언트용
- [ ] Bearer <token> 포함한 auth("Authorization" 헤더) 구현
[ ] ~~"sse" 운송~~ (더 이상 사용되지 않음)

사용 방법

CLI

지엑스피1

MCP 설정

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 )

소스 코드 개요

MCP란 무엇인가요?

MCP(Model Context Protocol)는 AI 시스템이 외부 도구 및 데이터 소스와 안전하고 상황에 맞게 연결할 수 있도록 하는 개방형 표준입니다.

이 보일러플레이트는 모든 API나 데이터 소스에 대한 사용자 정의 MCP 서버를 구축하기 위해 확장 가능한 깔끔하고 계층화된 아키텍처로 MCP 사양을 구현합니다.

왜 이 보일러플레이트를 사용해야 하나요?

프로덕션에 바로 적용 가능한 아키텍처 : CLI, 도구, 컨트롤러, 서비스를 명확하게 구분하여 게시된 MCP 서버에서 사용되는 것과 동일한 패턴을 따릅니다.
유형 안전성 : 개발자 경험, 코드 품질, 유지 관리 용이성을 개선하기 위해 TypeScript로 구축되었습니다.
실제 예제 : CLI에서 API 통합까지의 전체 패턴을 보여주는 완전히 구현된 IP 조회 도구가 포함되어 있습니다.
테스트 프레임워크 : 커버리지 보고를 포함하여 단위 및 CLI 통합 테스트를 위한 테스트 인프라가 제공됩니다.
개발 도구 : MCP 서버 개발을 위해 사전 구성된 ESLint, Prettier, TypeScript 및 기타 고품질 도구가 포함되어 있습니다.

시작하기

필수 조건

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 전송(기본값)을 사용하여 개발 모드로 서버를 시작합니다.

npm run dev:server

또는 Streamable HTTP 전송을 사용하면:

npm run dev:server:http

이렇게 하면 핫 리로딩으로 MCP 서버가 시작되고 http://localhost:5173 에서 MCP 검사기가 활성화됩니다.

⚙️ 포트 6277에서 수신 중인 프록시 서버 🔍 MCP Inspector가 http://127.0.0.1:6274 에서 실행 중입니다.

HTTP 전송을 사용하는 경우 서버는 기본적으로 http://127.0.0.1:8080/mcp 에서 사용할 수 있습니다.

3단계: 예제 도구 테스트

CLI에서 예제 IP 조회 도구를 실행합니다.

# 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 여야 합니다.
테스트 : <feature>.cli.test.ts 의 CLI 통합 테스트

도구 레이어( `src/tools/*.tool.ts` )

목적 : AI 어시스턴트에 대한 스키마와 설명을 포함하는 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 : 마크다운 서식 도우미

개발 가이드

개발 스크립트

# 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

코드 품질

# Lint code
npm run lint

# Format code with Prettier
npm run format

# Check types
npm run typecheck

사용자 정의 도구 구축

서버에 자신의 도구를 추가하려면 다음 단계를 따르세요.

1. 서비스 계층 정의

외부 API와 상호 작용하려면 src/services/ 에 새 서비스를 만드세요.

// 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 지원 추가

src/cli/ 에 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 검사관

시각적 MCP 검사기에 액세스하여 도구를 테스트하고 요청/응답 세부 정보를 확인하세요.

npm run dev:server
브라우저에서 http://localhost:5173을 엽니다.
UI에서 직접 도구를 테스트하고 로그를 확인하세요

서버 로그

개발을 위한 디버그 로그 활성화:

# 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 키를 찾을 수 없는 경우 전체 패키지 이름( searchapi-mcp-server ) 또는 범위가 지정되지 않은 패키지 이름( searchapi-mcp-server )으로 구성된 구성도 인식합니다. 하지만 새로운 구성에는 짧은 searchapi 키를 사용하는 것이 좋습니다.

Integrations