Ngss MCP

🚀 NGSS MCP Server

NGSS MCP Server 是一個模型上下文協議（MCP）服務器，可對中學教育的下一代科學標準（NGSS）進行編程訪問，為教育工作者和開發者提供了便捷的工具來查詢和使用相關標準。

🚀 快速開始

本 MCP 服務器僅提供對 NGSS 中學（MS）標準 的訪問，不包括小學（K - 5）或高中（HS）標準。

安裝

你可以通過以下多種方式安裝 NGSS MCP Server：

• 從 npm 安裝：

npm install ngss-mcp

或者指定版本安裝：

npm install ngss-mcp@1.0.0

也可以全局安裝：

npm install -g ngss-mcp

前提條件：

• Node.js 18+ 或 Bun 運行時

• npm 或 bun 包管理器

• 配置為 MCP 服務器： 根據不同的操作系統，將以下配置添加到你的 MCP 配置文件中： 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"]
    }
  }
}

• 通過 Smithery 安裝：

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

這將自動在你的 Claude Desktop 設置中配置服務器。

• 通過 Docker 安裝： 可以使用 Docker Compose 或 Dockerfile 進行安裝。 使用 Docker Compose： 創建 docker-compose.yml 文件：

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:

然後運行：

docker-compose up -d

使用 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"]

構建並運行：

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

Claude Desktop 對 Docker 的配置：

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

• 從源代碼安裝：

# 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

✨ 主要特性

• 覆蓋 55 條中學標準：全面覆蓋 NGSS 中學標準。
• 支持 3D 框架：涵蓋完整的科學與工程實踐（SEP）、學科核心概念（DCI）和跨學科概念（CCC）。
• 多索引數據庫：通過代碼進行 O(1) 查找、按領域過濾和相關性評分搜索，優化查詢性能。
• 高性能緩存：採用 LRU 緩存和 TTL，使重複查詢速度提高 60 倍。
• 性能指標：即時跟蹤查詢性能和緩存統計信息。
• 輸入驗證：對所有查詢參數進行全面驗證和清理。
• 8 個強大工具：提供用於標準查找、搜索、過濾和單元規劃的全面 API。
• MCP 協議：與 Claude Desktop、Continue 等 MCP 兼容的 AI 助手原生集成。

📊 數據庫統計信息

💻 使用示例

基礎用法

以下是使用 get_standard 工具檢索特定 NGSS 標準的示例：

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

輸出：

{
  "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": []}
  }
}

高級用法

以下是使用 search_standards 工具進行全文搜索的示例：

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

輸出：

{
  "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"]
    }
  ]
}

📚 詳細文檔

可用工具

1. get_standard

通過代碼標識符檢索特定的 NGSS 標準。

2. search_by_domain

查找特定科學領域的所有 NGSS 標準。

3. get_3d_components

提取特定標準的三維學習組件。

4. search_standards

對所有 NGSS 標準內容進行全文搜索。

5. search_by_practice

按科學與工程實踐（SEP）過濾 NGSS 標準。

6. search_by_crosscutting_concept

按跨學科概念（CCC）過濾 NGSS 標準。

7. search_by_disciplinary_core_idea

按學科核心概念（DCI）過濾 NGSS 標準。

8. get_3d_components

功能與工具 3 相同。

9. get_unit_suggestions

根據錨定標準獲取智能課程單元建議，使用跨領域、SEP、CCC 和 DCI 維度的二進制兼容性評分。

數據模型（ADR - 001）

NGSS - MCP 服務器對 3D 框架組件使用單對象數據模型，確保數據結構一致並簡化過濾操作。詳情見 docs/adr/001 - use - single - object - 3d - framework - structure.md。

錯誤處理

所有工具返回結構化錯誤響應，isError 為 true。

{
  "error": "Not Found",
  "message": "Standard MS-PS1-99 does not exist in the database",
  "code": "STANDARD_NOT_FOUND"
}

錯誤代碼：

• STANDARD_NOT_FOUND：請求的標準代碼不存在。
• INTERNAL_ERROR：服務器錯誤（數據庫未初始化、解析錯誤等）。

開發

項目結構

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

構建命令

# 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

測試

# 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

測試覆蓋率：

• ✅ 所有 8 個 MCP 工具（全面集成測試）
• ✅ 數據驗證（符合 ADR - 001：SEP/CCC/DCI 單對象）
• ✅ 向後兼容性（工具 1 - 4 與 v1.0.1 相同）
• ✅ 工具迴歸測試（工具 5、6、8 冒煙測試）
• ✅ 輸入驗證和錯誤處理
• ✅ 緩存有效性（驗證速度提高 60 倍）
• ✅ 性能壓力測試（100 + 次查詢）
• ✅ 邊緣情況和邊界條件
• ✅ 共 87 個測試用例，通過率 100%，代碼覆蓋率 100%

架構

• 數據庫模塊 (database.ts)：包含代碼索引、領域索引、全文索引、查詢緩存、性能指標和輸入驗證。
• 查詢緩存模塊 (query-cache.ts)：提供通用的 LRU 緩存，具有 TTL 過期、緩存指標、LRU 驅逐、TTL 管理、詳細統計和緩存鍵生成功能。
• 查詢驗證模塊 (query-validation.ts)：對所有輸入類型進行靜態驗證，包括格式驗證、範圍驗證、安全驗證、清理和錯誤消息。
• MCP 服務器 (index.ts)：使用 @modelcontextprotocol/sdk 中的高級 McpServer 類，對所有工具輸入進行 Zod 模式驗證，處理優雅關機、通過 StdioServerTransport 進行 MCP 協議通信並處理錯誤。

🔧 技術細節

數據質量

• 100% 3D 完整性：所有標準都包含 SEP、DCI 和 CCC 組件。
• 有效標準代碼：所有代碼符合 MS-(PS|LS|ESS)\d+-\d+ 格式。
• 乾淨文本：無嵌入式換行符或控制字符。
• 完整主題：完整的主題名稱（如“Structure and Properties of Matter”）。

源數據

• PDF 源：Middle School By Topic NGSS.pdf（3.6 MB）
• 提取方法：通過基於模式的提取，使用 pdf - extraction MCP 服務器。
• 生成時間：2025 年 10 月 15 日
• 驗證：使用 Zod 進行模式驗證，驗證完整性為 100%。

性能

• 查詢緩存：100 條記錄容量的 LRU 緩存，TTL 為 5 分鐘，典型使用模式下緩存命中率為 79 - 90%，緩存查詢平均速度提高 60 倍。
• 查詢性能：代碼查找 <0.01ms（O(1)），領域搜索 <0.05ms，關鍵詞搜索 0.01 - 0.20ms（首次查詢），緩存查詢 0.002 - 0.005ms，壓力測試 100 次查找用時 0.04ms（每次查找 0.0004ms）。
• 性能指標 API：通過 getQueryMetrics() 獲取即時查詢統計信息，通過 getCacheStats() 獲取緩存統計信息，跟蹤每個方法的性能、命中率和驅逐情況。

輸入驗證

所有查詢方法都包含全面驗證，驗證規則包括標準代碼格式、領域範圍、查詢字符串長度、限制參數範圍和注入保護。驗證錯誤會拋出具有清晰消息的描述性錯誤。

📄 許可證

本項目採用 MIT 許可證。

⚙️ 貢獻

歡迎貢獻代碼！請確保：

• 符合 TypeScript 嚴格模式。
• 對新輸入使用 Zod 模式驗證。
• 為新功能提供測試覆蓋。
• 對 API 更改更新文檔。

🛠️ 支持

如有問題、疑問或功能請求，請在倉庫中創建 issue。

⚠️ 重要提示

本 MCP 服務器僅提供對 NGSS 中學（MS）標準的訪問，不包括小學（K - 5）或高中（HS）標準。

💡 使用建議

在使用過程中，可根據不同的需求選擇合適的工具進行標準查詢和過濾。同時，利用緩存功能可以顯著提高查詢性能。