Species MCP Server Usage - jra3/mulm GitHub Wiki

Species Database MCP Server - Usage Guide

Overview

The Species Database MCP Server provides tools and resources for managing the species database through Claude Desktop and other MCP clients.

Database Schema: The database uses a split schema with separate tables for common names (species_common_name) and scientific names (species_scientific_name), both linked to species groups (species_name_group). See Species MCP Server Specification for complete schema details.

Setup

1. Install Dependencies

The MCP SDK is already installed as a dev dependency:

npm install

2. Configure Database

Create src/config.json with your database location:

{
  "databaseFile": "src/database.db"
}

Note: This file is gitignored. Each developer needs to create their own.

3. Test the Server

Run the MCP server directly:

npm run mcp:species

The server will start and listen on stdio. Press Ctrl+C to stop.

Claude Desktop Integration

Configuration

Add the MCP server to your Claude Desktop configuration:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Add this to the mcpServers section:

{
  "mcpServers": {
    "species-database": {
      "command": "npm",
      "args": ["run", "mcp:species"],
      "cwd": "/absolute/path/to/mulm",
      "env": {}
    }
  }
}

Important: Replace /absolute/path/to/mulm with the actual absolute path to this project. You can find this by running pwd in the mulm directory.

Using .mcp.json (Alternative)

This project includes a .mcp.json file that Claude Code can use automatically. However, for Claude Desktop, you'll need to manually add the configuration as shown above.

Restart Claude Desktop

After modifying the configuration:

  1. Quit Claude Desktop completely
  2. Relaunch Claude Desktop
  3. The MCP server should now be available

Available Resources

Resources are read-only endpoints for accessing species data.

List All Species

species://groups/list

Returns all species groups ordered by genus and species name.

Get Species by ID

species://groups/{group_id}

Returns detailed information about a specific species including all name variants (common names and scientific names separately).

Example: species://groups/123

Filter by Species Type

species://groups/by-type/{type}

Where {type} is one of: Fish, Plant, Invert, Coral

Examples:

  • species://groups/by-type/Fish
  • species://groups/by-type/Plant

Filter by Program Class

species://groups/by-class/{class}`

Where {class} is a program class like "Cichlids", "Livebearers", etc.

Example: species://groups/by-class/Cichlids

CARES Species

species://groups/cares

Returns all CARES conservation priority species.

Species Names (Split Schema)

# Common names
species://common-names/{common_name_id}          # Get specific common name
species://common-names/by-group/{group_id}       # Get all common names for a species

# Scientific names
species://scientific-names/{scientific_name_id}   # Get specific scientific name
species://scientific-names/by-group/{group_id}    # Get all scientific names for a species

Statistics

species://statistics

Returns aggregate statistics about the species database.

Available Tools

Tools are operations that can modify the species database.

Note: The database has been migrated to a split schema where common names and scientific names are managed independently. The MCP server implementation and examples below may still reference the old combined schema. See Species MCP Server Specification for the current tool signatures that work with the split schema (separate tools for add_common_name, add_scientific_name, etc.).

Core CRUD Operations

create_species_group

Creates a new species with canonical taxonomic name.

Parameters:

  • program_class (required): BAP program class
  • canonical_genus (required): Official genus name
  • canonical_species_name (required): Official species name
  • species_type (required): Fish, Plant, Invert, or Coral
  • base_points (optional): Points awarded for breeding
  • is_cares_species (optional): CARES conservation status

Example:

Create a new species:
- Genus: Astronotus
- Species: ocellatus
- Program class: Cichlids
- Species type: Fish
- Base points: 10

update_species_group

Updates metadata for an existing species group.

Parameters:

  • group_id (required): Species group ID
  • base_points (optional): Update point value
  • is_cares_species (optional): Update CARES status
  • external_references (optional): Array of reference URLs
  • image_links (optional): Array of image URLs

Example:

Update species group 123:
- Set base points to 15
- Add FishBase reference URL

delete_species_group

Deletes a species group and all its name variants (common names and scientific names) (DESTRUCTIVE).

Parameters:

  • group_id (required): Species group ID
  • force (optional): Force delete even if submissions exist

Example:

Delete species group 456 (preview first to check for submissions)

add_species_synonym

Adds a common/scientific name variant to a species.

Parameters:

  • group_id (required): Species group ID
  • common_name (required): Common name variant
  • scientific_name (required): Scientific name variant

Example:

Add synonym to species group 123:
- Common name: Oscar
- Scientific name: Astronotus ocellatus

update_species_synonym

Updates an existing name variant.

Parameters:

  • name_id (required): Name variant ID
  • common_name (optional): New common name
  • scientific_name (optional): New scientific name

delete_species_synonym

Removes a name variant.

Parameters:

  • name_id (required): Name variant ID
  • force (optional): Force delete even if last synonym

Advanced Operations

merge_species_groups

Merges two species groups (combines duplicates).

Parameters:

  • canonical_group_id (required): Species to keep
  • defunct_group_id (required): Species to merge and delete
  • preview (optional): Preview changes without executing

Example:

Merge species groups 123 and 124:
- Keep group 123 (Astronotus ocellatus)
- Merge and delete group 124 (duplicate entry)
- Preview first to see what will change

Workflow:

  1. First run with preview: true to see impact
  2. Review the preview data
  3. Run again with preview: false to execute

search_species

Search species with filters and sorting.

Parameters:

  • query (optional): Search text
  • species_type (optional): Filter by type
  • program_class (optional): Filter by class
  • has_base_points (optional): Filter by points presence
  • is_cares_species (optional): Filter CARES species
  • sort_by (optional): name, points, or class
  • limit (optional): Max results (default: 100)
  • offset (optional): Skip results (default: 0)

Examples:

Search for "cichlid" in all species

Find all Livebearers without base points assigned

Find all CARES species sorted by name

get_species_detail

Get comprehensive details for a single species.

Parameters:

  • group_id (required): Species group ID

Example:

Show full details for species group 123 including all synonyms

Metadata Management

set_base_points

Update point values for species (bulk or individual).

Parameters:

  • group_id (optional): Single species
  • group_ids (optional): Multiple species
  • species_type (optional): Filter by type
  • program_class (optional): Filter by class
  • base_points (required): Points value to set
  • preview (optional): Preview changes

Examples:

Set base points to 10 for species group 123

Set base points to 15 for all Cichlids (preview first)

Set base points to 5 for species groups [100, 101, 102]

toggle_cares_status

Mark species as CARES conservation priority.

Parameters:

  • group_id (required): Species group ID
  • is_cares_species (required): CARES status (true/false)

Example:

Mark species 123 as a CARES conservation species

Taxonomic Operations

update_canonical_name

Update the canonical genus/species name (for taxonomic revisions).

Parameters:

  • group_id (required): Species group ID
  • new_canonical_genus (optional): New genus name
  • new_canonical_species_name (optional): New species name
  • preserve_old_as_synonym (optional): Create synonym with old name (default: true)

Example:

Update species 123:
- Change genus from Astronotus to Cichla
- Preserve old name as a synonym

Example Usage in Claude Desktop

Once configured, you can ask Claude:

Basic Queries

"Show me all CARES species"

  • Uses: species://groups/cares resource

"List all fish species"

  • Uses: species://groups/by-type/Fish resource

"Get statistics about the species database"

  • Uses: species://statistics resource

Creating Species

"Create a new species: Astronotus ocellatus, program class Cichlids, species type Fish"

  • Uses: create_species_group tool

"Add a synonym 'Oscar' with scientific name 'Astronotus ocellatus' for species group 123"

  • Uses: add_species_synonym tool

Searching and Finding

"Search for all Cichlids without base points assigned"

  • Uses: search_species tool with filters:
    • program_class: "Cichlids"
    • has_base_points: false

"Find all species matching 'guppy'"

  • Uses: search_species tool with query: "guppy"

"Show me details for species group 123"

  • Uses: get_species_detail tool

Bulk Operations

"Set base points to 10 for all species in the Livebearers program class"

  • Uses: set_base_points tool with:
    • program_class: "Livebearers"
    • base_points: 10
    • preview: true (first run)

"Merge species groups 123 and 124, show me a preview first"

  • Uses: merge_species_groups tool with:
    • canonical_group_id: 123
    • defunct_group_id: 124
    • preview: true

Metadata Updates

"Mark species group 50 as a CARES conservation species"

  • Uses: toggle_cares_status tool with:
    • group_id: 50
    • is_cares_species: true

"Add FishBase reference URL to species 123"

  • Uses: update_species_group tool with:
    • group_id: 123
    • external_references: ["https://fishbase.org/..."]

Taxonomic Updates

"Update species 789: change genus from Astronotus to Cichla, keep old name as synonym"

  • Uses: update_canonical_name tool with:
    • group_id: 789
    • new_canonical_genus: "Cichla"
    • preserve_old_as_synonym: true

Troubleshooting

Server won't start

Problem: MCP server fails to start or crashes immediately

Solutions:

  • Check that src/config.json exists with correct database path
  • Verify database file exists at the specified location: ls -la src/database.db
  • Check that npm dependencies are installed: npm install
  • Try running directly to see error messages: npm run mcp:species

Tools returning errors

Problem: Tools return error messages when executed

Common Issues:

  • Foreign key constraint: Trying to add synonym to non-existent group_id
  • Duplicate constraint: Canonical name or synonym combination already exists
  • Not found: Trying to update/delete non-existent record
  • Database locked: Another process is using the database (close running dev server)

Solutions:

  • Read error message carefully - it will indicate the constraint violation
  • Use search tools to verify IDs exist before operations
  • Check that database migrations have run successfully

Claude Desktop not seeing the server

Problem: MCP tools don't appear in Claude Desktop

Solutions:

  • Verify claude_desktop_config.json has correct absolute path to project
  • Check path doesn't use ~ (expand to full /Users/username/...)
  • Restart Claude Desktop completely (quit and relaunch)
  • Check Claude Desktop logs for connection errors:
    • macOS: ~/Library/Logs/Claude/
  • Verify the npm script works: npm run mcp:species

Permission errors

Problem: Database permission denied or can't write

Solutions:

  • Check file permissions: ls -la src/database.db
  • Ensure database file is writable: chmod 644 src/database.db
  • Check parent directory permissions: ls -la src/

Best Practices

Always Preview First

For destructive operations (delete, merge) or bulk updates, always use preview mode first:

1. Run with preview: true
2. Review the changes that will be made
3. If satisfied, run again with preview: false (or omit)

Use Search Before Operations

Before updating or deleting:

  • Search to find the correct group_id or name_id
  • Verify you have the right species
  • Check for potential duplicates

Backup Before Bulk Operations

Before running operations that affect many records:

# Create backup
sqlite3 src/database.db ".backup backup-$(date +%Y%m%d).db"

Check for Submissions

Before deleting species:

  • Preview the delete to see submission count
  • Consider if those submissions should be preserved
  • Use merge instead if species is just a duplicate

Validate External Data

When adding URLs or references:

  • Verify URLs are accessible
  • Use authoritative sources (FishBase, SeriouslyFish)
  • Format consistently

Development

Adding New Tools

  1. Add tool definition to ListToolsRequestSchema handler in src/mcp/species-server.ts
  2. Add case to CallToolRequestSchema handler
  3. Implement handler function following existing patterns
  4. Update specification in wiki

Testing Changes

Test individual operations:

# Start server in test mode
npm run mcp:species

# Server will listen on stdin/stdout for MCP protocol messages

For integration testing, use Claude Desktop or an MCP client library.

Debugging

Enable verbose logging:

// In species-server.ts
logger.info('Debug info:', data);

Check logs in Claude Desktop or console output.

Security Notes

  • The MCP server has full database access
  • DESTRUCTIVE operations (delete, merge) should be used carefully
  • Always use preview: true for bulk operations first
  • No authentication/authorization - assumes trusted local use only
  • Consider adding audit logging for production use

Related Documentation