Nsip

nsip

[](https://github.com/zircote/nsip/actions/workflows/ci.yml) [](https://crates.io/crates/nsip) [](https://docs.rs/nsip) [](https://www.rust-lang.org/) [](https://github.com/zircote/nsip/blob/main/LICENSE) [](https://github.com/rust-lang/rust-clippy) [](https://github.com/EmbarkStudios/cargo-deny) [](https://github.com/gitleaks/gitleaks) [](https://docs.github.com/en/code-security/dependabot)

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.6"

Or use cargo add:

cargo add nsip

Quick Start

```rust,no_run use nsip::{NsipClient, SearchCriteria};

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

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

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

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

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

Ok(()) }

## CLI Usage

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

```bash
# 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 

# Get animal lineage
nsip lineage 

# Get animal progeny
nsip progeny 

# Get full profile (details + lineage + progeny)
nsip profile 

# Compare two or more animals side-by-side
nsip compare  

# Generate shell completions
nsip completions bash

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

# Start MCP server mode
nsip mcp

API Overview

Client Methods

| Method | Description | |--------|-------------| | date_last_updated() | Get database last-updated date | | breed_groups() | List available breed groups | | statuses() | List available animal statuses | | trait_ranges(breed_id) | Get trait ranges for a breed | | search_animals(page, page_size, breed_id, sorted_trait, reverse, criteria) | Search for animals | | animal_details(search_string) | Get animal details | | lineage(lpn_id) | Get animal lineage | | progeny(lpn_id, page, page_size) | Get animal progeny | | search_by_lpn(lpn_id) | Get full profile (concurrent) |

Data Types

| Type | Description | |------|-------------| | NsipClient | Main API client | | SearchCriteria | Search parameters with builder pattern | | AnimalDetails | Detailed animal record with traits and contact info | | AnimalProfile | Combined details + lineage + progeny | | Breed | A single breed within a breed group | | BreedGroup | Breed group with nested breeds | | ContactInfo | Owner / flock contact information | | DateLastUpdated | Response from the date-last-updated endpoint | | Lineage | Animal lineage/ancestry tree | | LineageAnimal | A single node in the pedigree tree | | Progeny | Paginated animal offspring | | ProgenyAnimal | A single offspring record | | SearchResults | Paginated search results | | Trait | A single EBV trait with value and accuracy | | TraitRange | Min/max range for a trait within a breed | | TraitRangeFilter | Min/max bounds for a trait filter | | Error | Error type for operations | | Result | Type alias for Result |

MCP Integration

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

```rust,ignore use nsip::mcp::{servestdio, toolsets::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](https://github.com/EmbarkStudios/cargo-deny) for supply chain security

### Setup

```bash
# 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

> Note: just check is the canonical local > equivalent of the CI pipeline (fmt + clippy + test + doc + deny + coverage). > Run just to list all available recipes. The raw cargo commands below are > the underlying equivalents.

# 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
• Secrets Scan (.github/workflows/secrets-scan.yml) - Gitleaks secret scanning (manual; enable push/PR triggers to automate)
• Container Scan (.github/workflows/container-scan.yml) - Trivy image vulnerability scanning

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
• Trusted Publishing (OIDC) — no registry token; the published crate is byte-verified and attested

Creating a Release

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

``bash git tag -a v0.6.0 -m "Release v0.6.0" git push origin v0.6.0 ``

1. 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.6.0
docker run --rm ghcr.io/zircote/nsip:v0.6.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](CONTRIBUTING.md) for development setup, PR checklist, and coding standards.

Please also review:

• [CODEOFCONDUCT.md](CODEOFCONDUCT.md) - Community guidelines
• [SECURITY.md](SECURITY.md) - Vulnerability reporting
• [GOVERNANCE.md](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zircote
• Source: zircote/nsip
• License: MIT

Install and usage instructions live in the source repository linked above.