Ngss MCP

🚀 NGSS MCP Server

このMCPサーバーは、中学教育向けの次世代科学基準（NGSS）にプログラムからアクセスできるようにするものです。中学レベルの科学教育における基準を効率的に参照できます。

ステータス: ✅ v1.2.2 がnpmに公開されました

⚠️ 中学基準のみ このMCPサーバーは、NGSS中学（MS）基準のみにアクセスできます。小学（K - 5）または高校（HS）の基準は含まれていません。

🚀 クイックスタート

Model Context Protocol (MCP) サーバーを使用することで、中学教育の次世代科学基準（NGSS）にプログラムからアクセスできます。

✨ 主な機能

• 55の中学基準：NGSS中学基準を完全に網羅しています。
• 3Dフレームワーク対応：科学と技術の実践（SEP）、学問分野の核心概念（DCI）、横断的概念（CCC）を完全にサポートしています。
• マルチインデックスデータベース：コードによるO(1)の高速検索、ドメインフィルタリング、および関連性スコア付きの検索が可能です。
• 高性能キャッシュ：TTL付きのLRUキャッシュを使用して、繰り返しのクエリを60倍高速化します。
• パフォーマンスメトリクス：リアルタイムのクエリパフォーマンス追跡とキャッシュ統計を提供します。
• 入力検証：すべてのクエリパラメータに対して包括的な検証とサニタイズを行います。
• 8つの強力なツール：基準の検索、フィルタリング、およびユニット計画などの包括的なAPIを提供します。
• MCPプロトコル：Claude Desktop、Continue、およびその他のMCP互換AIアシスタントとのネイティブ統合が可能です。

📦 インストール

オプション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:

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

オプションC: Smitheryを介してインストール

Smithery から直接インストールして、Claude Desktopまたはその他のMCPクライアントで使用します。

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

これにより、Claude Desktopの設定でサーバーが自動的に構成されます。

オプション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

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

💻 使用例

基本的な使用法

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

📚 ドキュメント

データベース統計

利用可能なツール

他にも様々なツールが用意されており、基準の検索、フィルタリング、ユニット計画などの操作が可能です。詳細は上述の使用例を参照してください。

データモデル (ADR-001)

NGSS-MCPサーバーは、3Dフレームワークコンポーネントに対して単一オブジェクトデータモデルを使用しています。

• 各基準には1つの sep オブジェクトがあります: standard.sep.name
• 各基準には1つの ccc オブジェクトがあります: standard.ccc.name
• 各基準には1つの 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): コードインデックス、ドメインインデックス、全文インデックスを使用して高速な検索を可能にします。
• クエリキャッシュモジュール (query-cache.ts): TTL付きのLRUキャッシュを使用して、クエリの高速化を実現します。
• クエリ検証モジュール (query-validation.ts): すべての入力パラメータに対して包括的な検証とサニタイズを行います。
• MCPサーバー (index.ts): 高レベルの McpServer クラスを使用して、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%の完全性が検証されています。

パフォーマンス

クエリキャッシュ

• LRUキャッシュ: 100エントリの容量で、インテリジェントなエビクションが行われます。
• TTL有効期限: キャッシュされた結果の有効期限は5分です。
• キャッシュヒット率: 通常の使用パターンで79 - 90%です。
• 速度向上: キャッシュされたクエリの平均速度が60倍向上します。
  • searchStandards: 64倍の高速化 (0.16ms → 0.002ms)
  • ドメインフィルタリングされた検索: 10倍の高速化 (0.04ms → 0.004ms)

クエリパフォーマンス

• コード検索: <0.01ms (O(1))
• ドメイン検索: <0.05ms
• キーワード検索: 0.01 - 0.20ms (最初のクエリ)
• キャッシュされたクエリ: 0.002 - 0.005ms
• ストレステスト: 100回の検索が0.04msで完了 (1回の検索あたり0.0004ms)

パフォーマンスメトリクスAPI

• getQueryMetrics() を介したリアルタイムのクエリ統計
• getCacheStats() を介したキャッシュ統計
• メソッドごとのパフォーマンス追跡
• ヒット率とエビクションの監視

入力検証

すべてのクエリメソッドには包括的な検証が含まれています。

検証ルール:

• 基準コード: MS-(PS|LS|ESS)\d+-\d+ の形式に一致する必要があります。
• ドメイン: 物理科学、生命科学、地球と宇宙科学のいずれかである必要があります。
• クエリ文字列: 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

メリット:

• 不正なリクエストを防止します。
• 明確なエラーメッセージを提供します。
• インジェクションに対するセキュリティ強化を行います。
• すべてのテキストフィールドに対して入力サニタイズを行います。

🔧 技術詳細

データモデル (ADR-001)

NGSS-MCPサーバーは、3Dフレームワークコンポーネントに対して単一オブジェクトデータモデルを採用しています。これにより、各基準に対してSEP、CCC、DCIのオブジェクトがそれぞれ1つずつ存在することが保証され、データ構造が一貫し、フィルタリング操作が簡素化されます。

アーキテクチャ

サーバーは、データベースモジュール、クエリキャッシュモジュール、クエリ検証モジュール、およびMCPサーバーモジュールに分かれています。各モジュールは特定の機能を担い、全体として高性能で信頼性の高いサービスを提供します。

📄 ライセンス

MITライセンスの下で公開されています。

コントリビューション

コントリビューションを歓迎します。以下の点を確認してください。

• TypeScriptのstrictモードに準拠すること。
• 新しい入力に対してZodスキーマ検証を行うこと。
• 新しい機能に対してテストカバレッジを持つこと。
• APIの変更に対してドキュメントを更新すること。

サポート

問題、質問、または機能リクエストについては、リポジトリにissueを作成してください。