nsip

Sheep genetic evaluation CLI & MCP server -- search animals, compare EBVs, plan matings, rank flocks via the NSIP database.

Try it out: Clone zircote/nsip-example for a ready-to-use farm repository with MCP server configuration, sample workflows, and AI assistant instructions pre-configured.

Features

• Type-safe API client with comprehensive error handling
• Search functionality for animals by breed group, status, and other criteria
• Detailed animal information including lineage and progeny
• MCP (Model Context Protocol) integration for AI assistant compatibility
• CLI tool with multiple subcommands for easy interaction
• Async/await support with tokio runtime
• Full documentation with examples in all public APIs

Installation

Add this to your Cargo.toml:

[dependencies]
nsip = "0.4"

Or use cargo add:

cargo add nsip

Quick Start

use nsip::{NsipClient, SearchCriteria};

#[tokio::main]
async fn main() -> Result<(), nsip::Error> {
    // Create a new client
    let client = NsipClient::new();

    // List available breed groups
    let breed_groups = client.breed_groups().await?;
    println!("Available breed groups: {}", breed_groups.len());

    // Search for animals
    let criteria = SearchCriteria::new()
        .with_status("CURRENT");

    let results = client
        .search_animals(0, 15, Some(640), None, None, Some(&criteria))
        .await?;
    println!("Found {} animals", results.total_count);

    // Get details for a specific animal
    let animal = client.animal_details("LPN_ID_HERE").await?;
    println!("Animal: {}", animal.lpn_id);

    Ok(())
}

CLI Usage

The nsip CLI provides several commands for interacting with the NSIP Search API:

# Get database last-updated date
nsip date-updated

# List breed groups
nsip breed-groups

# List animal statuses
nsip statuses

# Get trait ranges for a breed
nsip trait-ranges 640

# Search for animals
nsip search --breed-id 640 --status CURRENT --page 0 --page-size 15

# Get animal details
nsip details <lpn-id>

# Get animal lineage
nsip lineage <lpn-id>

# Get animal progeny
nsip progeny <lpn-id>

# Get full profile (details + lineage + progeny)
nsip profile <lpn-id>

# Compare two or more animals side-by-side
nsip compare <lpn-id-1> <lpn-id-2>

# Generate shell completions
nsip completions bash

# Generate man pages
nsip man-pages ./man/

# Start MCP server mode
nsip mcp

API Overview

Client Methods

Data Types

MCP Integration

The library includes MCP (Model Context Protocol) support for integration with AI assistants:

use nsip::mcp::{serve_stdio, tool_sets::EnabledToolSets};

// Start the MCP server on stdio (all 13 tools enabled)
serve_stdio(EnabledToolSets::all()).await?;

The MCP protocol exposes the following 13 tools when running nsip mcp:

• search - Search for animals with filters for breed, gender, status, date range, and flock
• details - Get detailed EBV data, breed, contact info, and status for an animal
• lineage - Get pedigree / ancestry tree including parents and grandparents
• progeny - Get paginated list of offspring for an animal
• profile - Get complete profile (details + pedigree + offspring) in one call
• breed_groups - List all breed groups and individual breeds
• trait_ranges - Get min/max EBV trait ranges for a specific breed
• compare - Compare 2-5 animals side-by-side on their EBV traits
• rank - Rank animals within a breed by weighted EBV traits
• inbreeding_check - Calculate Wright's coefficient of inbreeding for a sire-dam pairing
• mating_recommendations - Find optimal mates ranked by trait complementarity and COI
• flock_summary - Summarize a flock's animals: count, gender breakdown, and average EBVs
• database_status - Get last-updated date and available animal statuses

Development

Prerequisites

• Rust 1.92+ (2024 edition)
• cargo-deny for supply chain security

Setup

# Clone the repository
git clone https://github.com/zircote/nsip.git
cd nsip

# Build
cargo build

# Run tests
cargo test

# Run linting
cargo clippy --all-targets --all-features

# Format code
cargo fmt

# Check supply chain security
cargo deny check

# Generate documentation
cargo doc --open

Project Structure

crates/
├── lib.rs           # Library entry point
├── main.rs          # Binary entry point
├── client.rs        # HTTP client for the NSIP Search API
├── models.rs        # Data models (SearchCriteria, AnimalDetails, etc.)
├── format.rs        # Human-readable ASCII table formatting
└── mcp/             # MCP server (13 tools, prompts, resources)

tests/
├── integration_test.rs
└── cli_test.rs      # CLI integration tests

Cargo.toml           # Project manifest
clippy.toml          # Clippy configuration
rustfmt.toml         # Formatter configuration
deny.toml            # cargo-deny configuration
CLAUDE.md            # AI assistant instructions
AGENTS.md            # AI coding agent instructions
.editorconfig        # Cross-editor defaults
.devcontainer/       # Codespaces / dev container config
.vscode/             # VS Code settings and extensions

Code Quality

This project maintains high code quality standards:

• Linting: clippy with pedantic and nursery lints
• Formatting: rustfmt with custom configuration
• Testing: Unit tests, integration tests, and property-based tests
• Documentation: All public APIs documented with examples
• Supply Chain: cargo-deny for dependency auditing
• CI/CD: GitHub Actions for automated testing

Running Checks

# Run all checks
cargo fmt -- --check && \
cargo clippy --all-targets --all-features -- -D warnings && \
cargo test && \
cargo doc --no-deps && \
cargo deny check

# Run with MIRI for undefined behavior detection
cargo +nightly miri test

CI/CD and Deployment

This template includes production-ready workflows:

Continuous Integration

• CI (.github/workflows/ci.yml) - Format, lint, test, docs, supply chain security, MSRV check, coverage
• Security Audit (.github/workflows/security-audit.yml) - Daily cargo-audit scans
• CodeQL Analysis (.github/workflows/codeql-analysis.yml) - SAST scanning on push/PR and weekly schedule
• Benchmark (.github/workflows/benchmark.yml) - Performance tracking with criterion
• ADR Validation (.github/workflows/adr-validation.yml) - Architectural decision records validation

Release and Deployment

• Release (.github/workflows/release.yml) - Automated GitHub releases with multi-platform binaries

  • Builds for: Linux (x86_64, ARM64), macOS (x86_64, ARM64), Windows (x86_64)
  • Automatic changelog generation
  • Binary artifacts uploaded to releases

• Changelog (.github/workflows/changelog.yml) - Automated CHANGELOG.md generation

  • Uses git-cliff with conventional commits
  • Follows Keep a Changelog format
  • Triggered on version tags

• Docker (.github/workflows/docker.yml) - Multi-platform container builds

  • Platforms: linux/amd64, linux/arm64
  • Distroless base image for security
  • Published to GitHub Container Registry (ghcr.io)
  • Tagged with version and 'latest'

• Publish (.github/workflows/publish.yml) - Automated crates.io publishing

  • Full pre-publish validation
  • Triggered on version tags
  • Requires CARGO_REGISTRY_TOKEN secret

Creating a Release

1. Update version in Cargo.toml
2. Create and push a version tag:

   git tag -a v0.4.0 -m "Release v0.4.0"
   git push origin v0.4.0
   

3. Workflows automatically:
   • Generate changelog
   • Build binaries for all platforms
   • Create GitHub release with artifacts
   • Build and push Docker images
   • Publish to crates.io

AI Coding Agent

• Copilot Setup (.github/workflows/copilot-setup-steps.yml) - Environment for GitHub Copilot coding agent
• Agent Instructions: AGENTS.md, .github/copilot-instructions.md, CLAUDE.md
• Path-Specific Instructions: .github/instructions/ for Rust code and test patterns
• Reusable Prompts: .github/prompts/ for common development tasks

Docker Usage

Pull and run the container:

# Pull latest
docker pull ghcr.io/zircote/nsip:latest

# Run specific version
docker pull ghcr.io/zircote/nsip:v0.4.0
docker run --rm ghcr.io/zircote/nsip:v0.4.0 --version

MSRV Policy

The Minimum Supported Rust Version (MSRV) is 1.92. Increasing the MSRV is considered a minor breaking change.

Contributing

See CONTRIBUTING.md for development setup, PR checklist, and coding standards.

Please also review:

• CODE_OF_CONDUCT.md - Community guidelines
• SECURITY.md - Vulnerability reporting
• GOVERNANCE.md - Decision-making process

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Rust Programming Language
• Cargo
• clippy