mcp-server-3gpp

🔍 MCP Server for 3GPP Specification Document Search

A Model Context Protocol (MCP) server that enables AI assistants to search and retrieve information from 3GPP specification documents.

Features

• 📚 Search 3GPP Documents: Full-text search across 3GPP specifications
• 📋 EMM/5GMM Cause Lookup: Quick reference for LTE and 5G NAS cause values
• 🎯 Pre-built Data Included: Ready to use immediately after installation
• 🔄 MCP SDK v1.0.0 Compatible: Full support for structured responses
• ✅ Comprehensive Testing: 13 test scenarios with validation tools

✅ Included Specifications (Pre-processed)

• TS 24.008 - 2G/3G NAS (MM/GMM/SM/CC)
• TS 24.301 - LTE NAS (EMM/ESM)
• TS 24.501 - 5G NAS (5GMM/5GSM)
• TS 36.300 - E-UTRA Overall Description

📥 Additional Specifications (User can add)

The MCP server architecture supports expanding to more specifications. Users can add:

PCT (Protocol Conformance Test)

• TS 51.010-1 (2G), TS 34.123-1 (3G), TS 36.523-1 (4G), TS 38.523-1 (5G)

Protocol

• TS 31.121 (USIM), TS 31.124 (USAT)

IMS

• TS 34.229-1 (4G IMS), TS 34.229-5 (5G IMS)

Architecture

• TS 38.300 (NR Overall), TR 37.901 (Data Throughput)

RF (if needed)

• TS 36.521, TS 38.521 series, etc.

To add specifications: Download PDFs → Run npm run setup

Available Tools

Tool	Description
search_3gpp_docs	Search 3GPP documents by keywords
get_emm_cause	Get EMM cause (LTE) or 5GMM cause (5G) details
list_specs	List available specifications

Testing & Validation

This package includes comprehensive testing tools:

# Run all SpecKit user story tests (13 scenarios)
npm test

# Validate data structure and MCP server
npm run validate

Test Coverage:

• ✅ 13 acceptance scenarios from SpecKit specs
• ✅ All 3 MCP tools (search, get_emm_cause, list_specs)
• ✅ Data structure validation (22,408 chunks)
• ✅ EMM/5GMM cause lookup verification

Installation

Prerequisites

• Node.js >= 18.0.0
• Git LFS (for downloading pre-built data)

Quick Start (Recommended)

# Install Git LFS (if not already installed)
git lfs install

# Clone and install
git clone https://github.com/Lee-SiHyeon/mcp-server-3gpp.git
cd mcp-server-3gpp
npm install

# If chunks.json is a pointer file, pull LFS data
git lfs pull

# ✅ Ready to use! Pre-built data with 17 specs included.
npm start

Note: The pre-built chunks.json (107MB) is stored with Git LFS. If you don't have Git LFS installed, you can still use the MCP server for EMM/5GMM cause lookup, or generate data yourself using the scripts.

Included Specs

The package includes pre-processed chunks for 17 specifications:

NAS Layer (4 specs)

• TS 24.008 (2G/3G NAS)
• TS 24.301 (LTE NAS)
• TS 24.501 (5G NAS)
• TS 36.300 (E-UTRA Architecture)

RRC - Radio Resource Control (3 specs) 🆕

• TS 25.331 (3G UMTS RRC - SIB details)
• TS 36.331 (4G LTE RRC - SIB details)
• TS 38.331 (5G NR RRC - SIB details)

PCT - Protocol Conformance Test (4 specs)

• TS 51.010-1 (2G Protocol)
• TS 34.123-1 (3G Protocol)
• TS 36.523-1 (4G Protocol)
• TS 38.523-1 (5G Protocol)

USIM/USAT (2 specs)

• TS 31.121 (USIM)
• TS 31.124 (USAT)

IMS (2 specs)

• TS 34.229-1 (4G IMS)
• TS 34.229-5 (5G IMS)

Architecture (2 specs)

• TS 38.300 (5G NR)
• TR 37.901 (Data Throughput)

Total: 22,408 pre-built chunks, ~107MB

Optional: Update Data

If you want to regenerate data with the latest 3GPP specifications:

# Option 1: Automatic (downloads and processes PDFs)
npm run setup

# Option 2: Manual
# Step 1: Download PDFs
npm run download-pdfs
# Step 2: Extract and chunk
npm run prepare-data

Data Preparation

✅ Pre-built Data Included (Git LFS)

This package includes pre-processed 3GPP specification data (chunks.json) with 17 specifications and 22,408 chunks (~107MB).

Important: The data file is stored using Git LFS (Large File Storage).

If you have Git LFS installed:

git lfs pull  # Download the actual data file

If you don't have Git LFS:

# Option 1: Install Git LFS (recommended)
# Windows: Download from https://git-lfs.github.com/
# Mac: brew install git-lfs
# Linux: sudo apt-get install git-lfs

git lfs install
git lfs pull

# Option 2: Manual download
# Download chunks.json from GitHub releases or generate it yourself (see below)

Without Git LFS: The MCP server will still work for EMM/5GMM cause lookup. Full document search requires the data file.

📥 Add More Specifications (Optional)

Want to add more specifications? Follow these steps:

Prerequisites

# Install Python dependencies (required for PDF processing)
pip install pymupdf

Option 1: Automatic Download

Download additional specifications automatically:

# Download PCT specs (Protocol, USIM, USAT, IMS, Architecture)
python scripts/download_pct_specs.py

# Download RRC specs (3G/4G/5G RRC with SIB details) 🆕
python scripts/download_rrc_specs.py

PCT specs include:

• Protocol: TS 51.010-1 (2G), TS 34.123-1 (3G), TS 36.523-1 (4G), TS 38.523-1 (5G)
• USIM/USAT: TS 31.121, TS 31.124
• IMS: TS 34.229-1, TS 34.229-5
• Architecture: TS 38.300, TR 37.901

RRC specs include (for SIB details):

• TS 25.331 (3G UMTS RRC)
• TS 36.331 (4G LTE RRC)
• TS 38.331 (5G NR RRC)

Option 2: Manual Download

Download specifications manually from:

• 3GPP Official Site
• ETSI Standards

Place PDFs in the raw/ folder.

Process PDFs and Update chunks.json

After downloading PDFs:

# Step 1: Extract text from all PDFs in raw/ folder
python scripts/extract_pdf.py

# Step 2: Create chunks from extracted text
python scripts/create_chunks_simple.py

# Step 3: Copy to data folder
# Windows:
copy "extracted\chunks.json" "data\chunks.json"
# Linux/Mac:
cp extracted/chunks.json data/chunks.json

Advanced: Customize Scripts

All scripts are fully editable:

• scripts/download_pct_specs.py - Modify to download different specs
• scripts/extract_pdf.py - Adjust text extraction settings
• scripts/create_chunks_simple.py - Change chunk size/overlap

Example: Edit download_pct_specs.py to add new specifications:

SPECS = [
    {
        'name': 'ts_your_spec',
        'series': '12300_12399',  # ETSI series folder
        'spec_num': '123001',     # Spec number
        'version': '18.00.00_60', # Target version
        'description': 'Your Spec Description'
    },
    # Add more specs...
]

Configuration

VS Code / GitHub Copilot

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "3gpp-docs": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server-3gpp/src/index.js"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "3gpp-docs": {
      "command": "node",
      "args": ["/path/to/mcp-server-3gpp/src/index.js"]
    }
  }
}

Custom Data Path

Set the CHUNKS_FILE_PATH environment variable to use a custom chunks file location:

{
  "servers": {
    "3gpp-docs": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server-3gpp/src/index.js"],
      "env": {
        "CHUNKS_FILE_PATH": "/path/to/your/chunks.json"
      }
    }
  }
}

Usage Examples

Once configured, you can ask your AI assistant:

• "What is EMM cause #3?"
• "Search for attach procedure in 3GPP docs"
• "Explain 5GMM cause #7"
• "Find information about tracking area update"
• "List all available 3GPP specifications"
• "Search for SIB information in RRC specs"

Response Format

All tools return structured responses compatible with MCP SDK v1.0.0:

{
  "content": [
    {
      "type": "text",
      "text": "Human-readable response"
    }
  ],
  "structuredContent": {
    "results": [
      {
        "source": "ts_124301_v18.9.0_LTE_NAS",
        "content": "Detailed specification text..."
      }
    ]
  }
}

This allows AI clients to:

• Display formatted text to users
• Process structured data programmatically
• Integrate with automation workflows

EMM/5GMM Cause Quick Reference

Common EMM Causes (LTE - TS 24.301)

Cause	Name
#3	Illegal UE
#6	Illegal ME
#7	EPS services not allowed
#11	PLMN not allowed
#12	Tracking Area not allowed
#15	No Suitable Cells In TA
#22	Congestion

Common 5GMM Causes (5G - TS 24.501)

Cause	Name
#3	Illegal UE
#6	Illegal ME
#7	5GS services not allowed
#11	PLMN not allowed
#62	No network slices available
#65	Maximum PDU sessions reached

Project Structure

mcp-server-3gpp/
├── src/
│   └── index.js                    # MCP server implementation
├── scripts/
│   ├── extract_pdf.py              # PDF text extraction (editable)
│   ├── create_chunks_simple.py     # Text chunking (editable)
│   ├── download_pct_specs.py       # Auto-download PCT specs (editable)
│   ├── download_rrc_specs.py       # Auto-download RRC specs (editable) 🆕
│   ├── download-pdfs.js            # Download NAS specs
│   └── postinstall.js              # Post-install setup
├── data/
│   └── chunks.json                 # Pre-built chunks (22,408 chunks, 107MB)
├── test_speckit_userstories.js     # Comprehensive test suite 🆕
├── validate.js                     # Data & server validation 🆕
├── raw/                            # Place PDFs here (optional)
├── extracted/                      # Extracted text files (generated)
├── package.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file.

Disclaimer

This project is not affiliated with 3GPP. 3GPP specifications are copyrighted by ETSI and 3GPP partners. Users are responsible for complying with 3GPP's terms of use when downloading and using specification documents.

Developer Documentation

SpecKit (Spec-Driven Development)

This project uses SpecKit for maintaining development context and collaboration.

What is SpecKit?

SpecKit is a Spec-Driven Development framework that helps developers and AI agents maintain shared context through structured specifications.

Key Principle: Specifications come first, code follows.

SpecKit Workflow

Constitution → Specify → Plan → Tasks → Implement

1. Constitution (.specify/constitution.md): Project principles, technical stack, historical decisions
2. Specs (.specify/specs/): Feature specifications with user stories and acceptance criteria
3. Plans (.specify/plans/): Technical implementation plans and architecture
4. Tasks (.specify/tasks/): Granular task breakdowns with dependencies

Using SpecKit

If you have Claude Desktop or VS Code with the SpecKit extension:

Available Slash Commands:

• /speckit-constitution - View/update project constitution
• /speckit-specify - Create feature specifications
• /speckit-plan - Create implementation plans
• /speckit-tasks - Break down tasks
• /speckit-implement - Execute implementation
• /speckit-clarify - Clarify ambiguous specifications
• /speckit-analyze - Analyze consistency across specs
• /speckit-checklist - Quality checklist
• /speckit-taskstoissues - Convert tasks to GitHub Issues

Manual Access: All SpecKit files are in .specify/ directory and can be read/edited directly:

.specify/
├── constitution.md          # Project overview
├── specs/
│   └── 001-3gpp-document-search.md
├── plans/
│   └── 001-implementation-plan.md
├── tasks/
│   └── 001-tasks.md
└── templates/               # Templates for new features

Why SpecKit for this Project?

• Context Sharing: NAD team and future developers have complete project history
• AI Collaboration: AI agents understand design decisions and constraints
• Onboarding: New contributors can read specs instead of reverse-engineering code
• Documentation: Living documentation that evolves with code

Related Projects

• Model Context Protocol
• 3GPP Specifications
• SpecKit - Spec-Driven Development