# NGSS MCP Server
[](https://www.npmjs.com/package/ngss-mcp)
[](https://opensource.org/licenses/ISC)
**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 [CHANGELOG.md](./CHANGELOG.md)**
## 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:
```bash
npm install ngss-mcp
```
Or with a specific version:
```bash
npm install ngss-mcp@1.0.0
```
Or install globally:
```bash
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**:
```json
{
"mcpServers": {
"ngss": {
"command": "npx",
"args": ["-y", "ngss-mcp"]
}
}
}
```
**Windows**:
```json
{
"mcpServers": {
"ngss": {
"command": "cmd",
"args": ["/c", "npx", "-y", "ngss-mcp"]
}
}
}
```
**WSL**:
```json
{
"mcpServers": {
"ngss": {
"command": "wsl",
"args": ["npx", "-y", "ngss-mcp"]
}
}
}
```
### Option C: Install via Smithery
Install directly from [Smithery](https://smithery.ai) to use with Claude Desktop or other MCP clients:
```bash
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:
```yaml
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:
```bash
docker-compose up -d
```
**Using Dockerfile**:
Create a `Dockerfile`:
```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:
```bash
docker build -t ngss-mcp .
docker run -i ngss-mcp
```
**Claude Desktop Configuration for Docker**:
```json
{
"mcpServers": {
"ngss": {
"command": "docker",
"args": ["run", "-i", "--rm", "ngss-mcp"]
}
}
}
```
### Install from Source
```bash
# 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
```
## Available Tools
### 1. `get_standard`
Retrieve a specific NGSS standard by its code identifier.
**Input**:
```json
{
"code": "MS-PS1-1"
}
```
**Output**:
```json
{
"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": []}
}
}
```
**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**:
```json
{
"domain": "Physical Science"
}
```
**Accepted Values**:
- `"Physical Science"` or `"physical-science"`
- `"Life Science"` or `"life-science"`
- `"Earth and Space Science"` or `"earth-space-science"`
**Output**:
```json
{
"domain": "Physical Science",
"count": 19,
"standards": [
{
"code": "MS-PS1-1",
"topic": "Structure and Properties of Matter",
"performance_expectation": "Develop models to describe the atomic composition..."
}
]
}
```
### 3. `get_3d_components`
Extract the three-dimensional learning components for a specific standard.
**Input**:
```json
{
"code": "MS-LS2-1"
}
```
**Output**:
```json
{
"code": "MS-LS2-1",
"framework_components": {
"Science and Engineering Practices (SEP)": {
"code": "SEP-1",
"name": "Analyze and interpret data to provide evidence...",
"description": "Science and Engineering Practices..."
},
"Disciplinary Core Ideas (DCI)": {
"code": "LS2.A",
"name": "Interdependent Relationships in Ecosystems",
"description": "Disciplinary Core Ideas..."
},
"Crosscutting Concepts (CCC)": {
"code": "CCC-1",
"name": "Patterns can be used to identify cause and effect...",
"description": "Crosscutting Concepts..."
}
}
}
```
**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**:
```json
{
"query": "ecosystem interactions",
"domain": "Life Science",
"limit": 5
}
```
**Parameters**:
- `query` (required): Search text (min 2 characters)
- `domain` (optional): Filter by domain
- `limit` (optional): Maximum results (default: 10, must be positive integer)
**Output**:
```json
{
"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"]
}
]
}
```
**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**:
```json
{
"practice": "Developing and Using Models",
"detail_level": "minimal"
}
```
**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**:
```json
{
"practice": "Developing and Using Models",
"total": 8,
"standards": [
{
"code": "MS-PS1-1",
"topic": "Structure and Properties of Matter",
"performance_expectation": "Develop models to describe..."
}
]
}
```
### 6. `search_by_crosscutting_concept`
Filter NGSS standards by Crosscutting Concepts (CCC).
**Input**:
```json
{
"concept": "Patterns",
"detail_level": "minimal"
}
```
**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**:
```json
{
"concept": "Patterns",
"total": 6,
"standards": [
{
"code": "MS-LS2-2",
"topic": "Ecosystems: Interactions, Energy, and Dynamics",
"performance_expectation": "Construct an explanation..."
}
]
}
```
### 7. `search_by_disciplinary_core_idea`
Filter NGSS standards by Disciplinary Core Ideas (DCI).
**Input**:
```json
{
"dci": "Definitions of Energy",
"detail_level": "minimal"
}
```
**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**:
```json
{
"dci": "Definitions of Energy",
"total": 4,
"standards": [
{
"code": "MS-PS3-1",
"topic": "Energy",
"performance_expectation": "Construct and interpret graphical displays..."
}
]
}
```
### 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**:
```json
{
"anchor_standard": "MS-PS1-1",
"unit_size": 5,
"detail_level": "minimal"
}
```
**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**:
```json
{
"anchor": {
"code": "MS-PS1-1",
"domain": "Physical Science",
"topic": "Structure and Properties of Matter"
},
"unit_size": 5,
"suggestions": [
{
"code": "MS-PS1-2",
"compatibility_score": 8,
"domain_match": true,
"sep_match": true,
"ccc_match": true,
"dci_match": true
}
]
}
```
**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`:
```json
{
"error": "Not Found",
"message": "Standard MS-PS1-99 does not exist in the database",
"code": "STANDARD_NOT_FOUND"
}
```
**Error Codes**:
- `STANDARD_NOT_FOUND`: Requested standard code doesn't exist
- `INTERNAL_ERROR`: Server error (database not initialized, parsing error, etc.)
## 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
```bash
# 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
```bash
# 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
## 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:
```javascript
// 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
