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）标准。

💡 使用建议

在使用过程中，可根据不同的需求选择合适的工具进行标准查询和过滤。同时，利用缓存功能可以显著提高查询性能。