Fish MCP Server

Busca especies de peces utilizando la base de datos FishBase. Admite consultas en lenguaje natural tanto en japonés como en inglés.

GitHubPrueba este MCPPatrocinado

Documentación

Fish MCP Server

Servidor MCP de búsqueda de peces compatible con japonés: sistema de búsqueda de información de peces que utiliza la base de datos FishBase

Resumen

Fish MCP Server es un servidor que proporciona funciones de búsqueda de peces a Claude Desktop mediante el Model Context Protocol (MCP). Utiliza datos de más de 35,000 especies de peces y más de 5,000 nombres en japonés de FishBase, y admite búsqueda en lenguaje natural en japonés e inglés.

Funciones principales

  • Búsqueda multilingüe: búsqueda de nombres de peces en japonés (hiragana, katakana, kanji) e inglés
  • Búsqueda de texto completo: búsqueda rápida de texto completo en japonés mediante SQLite FTS5
  • Búsqueda por características: búsqueda por condiciones como tamaño, hábitat, peligrosidad, etc.
  • Obtención de imágenes: obtención automática de imágenes de peces mediante la API de iNaturalist
  • Datos a gran escala: 35,731 especies de peces + 81,808 datos de nombres obtenidos de FishBase

Requisitos

  • Node.js 18.0.0 o superior
  • npm o yarn
  • Claude Desktop

Instalación

1. Clonación del proyecto y configuración

git clone <repository-url>
cd fish-mcp-server
npm install

2. Compilación de TypeScript

npm run build

3. Preparación de la base de datos

Carga de datos de muestra (para pruebas)

npm run load-sample-data

Carga completa de datos de FishBase (para uso en producción)

npm run load-data

4. Configuración de Claude Desktop

Agregue lo siguiente al archivo de configuración de Claude Desktop (~/.config/claude/claude_desktop_config.json o ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fish-mcp-server": {
      "command": "node",
      "args": ["/path/to/fish-mcp-server/dist/index.js"],
      "cwd": "/path/to/fish-mcp-server",
      "env": {
        "FISH_DB_PATH": "/path/to/fish-mcp-server/fish.db"
      }
    }
  }
}

Nota: reemplace /path/to/fish-mcp-server con la ruta real del proyecto.

Configuración mediante variables de entorno

  • FISH_DB_PATH: especifica la ruta absoluta del archivo de base de datos (opcional)
    • Si no se configura, se buscará automáticamente fish.db desde la raíz del proyecto
    • Se puede usar como medida de seguridad si cambia la estructura de compilación

5. Reinicio de Claude Desktop

Después de cambiar la configuración, reinicie Claude Desktop para cargar el servidor MCP.

Uso

En Claude Desktop puede hacer preguntas como las siguientes:

Ejemplos de búsqueda por nombre de pez

マグロについて教えて

tunaを検索して

あじの仲間を探して

Ejemplos de búsqueda por características

大きくて危険な海水魚を教えて

30cm以下の淡水魚はどんな種類がいますか？

深海魚を5種類教えて

Ejemplo de búsqueda con imágenes

クマノミの写真も含めて検索して

Herramientas disponibles

search_fish_by_name

Busca peces por nombre (en japonés o inglés).

Parámetros:

  • query (obligatorio): nombre del pez a buscar
  • limit (opcional): número máximo de resultados (predeterminado: 10)
  • includeImages (opcional): incluir información de imagen (predeterminado: false)

search_fish_by_features

Busca peces por características.

Parámetros:

  • minLength (opcional): tamaño mínimo (cm)
  • maxLength (opcional): tamaño máximo (cm)
  • dangerous (opcional): buscar solo peces peligrosos
  • saltwater (opcional): buscar solo peces de agua salada
  • deepwater (opcional): buscar solo peces de aguas profundas
  • commercial (opcional): buscar solo peces de importancia comercial
  • limit (opcional): número máximo de resultados (predeterminado: 20)
  • includeImages (opcional): incluir información de imagen (predeterminado: false)

Desarrollo

Scripts de desarrollo

# 開発サーバーの起動
npm run dev

# ビルド
npm run build

# テスト実行
npm run test-search
npm run test-fts5
npm run test-improved

# リント・フォーマット
npm run lint
npm run format
npm run check-all  # 開発時のチェック
npm run check-ci   # CI用の厳密チェック

Pruebas

# データベース状態確認
npx tsx tests/test-db-status.ts

# 検索機能テスト
npx tsx tests/test-search.ts

# FTS5機能テスト
npx tsx tests/test-fts5-simple.ts

Gestión de datos

# サンプルデータ読み込み
npm run load-sample-data

# FishBase全データ読み込み
npm run load-data

Fuentes de datos

  • FishBase: la base de datos de peces más grande del mundo
    • Datos de especies: 35,731 especies
    • Datos de nombres: 81,808 registros (5,204 en japonés, 76,604 en inglés)
  • API de iNaturalist: obtención de imágenes de peces

Stack tecnológico

  • Lenguaje: TypeScript
  • Runtime: Node.js
  • Base de datos: SQLite + FTS5
  • Protocolo: Model Context Protocol (MCP)
  • Framework: @modelcontextprotocol/sdk
  • Procesamiento de datos: parquet-wasm, apache-arrow
  • API de imágenes: API de iNaturalist

Arquitectura

src/
├── index.ts              # エントリーポイント
├── mcp/
│   ├── server.ts         # MCPサーバー実装
│   └── tools.ts          # MCP ツール定義
├── database/
│   ├── db-manager.ts     # データベース管理
│   ├── data-importer.ts  # データ読み込み
│   └── schema.sql        # データベーススキーマ
├── services/
│   ├── search-service.ts # 検索ロジック
│   ├── data-loader.ts    # FishBaseデータ読み込み
│   └── image-service.ts  # 画像取得サービス
└── types/               # 型定義

Solución de problemas

El servidor MCP no se carga

  1. Verifique los registros de Claude Desktop:

    tail -f ~/Library/Logs/Claude/mcp.log

  2. Verifique que la ruta sea correcta:

    ls -la /path/to/fish-mcp-server/dist/index.js

  3. Verifique que la compilación se haya completado correctamente:

    npm run build

Pocos resultados de búsqueda o no se encuentran resultados

  1. Verifique el estado de la base de datos:

    npx tsx tests/test-db-status.ts

  2. Reconstruya el índice FTS5:

    # データベースファイルを削除して再構築
rm fish.db
npm run load-data

No se pueden obtener imágenes

  • Debido a las limitaciones de la API de iNaturalist, es posible que no se puedan obtener imágenes para algunas especies de peces
  • Si el nombre científico es incorrecto, la búsqueda de imágenes puede fallar

Habilitación de registros de depuración

Si desea ver registros detallados de obtención de imágenes y búsqueda:

# 全てのデバッグログを有効化
DEBUG=fish-mcp:* npm run dev

# 特定のモジュールのみ
DEBUG=fish-mcp:image-service npm run dev
DEBUG=fish-mcp:search-service npm run dev

Licencia

Licencia ISC

Información para desarrolladores

Prohibición de salida por consola

En el entorno MCP, console.log y console.error están prohibidos porque interfieren con la comunicación JSON-RPC. Se detectan automáticamente mediante reglas de ESLint.

Resolución de rutas

Para evitar dependencias del entorno, todas las rutas de archivos se resuelven dinámicamente usando import.meta.url y fileURLToPath.

Hooks de pre-commit

Mediante Husky + lint-staged, se ejecutan automáticamente lint y formato antes de cada commit.