NGSS MCP Server

Status: ✅ v1.2.2 Published to npm

⚠️ Middle School Standards Only This MCP server provides access to NGSS Middle School (MS) standards only. It does not include Elementary (K-5) or High School (HS) standards.

Model Context Protocol (MCP) server providing programmatic access to Next Generation Science Standards (NGSS) for middle school education.

What's New in v1.2.2

• Platform-Specific Configurations: Fixed MCP server configurations for macOS/Linux, Windows, and WSL

  • macOS/Linux: Direct npx command

  • Windows: cmd /c npx wrapper

  • WSL: wsl npx command

• Installation Options: Four clear installation methods (npm, MCP config, Smithery, Docker)

• Smithery Deployment: Fixed module field for TypeScript runtime support

• Docker Support: Comprehensive Docker installation documentation

See full release history in

Features

• 55 Middle School Standards: Complete coverage of NGSS middle school standards

• 3D Framework Support: Full Science & Engineering Practices (SEP), Disciplinary Core Ideas (DCI), and Crosscutting Concepts (CCC)

• Multi-Index Database: Optimized O(1) lookups by code, domain filtering, and relevance-scored search

• High-Performance Caching: LRU cache with TTL for 60x faster repeated queries

• Performance Metrics: Real-time query performance tracking and cache statistics

• Input Validation: Comprehensive validation and sanitization for all query parameters

• 8 Powerful Tools: Comprehensive API for standard lookup, search, filtering, and unit planning

• MCP Protocol: Native integration with Claude Desktop, Continue, and other MCP-compatible AI assistants

Database Statistics

• Total Standards: 55

• Physical Science: 19 standards

• Life Science: 21 standards

• Earth & Space Science: 15 standards

• Database Size: 80 KB (optimized)

• Index Sizes: 55 codes, 3 domains, 343 full-text keywords

Installation

Option A: Install from npm

Install via npm:

Or with a specific version:

Or install globally:

Prerequisites:

• Node.js 18+ or Bun runtime

• npm or bun package manager

Option B: Configure as MCP Server

Add to your MCP configuration file:

macOS/Linux:

Windows:

WSL:

Option C: Install via Smithery

Install directly from Smithery to use with Claude Desktop or other MCP clients:

This will automatically configure the server in your Claude Desktop settings.

Option D: Install via Docker

Run the MCP server in a Docker container for isolated, reproducible deployments.

Using Docker Compose (recommended):

Create a docker-compose.yml file:

Then run:

Using Dockerfile:

Create a Dockerfile:

Build and run:

Claude Desktop Configuration for Docker:

Install from Source

Available Tools

1. get_standard

Retrieve a specific NGSS standard by its code identifier.

Input:

Output:

Valid Code Format: MS-(PS|LS|ESS)\d+-\d+

• MS-PS1-1 through MS-PS4-3 (Physical Science)

• MS-LS1-1 through MS-LS4-6 (Life Science)

• MS-ESS1-1 through MS-ESS3-5 (Earth & Space Science)

2. search_by_domain

Find all NGSS standards in a specific science domain.

Input:

Accepted Values:

• "Physical Science" or "physical-science"

• "Life Science" or "life-science"

• "Earth and Space Science" or "earth-space-science"

Output:

3. get_3d_components

Extract the three-dimensional learning components for a specific standard.

Input:

Output:

3D Framework Components:

• SEP: Science & Engineering Practices - What scientists and engineers do

• DCI: Disciplinary Core Ideas - Key concepts to understand

• CCC: Crosscutting Concepts - Themes that connect across disciplines

4. search_standards

Perform full-text search across all NGSS standard content.

Input:

Parameters:

• query (required): Search text (min 2 characters)

• domain (optional): Filter by domain

• limit (optional): Maximum results (default: 10, must be positive integer)

Output:

Search Scope:

• Performance expectations

• Topics

• Keywords

• All 3D components (SEP, DCI, CCC)

5. search_by_practice

Filter NGSS standards by Science & Engineering Practices (SEP).

Input:

Valid SEP Values (10 options):

1. "Asking Questions and Defining Problems"

2. "Developing and Using Models"

3. "Planning and Carrying Out Investigations"

4. "Analyzing and Interpreting Data"

5. "Using Mathematics and Computational Thinking"

6. "Constructing Explanations and Designing Solutions"

7. "Engaging in Argument from Evidence"

8. "Obtaining, Evaluating, and Communicating Information"

9. "Define the Criteria and Constraints of a Design Problem"

10. "Unknown"

Output:

6. search_by_crosscutting_concept

Filter NGSS standards by Crosscutting Concepts (CCC).

Input:

Valid CCC Values (8 options):

1. "Patterns"

2. "Cause and Effect"

3. "Scale, Proportion, and Quantity"

4. "Systems and System Models"

5. "Energy and Matter"

6. "Structure and Function"

7. "Stability and Change"

8. "Unknown"

Output:

7. search_by_disciplinary_core_idea

Filter NGSS standards by Disciplinary Core Ideas (DCI).

Input:

Valid DCI Values (14 options):

1. "Definitions of Energy"

2. "Earth's Materials and Systems"

3. "Evidence of Common Ancestry and Diversity"

4. "Forces and Motion"

5. "Growth and Development of Organisms"

6. "Interdependent Relationships in Ecosystems"

7. "Natural Hazards"

8. "Organization for Matter and Energy Flow in Organisms"

9. "Structure and Function"

10. "Structure and Properties of Matter"

11. "The History of Planet Earth"

12. "The Universe and Its Stars"

13. "Wave Properties"

14. "Weather and Climate"

Output:

8. get_3d_components

(Renumbered from Tool 3 - functionality unchanged)

9. get_unit_suggestions

Get intelligent curriculum unit suggestions based on an anchor standard, using binary compatibility scoring across domain, SEP, CCC, and DCI dimensions.

Input:

Parameters:

• anchor_standard (required): Standard code to base suggestions on

• unit_size (optional): Total standards in unit including anchor (default: 5, range: 2-8)

• detail_level (optional): Response detail level (minimal/summary/full)

Output:

Compatibility Scoring (Binary Matching per ADR-001):

• Domain Match: +3 points (same science domain as anchor)

• SEP Match: +2 points (same Science & Engineering Practice)

• CCC Match: +2 points (same Crosscutting Concept)

• DCI Match: +1 point (same Disciplinary Core Idea)

• Maximum Score: 8 points (perfect alignment across all dimensions)

Use Cases:

• Curriculum planning: Build thematically coherent units

• Cross-domain exploration: Discover connections between science domains

• Differentiation: Find standards with varying complexity levels

• Unit sequencing: Identify logical progressions of concepts

Data Model (ADR-001)

The NGSS-MCP server uses a single-object data model for 3D framework components:

• Each standard has ONE sep object: standard.sep.name

• Each standard has ONE ccc object: standard.ccc.name

• Each standard has ONE dci object: standard.dci.name

This ensures consistent data structure and simplifies filtering operations. See docs/adr/001-use-single-object-3d-framework-structure.md for details.

Error Handling

All tools return structured error responses with isError: true:

Error Codes:

• STANDARD_NOT_FOUND: Requested standard code doesn't exist

• INTERNAL_ERROR: Server error (database not initialized, parsing error, etc.)

Development

Project Structure

Build Commands

Testing

Test Coverage:

• ✅ All 8 MCP tools (comprehensive integration tests)

• ✅ Data validation (ADR-001 compliance: SEP/CCC/DCI single objects)

• ✅ Backward compatibility (Tools 1-4 unchanged from v1.0.1)

• ✅ Tool regression (Tools 5, 6, 8 smoke tests)

• ✅ Input validation and error handling

• ✅ Cache effectiveness (60x speedup verification)

• ✅ Performance stress testing (100+ queries)

• ✅ Edge cases and boundary conditions

• ✅ 87 total test cases, 100% pass rate, 100% code coverage

Architecture

Database Module (database.ts):

• Code Index: Map<string, Standard> - O(1) lookups by standard code

• Domain Index: Map<string, Standard[]> - Grouped by science domain

• Full-Text Index: Map<string, Set<string>> - Comprehensive search

• Query Cache: LRU cache with TTL for search result caching

• Performance Metrics: Real-time query statistics and timing

• Input Validation: Integrated validation for all query parameters

Query Cache Module (query-cache.ts):

• QueryCache Class: Generic LRU cache with TTL expiration

• Cache Metrics: Hits, misses, evictions, hit rate tracking

• LRU Eviction: Automatic removal of least recently used entries

• TTL Management: Automatic expiration of stale entries

• Detailed Statistics: Top entries and age tracking

• Cache Key Generation: Deterministic key creation from parameters

Query Validation Module (query-validation.ts):

• QueryValidator Class: Static validation methods for all input types

• Format Validation: Standard code, domain, query string checks

• Range Validation: Limit parameter bounds checking

• Security Validation: Injection pattern detection and sanitization

• Sanitization: Text cleaning and normalization

• Error Messages: Clear, actionable validation error messages

MCP Server (index.ts):

• High-level McpServer class from @modelcontextprotocol/sdk

• Zod schema validation for all tool inputs

• Graceful shutdown handling (SIGINT/SIGTERM)

• StdioServerTransport for MCP protocol communication

• Error handling with structured responses

Data Quality

• ✅ 100% 3D Completeness: All standards include SEP, DCI, and CCC components

• ✅ Valid Standard Codes: All codes match pattern MS-(PS|LS|ESS)\d+-\d+

• ✅ Clean Text: No embedded newlines or control characters

• ✅ Complete Topics: Full topic names (e.g., "Structure and Properties of Matter")

Source Data

• PDF Source: Middle School By Topic NGSS.pdf (3.6 MB)

• Extraction Method: Pattern-based extraction via pdf-extraction MCP server

• Generated: October 15, 2025

• Validation: Schema-validated with Zod, 100% completeness verified

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript strict mode compliance

• Zod schema validation for new inputs

• Test coverage for new features

• Documentation updates for API changes

Support

For issues, questions, or feature requests, please open an issue on the repository.

Performance

Query Caching:

• LRU Cache: 100-entry capacity with intelligent eviction

• TTL Expiration: 5-minute Time-To-Live for cached results

• Cache Hit Rate: 79-90% in typical usage patterns

• Speed Improvement: 60x faster average for cached queries

  • searchStandards: 64x speedup (0.16ms → 0.002ms)

  • Domain-filtered search: 10x speedup (0.04ms → 0.004ms)

Query Performance:

• Code lookups: <0.01ms (O(1))

• Domain searches: <0.05ms

• Keyword searches: 0.01-0.20ms (first query)

• Cached queries: 0.002-0.005ms

• Stress test: 100 lookups in 0.04ms (0.0004ms per lookup)

Performance Metrics API:

• Real-time query statistics via getQueryMetrics()

• Cache statistics via getCacheStats()

• Per-method performance tracking

• Hit rate and eviction monitoring

Input Validation

All query methods include comprehensive validation:

Validation Rules:

• Standard Codes: Must match format MS-(PS|LS|ESS)\d+-\d+

• Domains: Must be one of: Physical Science, Life Science, Earth and Space Science

• Query Strings: 1-500 characters, sanitized for security

• Limit Parameters: 1-100 (positive integers only)

• Injection Protection: Blocks suspicious patterns and control characters

Validation Errors: Throw descriptive errors with clear messages:

Benefits:

• Prevents malformed requests

• Clear error messaging

• Security hardening against injection

• Input sanitization for all text fields