SearchAPI.site - MCP Server

SearchAPI.site - MCP サーバー

このプロジェクトは、SearchAPI.site を介して AI アシスタントを外部データソース（Google、Bing など）に接続する Model Context Protocol（MCP）サーバーを提供します。

作成者： Claude

• Glama
• Github
• NPM

利用可能なプラットフォーム

• Google - ウェブ検索
• Google - 画像検索
• Google - YouTube 検索
• Google - マップ検索
• Bing - ウェブ検索
• Bing - 画像検索
• Reddit
• X/Twitter
• Facebook 検索
• Facebook グループ検索
• Instagram
• TikTok

SearchAPI.site

• ウェブサイト
• API ドキュメント
• Swagger UI 設定
• Search API キーをこちらで作成
• GitHub

対応トランスポート

• "stdio" トランスポート - CLI での使用におけるデフォルトのトランスポート
• "Streamable HTTP" トランスポート - ウェブベースのクライアント向け
  • 認証を実装（Bearer <token> を含む "Authorization" ヘッダー）
• "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

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 とは？

Model Context Protocol（MCP）は、AI システムが外部のツールやデータソースに、安全かつコンテキストに応じて接続できるようにするオープン標準です。

このボイラープレートは、MCP 仕様を明確に階層化されたアーキテクチャで実装しており、あらゆる API やデータソース向けのカスタム MCP サーバーを構築できるよう拡張できます。

このボイラープレートを使用する理由

• 本番環境に対応したアーキテクチャ：公開済みの MCP サーバーと同じパターンに従い、CLI、ツール、コントローラー、サービスを明確に分離しています。

• 型安全性：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 Inspector を利用できるようになります。

⚙️ プロキシサーバーがポート 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 とのやり取りに専念します

Utils レイヤー（src/utils/*.util.ts）

• 目的：アプリケーション全体で共有する機能を提供します
• 主な Utils：
  • 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

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. サービスレイヤーを定義する

外部 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 Inspector

ビジュアル MCP Inspector にアクセスして、ツールをテストし、リクエストとレスポンスの詳細を確認します：

1. npm run dev:server を実行します
2. ブラウザーで http://localhost:5173 を開きます
3. UI からツールをテストし、ログを直接確認します

サーバーログ

開発時にデバッグログを有効にします：

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

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

---

MCP サーバーの公開

カスタム MCP サーバーを公開する準備ができたら、以下を行います：

1. package.json を詳細情報で更新します
2. README.md をツールのドキュメントで更新します
3. プロジェクトをビルドします：npm run build
4. 本番ビルドをテストします：npm run start:server
5. npm に公開します：npm publish

---

ライセンス

ISC ライセンス

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

**注記：**後方互換性のため、searchapi キーが見つからない場合、サーバーは完全なパッケージ名（searchapi-mcp-server）またはスコープなしのパッケージ名（searchapi-mcp-server）を使った設定も認識します。ただし、新しい設定では短い searchapi キーを使用することをおすすめします。

共著者

• Claude Code（Claude AI アシスタント）
• Goon