NGSS MCP

NGSS MCP 服务器

状态： ✅ v1.2.2 已发布到npm

⚠️ 仅限中学标准 这个MCP服务器提供访问权限至 仅包含NGSS中学（MS）标准它不包括小学（K-5）或高中（HS）的标准。

提供面向中学教育的下一代科学教育标准（NGSS）程序化访问的模型上下文协议（MCP）服务器。

v1.2.2版的新功能有哪些

• 平台特定配置为 macOS/Linux、Windows 和 WSL 固定了 MCP 服务器配置

- macOS/Linux：直接 npx 命令 - Windows： cmd /c npx 包装器；外壳；封装类 - WSL：Windows Subsystem for Linux（Windows上的Linux子系统） wsl npx 命令

• 安装选项四种明确的安装方法（npm、MCP配置、Smithery、Docker）
• Smithery 部署为TypeScript运行时支持固定模块字段
• Docker 支持全面的Docker安装指南

查看完整的发布历史记录，请见 CHANGELOG.md 翻译为中文是：“变更日志文件（Markdown 格式）”

特点/特性

• 55项中学标准全面覆盖NGSS（美国国家科学教育标准）中学标准
• 3D框架支持完整的科学与工程实践（SEP）、学科核心概念（DCI）和跨学科概念（CCC）
• 多索引数据库通过代码、域过滤和相关性评分搜索优化了O(1)查找速度
• 高性能缓存带有TTL（生存时间）的LRU缓存，使重复查询速度提升60倍
• 性能指标实时查询性能跟踪和缓存统计
• 输入验证对所有查询参数进行全面验证和清理
• 8款强大工具标准查询、搜索、过滤和单位规划的综合API
• MCP协议与Claude Desktop、Continue及其他MCP兼容的AI助手实现原生集成

数据库统计信息

• 总标准55
• 自然科学（或物理科学）19项标准
• 生命科学21项标准
• 地球与空间科学15项标准
• 数据库大小80 KB（优化后）
• 索引大小55个代码，3个领域，343个全文关键词

安装

选项A：从npm安装

通过npm安装：

npm install ngss-mcp

或者，使用特定版本：

npm install ngss-mcp@1.0.0

或者全局安装：

npm install -g ngss-mcp

先决条件：

• Node.js 18+ 或 Bun 运行时
• npm 或 bun 包管理器

选项B：配置为MCP服务器

在您的MCP配置文件中添加：

macOS/Linux（注：这两个词分别是苹果公司的操作系统macOS和开源操作系统Linux的名称，无需翻译，直接保留原样）:

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

Windows：

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

WSL（Windows Subsystem for Linux，Windows上的Linux子系统）:

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

选项C：通过Smithery进行安装

直接从（某处）安装 Smithery 翻译成中文是“铁匠铺”或“锻造工坊” 用于Claude Desktop或其他MCP客户端：

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

这将自动在您的Claude桌面设置中配置服务器。

选项D：通过Docker安装

在Docker容器中运行MCP服务器，以实现隔离且可重复的部署。

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

Docker的Claude桌面配置:

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

从源代码安装

# Clone repository
git clone 
cd NGSS-MCP

# Install dependencies
bun install  # or npm install

# Build TypeScript
bun run build  # or npm run build

可用工具

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

有效的代码格式： MS-(PS|LS|ESS)\d+-\d+

• MS-PS1-1 通过 MS-PS4-3 （物理科学）
• MS-LS1-1 通过 MS-LS4-6 （生命科学）
• MS-ESS1-1 通过 MS-ESS3-5 (地球与空间科学)

2. search_by_domain

查找特定科学领域内的所有NGSS标准。

输入:

{
  "domain": "Physical Science"
}

接受值:

• "Physical Science" 或者 "physical-science"
• "Life Science" 或者 "life-science"
• "Earth and Space Science" 或者 "earth-space-science"

输出：

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

为特定标准提取三维学习要素。

输入：

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

输出：

{
  "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框架组件:

• SEP（特殊教育需求）科学与工程实践 - *科学家和工程师所做的工作*
• DCI（Direct Current Injection）直流注入核心学科理念 - *需要理解的关键概念*
• CCC（中国强制性产品认证）跨学科概念 - *跨学科相联系的主题*

4. search_standards

在所有NGSS标准内容中进行全文搜索。

输入:

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

参数：

• query （必填）：搜索文本（至少2个字符）
• domain （可选）：按域名筛选
• limit （可选）：最大结果数（默认：10，必须为正整数）

输出:

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

搜索范围:

• 绩效期望
• 主题/话题
• 关键词
• 所有3D组件（SEP、DCI、CCC）

5. search_by_practice

按科学与工程实践（SEP）筛选NGSS标准。

输入：

{
  "practice": "Developing and Using Models",
  "detail_level": "minimal"
}

有效的SEP值 （10个选项）：

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"

输出：

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

按跨学科概念（CCC）过滤NGSS标准。

输入:

{
  "concept": "Patterns",
  "detail_level": "minimal"
}

有效的CCC值 （8个选项）：

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"

输出:

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

按学科核心概念（DCI）筛选NGSS标准。

输入:

{
  "dci": "Definitions of Energy",
  "detail_level": "minimal"
}

有效的DCI值 (14个选项)：

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"

输出：

{
  "dci": "Definitions of Energy",
  "total": 4,
  "standards": [
    {
      "code": "MS-PS3-1",
      "topic": "Energy",
      "performance_expectation": "Construct and interpret graphical displays..."
    }
  ]
}

8. get_3d_components

*（从工具3重新编号 - 功能保持不变）*

9. get_unit_suggestions

基于锚定标准，利用跨领域、科学与工程实践（SEP）、跨学科概念（CCC）和跨概念维度（DCI）的二元兼容性评分，获取智能的课程单元建议。

输入:

{
  "anchor_standard": "MS-PS1-1",
  "unit_size": 5,
  "detail_level": "minimal"
}

参数:

• anchor_standard （必填）：作为建议基础的标准代码
• unit_size （可选）：单元中包括锚点在内的总标准数（默认：5，范围：2-8）
• detail_level （可选）：响应详细程度（最小/摘要/完整）

输出:

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

兼容性评分 （根据ADR-001进行二进制匹配）

• 域名匹配+3分（与锚点属于同一科学领域）
• SEP 比赛+2分（同一科学与工程实践）
• CCC比赛+2分（同一跨学科概念）
• DCI比赛+1分（同一学科核心理念）
• 最高分8分（在所有维度上均完美对齐）

用例：

• 课程规划：构建主题连贯的单元
• 跨领域探索：发现科学领域之间的联系
• 差异化：寻找不同复杂程度的标准
• 单元排序：确定概念的逻辑顺序

数据模型（ADR-001）

NGSS-MCP服务器使用一个 单对象数据模型 对于3D框架组件：

• 每个标准都有一个 sep 对象： standard.sep.name
• 每个标准都有一个 ccc 对象： standard.ccc.name
• 每个标准都有一个 dci 对象： standard.dci.name

这确保了数据结构的一致性，并简化了过滤操作。请参阅 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):

• 代码索引： Map - 标准代码中的O(1)查找
• 域名索引: Map - 按科学领域分组
• 全文索引: Map> - 全面搜索
• 查询缓存带有TTL的LRU缓存，用于搜索结果缓存
• 性能指标实时查询统计与计时
• 输入验证对所有查询参数进行综合验证

查询缓存模块 (query-cache.ts):

• QueryCache 类具有TTL过期时间的通用LRU缓存
• 缓存指标命中、未命中、驱逐、命中率追踪
• LRU（最近最少使用）驱逐（或淘汰）自动移除最近最少使用的条目
• TTL管理自动过期陈旧条目
• 详细统计顶尖条目与年龄追踪
• 缓存密钥生成从参数中确定性地生成密钥

查询验证模块 (query-validation.ts):

• QueryValidator 类所有输入类型的静态验证方法
• 格式验证标准代码、域名、查询字符串检查
• 范围验证限制参数边界检查
• 安全验证注入模式检测与清理
• 消毒文本清洗和规范化
• 错误信息清晰、可操作的验证错误信息

MCP服务器 (index.ts):

• 高级别的 McpServer 来自（某）类的 @modelcontextprotocol/sdk
• 对所有工具输入进行Zod模式验证
• 优雅的关闭处理（SIGINT/SIGTERM）
• 用于MCP协议通信的StdioServerTransport
• 使用结构化响应进行错误处理

数据质量

• ✅ 100% 3D完整性所有标准均包含SEP、DCI和CCC组件
• ✅ 有效标准代码所有代码均符合模式 MS-(PS|LS|ESS)\d+-\d+
• ✅ 清理文本不包含嵌入的换行符或控制字符
• ✅ 表示“正确”或“已完成”。 完整主题完整主题名称（例如，“物质的结构和性质”）

源数据

• PDF 源文件《按主题划分的中学课程（NGSS版）.pdf》（3.6 MB）
• 提取方法基于模式的提取，通过pdf-extraction MCP服务器进行
• 生成的2025年10月15日
• 验证使用Zod进行模式验证，100%完整性已确认

许可证

麻省理工学院（MIT）

做出贡献

欢迎投稿！请确保：

• TypeScript 严格模式合规性
• 为新输入进行Zod模式验证
• 新功能的测试覆盖率
• API变更的文档更新

支持

对于问题、疑问或功能请求，请在仓库中提交一个问题。

演出

查询缓存:

• LRU 缓存100项条目容量，支持智能驱逐
• TTL（生存时间）过期缓存结果的生存时间（Time-To-Live）为5分钟
• 缓存命中率在典型使用模式下，效率为79%-90%
• 速度提升缓存查询的平均速度提高60倍

- searchStandards64倍加速（0.16毫秒 → 0.002毫秒） - 域名过滤搜索：速度提升10倍（0.04毫秒 → 0.004毫秒）

查询性能：

• 代码查找时间：\<0.01毫秒（O(1)）
• 域名搜索时间：\<0.05毫秒
• 关键词搜索：0.01-0.20毫秒（首次查询）
• 缓存查询：0.002-0.005毫秒
• 压力测试：0.04毫秒内完成100次查找（每次查找0.0004毫秒）

性能指标API：

• 实时查询统计信息通过 getQueryMetrics()
• 通过缓存统计 getCacheStats()
• 每种方法的性能跟踪
• 命中率和驱逐监控

输入验证

所有查询方法均包含全面的验证：

验证规则：

• 标准代码必须符合格式 MS-(PS|LS|ESS)\d+-\d+
• 领域/域名（根据上下文，"Domains" 可以翻译为“领域”或“域名”，这里提供了两种可能的翻译）必须是以下之一：物理科学、生命科学、地球与空间科学
• 查询字符串1-500个字符，已进行安全处理
• 限制参数1-100（仅限正整数）
• 注射防护阻止可疑模式和控制字符

验证错误： 抛出带有明确信息的描述性错误：

// 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

好处；利益：

• 防止格式错误的请求
• 清晰的错误提示信息
• 增强对注入攻击的安全防护
• 对所有文本字段进行输入净化