Fish MCP Server

Pesquise espécies de peixes usando o banco de dados FishBase. Suporta consultas em linguagem natural em japonês e inglês.

GitHubExperimente este MCPPatrocinado

Documentação

Fish MCP Server

Servidor MCP de busca de peixes com suporte a japonês - Sistema de busca de informações sobre peixes usando o banco de dados FishBase

Visão geral

O Fish MCP Server é um servidor que fornece recursos de busca de peixes ao Claude Desktop usando o Model Context Protocol (MCP). Utiliza dados de mais de 35.000 espécies de peixes do FishBase e mais de 5.000 nomes em japonês, com suporte a busca em linguagem natural em japonês e inglês.

Principais recursos

  • Busca multilíngue: busca de nomes de peixes em japonês (hiragana, katakana, kanji) e inglês
  • Busca de texto completo: busca rápida em texto completo em japonês com SQLite FTS5
  • Busca por características: busca por condições como tamanho, habitat, periculosidade
  • Obtenção de imagens: obtenção automática de imagens de peixes via iNaturalist API
  • Dados em larga escala: 35.731 espécies de peixes + 81.808 registros de nomes obtidos do FishBase

Requisitos

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

Instalação

1. Clonagem e configuração do projeto

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

2. Compilação do TypeScript

npm run build

3. Preparação do banco de dados

Carregamento de dados de exemplo (para testes)

npm run load-sample-data

Carregamento completo dos dados do FishBase (para produção)

npm run load-data

4. Configuração do Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop (~/.config/claude/claude_desktop_config.json ou ~/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"
      }
    }
  }
}

Atenção: substitua /path/to/fish-mcp-server pelo caminho real do projeto.

Configuração por variáveis de ambiente

  • FISH_DB_PATH: especifica o caminho absoluto do arquivo do banco de dados (opcional)
    • Se não for definido, fish.db será procurado automaticamente a partir da raiz do projeto
    • Pode ser usado como medida de segurança caso a estrutura de build seja alterada

5. Reinicialização do Claude Desktop

Após alterar as configurações, reinicie o Claude Desktop para carregar o servidor MCP.

Como usar

Você pode fazer perguntas como as seguintes no Claude Desktop:

Exemplos de busca por nome de peixe

マグロについて教えて

tunaを検索して

あじの仲間を探して

Exemplos de busca por características

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

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

深海魚を5種類教えて

Exemplo de busca com imagens

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

Ferramentas disponíveis

search_fish_by_name

Busca peixes pelo nome (em japonês ou inglês).

Parâmetros:

  • query (obrigatório): nome do peixe a ser buscado
  • limit (opcional): número máximo de resultados (padrão: 10)
  • includeImages (opcional): incluir informações de imagem (padrão: false)

search_fish_by_features

Busca peixes por características.

Parâmetros:

  • minLength (opcional): tamanho mínimo (cm)
  • maxLength (opcional): tamanho máximo (cm)
  • dangerous (opcional): buscar apenas peixes perigosos
  • saltwater (opcional): buscar apenas peixes marinhos
  • deepwater (opcional): buscar apenas peixes de águas profundas
  • commercial (opcional): buscar apenas peixes comercialmente importantes
  • limit (opcional): número máximo de resultados (padrão: 20)
  • includeImages (opcional): incluir informações de imagem (padrão: false)

Desenvolvimento

Scripts de desenvolvimento

# 開発サーバーの起動
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用の厳密チェック

Testes

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

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

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

Gerenciamento de dados

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

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

Fontes de dados

  • FishBase: o maior banco de dados de peixes do mundo
    • Dados de espécies: 35.731 espécies
    • Dados de nomes: 81.808 registros (5.204 em japonês, 76.604 em inglês)
  • iNaturalist API: obtenção de imagens de peixes

Stack de tecnologia

  • Linguagem: TypeScript
  • Runtime: Node.js
  • Banco de dados: SQLite + FTS5
  • Protocolo: Model Context Protocol (MCP)
  • Framework: @modelcontextprotocol/sdk
  • Processamento de dados: parquet-wasm, apache-arrow
  • API de imagens: iNaturalist API

Arquitetura

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/               # 型定義

Solução de problemas

O servidor MCP não carrega

  1. Verifique os logs do Claude Desktop:

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

  2. Verifique se o caminho está correto:

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

  3. Verifique se o build foi concluído corretamente:

    npm run build

Poucos resultados ou resultados não encontrados

  1. Verifique o estado do banco de dados:

    npx tsx tests/test-db-status.ts

  2. Reconstrua o índice FTS5:

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

Não é possível obter imagens

  • Devido às limitações da iNaturalist API, pode não ser possível obter imagens para algumas espécies de peixes
  • Se o nome científico estiver incorreto, a busca de imagens pode falhar

Ativação de logs de depuração

Se quiser ver logs detalhados de obtenção de imagens e buscas:

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

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

Licença

ISC License

Informações para desenvolvedores

Proibição de saída no console

No ambiente MCP, console.log e console.error são proibidos, pois interferem na comunicação JSON-RPC. Eles são detectados automaticamente pelas regras do ESLint.

Resolução de caminhos

Para evitar dependências de ambiente, todos os caminhos de arquivo são resolvidos dinamicamente usando import.meta.url e fileURLToPath.

Hooks de pre-commit

Com Husky + lint-staged, lint e formatação são executados automaticamente antes de cada commit.