Ngss MCP

🚀 NGSS MCP Server

The MCP server provides programmatic access to Next Generation Science Standards (NGSS) for middle school education.

🚀 Quick Start

The NGSS MCP Server is a Model Context Protocol (MCP) server that offers programmatic access to Next Generation Science Standards (NGSS) for middle - school education. It currently has version v1.2.2 published to npm.

⚠️ Important Note

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

✨ 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 Cross - cutting 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.

📦 Installation

Option A: Install from npm

Install via npm:

npm install ngss-mcp

Or with a specific version:

npm install ngss-mcp@1.0.0

Or install globally:

npm install -g ngss-mcp

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:

{
  "mcpServers": {
    "ngss": {
      "command": "npx",
      "args": ["-y", "ngss-mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "ngss": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "ngss-mcp"]
    }
  }
}

WSL:

{
  "mcpServers": {
    "ngss": {
      "command": "wsl",
      "args": ["npx", "-y", "ngss-mcp"]
    }
  }
}

Option C: Install via Smithery

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

npx -y @smithery/cli install @sallvainian/ngss-mcp --client claude

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:

version: '3.8'
services:
  ngss-mcp:
    image: node:18-alpine
    working_dir: /app
    command: npx -y ngss-mcp
    stdin_open: true
    tty: true
    volumes:
      - ngss-data:/root/.npm
volumes:
  ngss-data:

Then run:

docker-compose up -d

Using Dockerfile:

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Install the MCP server globally
RUN npm install -g ngss-mcp

# Expose stdio for MCP protocol
CMD ["ngss-mcp"]

Build and run:

docker build -t ngss-mcp .
docker run -i ngss-mcp

Claude Desktop Configuration for Docker:

{
  "mcpServers": {
    "ngss": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ngss-mcp"]
    }
  }
}

Install from Source

# Clone repository
git clone <repository-url>
cd NGSS-MCP

# Install dependencies
bun install  # or npm install

# Build TypeScript
bun run build  # or npm run build

💻 Usage Examples

Basic Usage

1. get_standard

Retrieve a specific NGSS standard by its code identifier.

Input:

{
  "code": "MS-PS1-1"
}

Output:

{
  "code": "MS-PS1-1",
  "grade_level": "MS",
  "domain": "Physical Science",
  "topic": "Structure and Properties of Matter",
  "performance_expectation": "Develop models to describe the atomic composition of simple molecules and extended structures.",
  "sep": {
    "code": "SEP-1",
    "name": "Develop a model to predict and/or describe phenomena.",
    "description": "Science and Engineering Practices Developing and Using Models..."
  },
  "dci": {
    "code": "PS1.A",
    "name": "Structure and Properties of Matter",
    "description": "Disciplinary Core Ideas..."
  },
  "ccc": {
    "code": "CCC-1",
    "name": "Patterns can be used to identify cause and effect relationships.",
    "description": "Crosscutting Concepts..."
  },
  "keywords": ["develop", "model", "describe", "atomic", "composition", "molecules"],
  "lesson_scope": {
    "key_concepts": [...],
    "prerequisite_knowledge": [],
    "common_misconceptions": [],
    "depth_boundaries": {"include": [], "exclude": []}
  }
}

Advanced Usage

2. search_standards

Perform full - text search across all NGSS standard content.

Input:

{
  "query": "ecosystem interactions",
  "domain": "Life Science",
  "limit": 5
}

Output:

{
  "query": "ecosystem interactions",
  "domain": "Life Science",
  "totalMatches": 3,
  "results": [
    {
      "code": "MS-LS2-2",
      "domain": "Life Science",
      "topic": "Ecosystems: Interactions, Energy, and Dynamics",
      "relevance": 0.89,
      "performance_expectation": "Construct an explanation that predicts patterns...",
      "keywords": ["construct", "explanation", "predicts", "patterns", "interactions"]
    }
  ]
}

📚 Documentation

Available Tools

1. get_standard

Retrieve a specific NGSS standard by its code identifier. The valid code format is MS-(PS|LS|ESS)\d+-\d+, including ranges for Physical Science, Life Science, and Earth & Space Science.

2. search_by_domain

Find all NGSS standards in a specific science domain. Accepted values are "Physical Science" or "physical - science", "Life Science" or "life - science", "Earth and Space Science" or "earth - space - science".

3. get_3d_components

Extract the three - dimensional learning components for a specific standard. The 3D framework components include SEP (Science & Engineering Practices), DCI (Disciplinary Core Ideas), and CCC (Cross - cutting Concepts).

4. search_standards

Perform full - text search across all NGSS standard content. Parameters include query (required), domain (optional), and limit (optional).

5. search_by_practice

Filter NGSS standards by Science & Engineering Practices (SEP). There are 10 valid SEP values.

6. search_by_crosscutting_concept

Filter NGSS standards by Cross - cutting Concepts (CCC). There are 8 valid CCC values.

7. search_by_disciplinary_core_idea

Filter NGSS standards by Disciplinary Core Ideas (DCI). There are 14 valid DCI values.

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. Parameters include anchor_standard (required), unit_size (optional), and detail_level (optional).

Data Model (ADR - 001)

The NGSS - MCP server uses a single - object data model for 3D framework components. Each standard has one sep, ccc, and dci object, which 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 include STANDARD_NOT_FOUND and INTERNAL_ERROR.

Development

Project Structure

NGSS-MCP/
├── src/
│   ├── server/
│   │   ├── index.ts              # MCP server with 8 tools
│   │   ├── database.ts           # Multi-index database with caching
│   │   ├── query-cache.ts        # LRU cache with TTL and metrics
│   │   └── query-validation.ts   # Input validation and sanitization
│   │   └── integration.test.ts   # 87 comprehensive tests (100% coverage)
│   ├── constants/
│   │   └── enum-values.ts        # SEP and CCC enum values
│   ├── extraction/               # PDF extraction utilities
│   └── types/
│       └── ngss.ts               # Type definitions
├── scripts/
│   ├── test-query-interface.ts   # Comprehensive test suite
│   └── test-cache-performance.ts # Cache effectiveness validation
├── data/
│   └── ngss-ms-standards.json    # Extracted standards database
├── dist/                         # Compiled JavaScript
├── docs/
│   ├── adr/                      # Architecture Decision Records
│   │   └── 001-use-single-object-3d-framework-structure.md
│   └── Middle School By Topic NGSS.pdf

Build Commands

# Compile TypeScript
bun run build

# Development mode (watch)
bun run dev

# Extract standards from PDF (requires pdf-extraction MCP)
bun run build-data

# Test PDF extraction
bun test

Testing

# Run comprehensive query interface tests (32 tests)
bun run scripts/test-query-interface.ts

# Test cache performance and effectiveness
bun run scripts/test-cache-performance.ts

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

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:

// Invalid standard code
Error: Invalid standard code format. Expected: MS-{PS|LS|ESS}{number}-{number}

// Invalid domain
Error: Invalid domain. Must be one of: Physical Science, Life Science, Earth and Space Science

// Invalid limit
Error: Limit cannot exceed 100

// Empty query
Error: Query must be at least 1 character

Benefits

• Prevents malformed requests.
• Clear error messaging.
• Security hardening against injection.
• Input sanitization for all text fields.

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are 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.