3gpp-mcp-server/docs/api-reference.md

MCP Server for querying 3GPP telecom protocol specifications

# API Reference

## Overview

This document provides a complete reference for all MCP tools, resources, and prompts available in the 3GPP MCP Server. The server implements the Model Context Protocol specification and provides specialized capabilities for querying 3GPP telecommunications specifications.

## MCP Server Information

- **Name**: `3gpp-mcp-server`
- **Version**: `1.0.0`
- **Protocol Version**: MCP 2024-11-05
- **Capabilities**: Tools, Resources, Prompts

## Tools

Tools are callable functions that perform specific operations on 3GPP specifications and return structured results.

### `search_3gpp_specs`

Search through 3GPP specification documents using semantic search capabilities.

**Description**: Performs intelligent search across the 3GPP specification database with support for natural language queries, filtering, and relevance ranking.

**Input Schema**:
```typescript
{
  query: string;              // Search query text (REQUIRED)
  series?: string[];          // Filter by specification series (e.g., ["24", "25"])
  releases?: string[];        // Filter by 3GPP releases (e.g., ["Rel-15", "Rel-16"])
  limit?: number;             // Maximum results (1-50, default: 10)
  offset?: number;            // Pagination offset (default: 0)
}
```

**Parameters**:
- **`query`** (string, required): Natural language search query
  - Examples: "NAS authentication", "5G security procedures", "RRC handover"
  - Supports both technical terms and natural language descriptions

- **`series`** (array of strings, optional): Filter by 3GPP specification series
  - Valid values: "21", "22", "23", "24", "25", "26", "27", "28", "29", "31", "32", "33", "34", "35", "36", "37", "38"
  - Examples: ["24"] for NAS protocols, ["36", "38"] for RRC protocols

- **`releases`** (array of strings, optional): Filter by 3GPP releases
  - Format: "Rel-XX" where XX is release number
  - Examples: ["Rel-15", "Rel-16"] for 5G releases

- **`limit`** (number, optional): Maximum number of results
  - Range: 1-50
  - Default: 10

- **`offset`** (number, optional): Number of results to skip for pagination
  - Minimum: 0
  - Default: 0

**Response Format**:
```typescript
{
  content: [{
    type: "text",
    text: string; // Formatted search results with specifications, relevance scores, and context
  }]
}
```

**Response Structure**:
The response text contains formatted results with:
- Specification ID and title
- Series, release, and version information
- Relevance score (0-100%)
- Matched content snippets
- Context information

**Example Request**:
```json
{
  "name": "search_3gpp_specs",
  "arguments": {
    "query": "NAS authentication procedures",
    "series": ["24"],
    "releases": ["Rel-15", "Rel-16"],
    "limit": 5
  }
}
```

**Example Response**:
```
Found 3 specifications matching "NAS authentication procedures":

**TS 24.301** - Non-Access-Stratum (NAS) protocol for Evolved Packet System (EPS)
Series: 24 | Release: Rel-15 | Version: 15.9.0
Relevance: 85.2%
Matched content: "authentication procedures"
Context: Specifies the Non-Access-Stratum protocol including authentication...
---

**TS 24.501** - Non-Access-Stratum (NAS) protocol for 5G System (5GS)
Series: 24 | Release: Rel-16 | Version: 16.7.0
Relevance: 91.7%
Matched content: "5G authentication procedures"
Context: Defines 5G NAS protocol including enhanced authentication mechanisms...
```

### `get_specification_details`

Retrieve detailed information about a specific 3GPP specification.

**Description**: Provides comprehensive information about a specific specification including metadata, content summary, or raw content depending on the requested format.

**Input Schema**:
```typescript
{
  specId: string;             // Specification ID (REQUIRED)
  format?: "summary" | "detailed" | "raw"; // Detail level (default: "summary")
}
```

**Parameters**:
- **`specId`** (string, required): 3GPP specification identifier
  - Format: "TS XX.XXX" (e.g., "TS 24.301", "TS 38.331")
  - Case-insensitive matching supported

- **`format`** (enum, optional): Level of detail to return
  - **"summary"** (default): Basic information with metadata
  - **"detailed"**: Comprehensive summary with sections and analysis
  - **"raw"**: Full document content (when available)

**Response Format**:
```typescript
{
  content: [{
    type: "text",
    text: string; // Formatted specification details based on requested format
  }]
}
```

**Example Request**:
```json
{
  "name": "get_specification_details",
  "arguments": {
    "specId": "TS 24.501",
    "format": "summary"
  }
}
```

**Example Response**:
```
# Non-Access-Stratum (NAS) protocol for 5G System (5GS) (TS 24.501)

**Series:** 24
**Release:** Rel-16
**Version:** 16.7.0
**Size:** 2048 KB
**Last Modified:** 2023-03-15

This Technical Specification defines the Non-Access-Stratum protocol for the 5G System, including procedures for registration, session management, and mobility management.

**Keywords:** NAS, 5GS, 5G, Protocol, Authentication, Session Management
```

### `query_protocol_info`

Get information about specific 3GPP protocols and procedures.

**Description**: Provides protocol-specific information including procedures, messages, and technical details for major 3GPP protocols.

**Input Schema**:
```typescript
{
  protocolName: string;       // Protocol name (REQUIRED)
  queryType?: "procedures" | "messages" | "overview"; // Query type (default: "overview")
}
```

**Parameters**:
- **`protocolName`** (string, required): Name of the 3GPP protocol
  - Examples: "NAS", "RRC", "MAC", "RLC", "PDCP", "NGAP", "XNAP"
  - Case-insensitive matching
  - Supports both short names (NAS) and full names (Non-Access Stratum)

- **`queryType`** (enum, optional): Type of information to retrieve
  - **"overview"** (default): General protocol description and key features
  - **"procedures"**: Detailed procedure descriptions with steps
  - **"messages"**: Protocol message formats and usage

**Response Format**:
```typescript
{
  content: [{
    type: "text",
    text: string; // Formatted protocol information based on query type
  }]
}
```

**Example Request**:
```json
{
  "name": "query_protocol_info",
  "arguments": {
    "protocolName": "RRC",
    "queryType": "procedures"
  }
}
```

**Example Response**:
```
## Radio Resource Control (RRC) - Procedures

### Connection Establishment
**Description:** Procedure to establish RRC connection between UE and gNB

**Steps:**
1. UE sends RRC Connection Request
2. gNB responds with RRC Connection Setup
3. UE confirms with RRC Connection Setup Complete

**Related Specifications:** TS 36.331, TS 38.331

---

### Handover Procedure
**Description:** Procedure to transfer UE connection between cells

**Steps:**
1. Source cell makes handover decision
2. Target cell prepares resources
3. UE reconfigures to target cell
4. UE confirms handover completion

**Related Specifications:** TS 38.331
```

### `find_related_specs`

Find specifications related to a given topic or specification.

**Description**: Discovers specifications that are related to a specific topic, protocol, or existing specification through content analysis and cross-referencing.

**Input Schema**:
```typescript
{
  topic: string;              // Topic or specification to find relations for (REQUIRED)
  maxResults?: number;        // Maximum number of results (default: 5)
}
```

**Parameters**:
- **`topic`** (string, required): Topic, protocol name, or specification ID
  - Examples: "authentication", "TS 24.301", "5G security", "handover"
  - Supports both technical terms and specification identifiers

- **`maxResults`** (number, optional): Maximum number of related specifications
  - Range: 1-20
  - Default: 5

**Response Format**:
```typescript
{
  content: [{
    type: "text",
    text: string; // List of related specifications with brief descriptions
  }]
}
```

**Example Request**:
```json
{
  "name": "find_related_specs",
  "arguments": {
    "topic": "5G authentication",
    "maxResults": 3
  }
}
```

**Example Response**:
```
Related specifications for "5G authentication":

**TS 24.501** - Non-Access-Stratum (NAS) protocol for 5G System
Series: 24 | Release: Rel-16

**TS 33.501** - Security architecture and procedures for 5G System
Series: 33 | Release: Rel-16

**TS 29.518** - 5G System; Access and Mobility Management Services
Series: 29 | Release: Rel-16
```

## Resources

Resources provide access to structured data and catalogs maintained by the server.

### `3gpp://specifications/catalog`

**Description**: Complete catalog of available 3GPP specifications with statistics and metadata.

**URI**: `3gpp://specifications/catalog`
**MIME Type**: `application/json`

**Response Structure**:
```typescript
{
  totalSpecs: number;                    // Total number of specifications
  seriesCount: Record<string, number>;   // Count per specification series
  releaseCount: Record<string, number>;  // Count per 3GPP release
  formatCount: Record<string, number>;   // Count per file format
  sampleSpecs: GPPSpecification[];       // Sample specifications
}
```

**Example Response**:
```json
{
  "totalSpecs": 1247,
  "seriesCount": {
    "21": 45,
    "22": 89,
    "23": 156,
    "24": 78,
    "25": 34,
    "36": 123,
    "38": 98
  },
  "releaseCount": {
    "Rel-15": 234,
    "Rel-16": 287,
    "Rel-17": 198,
    "Rel-18": 156
  },
  "formatCount": {
    "markdown": 1089,
    "docx": 158
  },
  "sampleSpecs": [...]
}
```

### `3gpp://protocols/list`

**Description**: List of all 3GPP protocols with descriptions and related specifications.

**URI**: `3gpp://protocols/list`
**MIME Type**: `application/json`

**Response Structure**:
```typescript
GPPProtocol[] {
  name: string;                // Short protocol name
  fullName: string;            // Full protocol name
  series: string;              // Primary specification series
  specifications: string[];    // Related specification IDs
  description?: string;        // Protocol description
  procedures?: ProtocolProcedure[]; // Key procedures
}
```

**Example Response**:
```json
[
  {
    "name": "NAS",
    "fullName": "Non-Access Stratum",
    "series": "24",
    "specifications": ["TS 24.301", "TS 24.501"],
    "description": "Protocol between UE and core network for session and mobility management",
    "procedures": [...]
  },
  {
    "name": "RRC",
    "fullName": "Radio Resource Control",
    "series": "36",
    "specifications": ["TS 36.331", "TS 38.331"],
    "description": "Protocol for controlling radio resources between UE and base station",
    "procedures": [...]
  }
]
```

### `3gpp://releases/timeline`

**Description**: Timeline of 3GPP releases with major features and specification counts.

**URI**: `3gpp://releases/timeline`
**MIME Type**: `application/json`

**Response Structure**:
```typescript
{
  releases: Array<{
    name: string;              // Release name (e.g., "Rel-16")
    year: number;              // Release year
    majorFeatures: string[];   // Key features introduced
    specCount: number;         // Number of specifications
  }>
}
```

**Example Response**:
```json
{
  "releases": [
    {
      "name": "Rel-15",
      "year": 2018,
      "majorFeatures": ["5G NR", "NSA", "5G Core"],
      "specCount": 234
    },
    {
      "name": "Rel-16",
      "year": 2020,
      "majorFeatures": ["URLLC", "V2X Enhancement", "5G Positioning"],
      "specCount": 287
    }
  ]
}
```

## Prompts

Prompts provide pre-structured templates for complex queries and analysis tasks.

### `explain_3gpp_procedure`

**Description**: Generate a comprehensive explanation of a specific 3GPP procedure.

**Arguments**:
- **`procedure_name`** (required): Name of the procedure to explain
- **`detail_level`** (optional): Level of explanation detail
  - Values: "basic", "intermediate", "expert"
  - Default: "intermediate"

**Generated Prompt Structure**:
The prompt includes:
- Context about the procedure from specifications
- Request for structured explanation
- Specific output format requirements
- Detail level considerations

**Example Usage**:
```json
{
  "name": "explain_3gpp_procedure",
  "arguments": {
    "procedure_name": "5G NAS authentication",
    "detail_level": "intermediate"
  }
}
```

**Generated Prompt**:
```
Please explain the 3GPP procedure "5G NAS authentication" at an intermediate level of detail.

Based on the following information from the 3GPP specifications:
[Relevant specification content...]

Please provide:
1. Overview of the procedure's purpose
2. Step-by-step breakdown of the procedure
3. Key messages and parameters involved
4. Common use cases and scenarios
5. Related specifications and dependencies

Format your response in a clear, structured manner appropriate for someone with intermediate knowledge of 3GPP protocols.
```

### `compare_specifications`

**Description**: Generate a detailed comparison between two 3GPP specifications.

**Arguments**:
- **`spec1`** (required): First specification ID to compare
- **`spec2`** (required): Second specification ID to compare

**Generated Prompt Structure**:
- Metadata about both specifications
- Request for structured comparison
- Specific comparison criteria
- Output format guidelines

**Example Usage**:
```json
{
  "name": "compare_specifications",
  "arguments": {
    "spec1": "TS 36.331",
    "spec2": "TS 38.331"
  }
}
```

**Generated Prompt**:
```
Please compare the following 3GPP specifications:

**Specification 1: Radio Resource Control (RRC) Protocol specification (TS 36.331)**
- Series: 36
- Release: Rel-15
- Version: 15.11.0
- Abstract: Specifies the Radio Resource Control protocol for LTE

**Specification 2: NR Radio Resource Control (RRC) protocol specification (TS 38.331)**
- Series: 38
- Release: Rel-16
- Version: 16.7.0
- Abstract: Specifies the Radio Resource Control protocol for 5G NR

Please analyze and compare these specifications focusing on:
1. Purpose and scope differences
2. Technical approach variations
3. Protocol differences (if applicable)
4. Release evolution changes
5. Dependencies and relationships
6. Use case scenarios

Highlight the key differences and similarities in a structured format.
```

## Error Handling

### Common Error Responses

**Invalid Parameters**:
```json
{
  "content": [{
    "type": "text",
    "text": "Error: Invalid parameter 'series'. Expected array of valid series numbers."
  }]
}
```

**Specification Not Found**:
```json
{
  "content": [{
    "type": "text",
    "text": "Error: Specification TS 99.999 not found in the database."
  }]
}
```

**Search Query Too Short**:
```json
{
  "content": [{
    "type": "text",
    "text": "Error: Query must be at least 3 characters long."
  }]
}
```

### Error Categories

1. **Validation Errors**: Invalid input parameters or format
2. **Not Found Errors**: Requested specification or resource doesn't exist
3. **Processing Errors**: Server-side processing failures
4. **Rate Limiting**: Too many requests (if implemented)

## Rate Limits and Quotas

**Current Implementation**: No rate limits enforced
**Recommendations for Production**:
- 100 requests per minute per client
- 1000 requests per hour per client
- Complex queries (search) may have lower limits

## Data Freshness

**Dataset Version**: TSpec-LLM v2.0 (as of April 2025)
**Update Frequency**: Manual updates with new TSpec-LLM releases
**Coverage**: 3GPP Releases 8-19 (1999-2023)

## SDK Examples

### TypeScript/JavaScript

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: "3gpp-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

// Connect to server
await client.connect(transport);

// Search specifications
const searchResult = await client.callTool('search_3gpp_specs', {
  query: 'NAS authentication',
  series: ['24'],
  limit: 5
});

// Get specification details
const specDetails = await client.callTool('get_specification_details', {
  specId: 'TS 24.501',
  format: 'summary'
});

// Query protocol information
const protocolInfo = await client.callTool('query_protocol_info', {
  protocolName: 'RRC',
  queryType: 'procedures'
});
```

### Python (Conceptual)

```python
import asyncio
from mcp_client import MCPClient

async def main():
    client = MCPClient("3gpp-client", "1.0.0")
    await client.connect(stdio_transport)

    # Search for specifications
    result = await client.call_tool('search_3gpp_specs', {
        'query': 'NAS authentication',
        'series': ['24'],
        'limit': 5
    })

    print(result.content[0].text)

asyncio.run(main())
```

This API reference provides complete documentation for integrating with and using the 3GPP MCP Server's capabilities.