Content
# Telecom Ops Claude Code Plugin
A Claude Code plugin for telecom operations (O-RAN/Nephio), providing network slice intent parsing, O2-IMS status query, and more. This plugin showcases the full capabilities of the Claude Code plugin system, including Slash Commands, Agents, Hooks, and integration with MCP Server.
## Features
### 🎯 Slash Commands
#### `/telecom-ops:intent-parse`
Convert natural language service intent into Nephio-compatible KRM (Kubernetes Resource Model) configuration packages.
**Example Usage:**
```
/telecom-ops:intent-parse intent description: VR network, bandwidth: 5 Mbps downlink, latency: 9 ms, single UE test
```
**Functionality:**
- Parse parameters such as bandwidth, latency, and reliability
- Map to 3GPP S-NSSAI and NSST standards
- Generate `QoSIntent.yaml` and `NetworkSlice.yaml`
- Create a complete Kpt package structure
**Output:**
```
output/
└── vr-network-package/
├── Kptfile
├── QoSIntent.yaml
├── NetworkSlice.yaml
└── README.md
```
#### `/telecom-ops:o2-status`
Query O2-IMS (O-RAN O2 Interface for Infrastructure Management Service) list and site status.
**Example Usage:**
```
/telecom-ops:o2-status edge01
/telecom-ops:o2-status # Query all sites
```
**Functionality:**
- Site health status monitoring
- CPU, memory, and storage capacity queries
- Network interface usage statistics
- Alarm and deployment workload status
### 🤖 Agent
**`intent-translator`** - Network Slice Intent Translator
Specialized in converting high-level telecom service intent into concrete Kubernetes resource lists.
**Capabilities:**
- Intent analysis: extract key parameters from free text
- Specification mapping: map parameters to S-NSSAI values and network slice templates
- List generation guidance: plan KRM package structure
- GitOps integration suggestions: how to integrate with Porch/ConfigSync automation processes
**Configuration:**
- Model: Haiku (fast response)
- Tools: NotebookRead, TodoWrite
- Color: Blue
### 🪝 Hooks
The plugin is configured with a PostToolUse hook, which is automatically triggered after each tool invocation.
**Current Configuration:**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/kpt-render.sh"
}
]
}
]
}
}
```
**Effect:**
After each tool execution, the terminal will display:
```
[telecom-ops] PostToolUse hook triggered. This is where you could run kpt rendering or validation.
```
**Extensibility:**
Additional hooks can be added, such as PreToolUse, Notification, to achieve:
- Validation before file writing
- YAML syntax checking
- Automatic kpt rendering
- Error notification and alarm
### 🔌 MCP Server Integration
**⚠️ (Advanced) MCP Server:** If you replace `.mcp.json` with an actual O2-IMS / Nephio / kubectl server, the plugin will automatically start the corresponding server when enabled, becoming a tool for Claude.
**This feature is not yet fully developed.** Currently, a stub configuration example is provided.
**Current Configuration (Example):**
```json
{
"mcpServers": {
"telecom-cli": {
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/telecom-mcp-server.sh",
"args": [],
"env": {
"EXAMPLE_ENV": "value"
}
}
}
}
```
**Future Plans:**
After connecting to an actual O2-IMS MCP Server, the following tools will be provided:
- `mcp__o2ims_list_sites` - List all sites
- `mcp__o2ims_get_site_status` - Get detailed site status
- `mcp__o2ims_list_resource_pools` - Query resource pools
- `mcp__o2ims_get_deployments` - List deployed workloads
- `mcp__o2ims_query_alarms` - Query alarm events
- `mcp__o2ims_get_inventory` - Query hardware inventory
**Configuration Method:**
Refer to `telecom-ops/.mcp.json`, replace with actual MCP server endpoint and authentication information.
## Project Structure
```
telecom-ops-claude-code-plugins/
├── .claude-plugin/
│ ├── plugin.json # Plugin metadata
│ └── marketplace.json # Marketplace configuration
│
├── telecom-ops/ # Plugin main body
│ ├── agents/
│ │ └── intent-translator.md # Intent translator Agent
│ ├── commands/
│ │ ├── intent-parse.md # Intent Parse command
│ │ └── o2-status.md # O2 Status command
│ ├── hooks/
│ │ └── hooks.json # Hook configuration
│ ├── scripts/
│ │ ├── kpt-render.sh # PostToolUse hook script
│ │ └── telecom-mcp-server.sh # MCP server stub
│ └── .mcp.json # MCP server configuration
│
└── telecom-ops-tests/ # Test suite
├── prompts/
│ ├── S1_intent_to_krm.md # Test case 1: Intent parsing
│ ├── S2_o2_status.md # Test case 2: O2 status query
│ └── S3_hook_check.md # Test case 3: Hook verification
├── output/ # Generated KRM packages
├── scripts/
│ └── run_headless.sh # Headless automated testing
└── README.md
```
## Installation and Usage
### Method 1: Install from GitHub (Recommended)
```bash
# Run in Claude Code
/plugin marketplace add thc1006/telecom-ops-claude-code-plugins
/plugin install telecom-ops@telecom-ops-marketplace
```
### Method 2: Local Installation (Development)
```bash
# Clone the project
git clone https://github.com/thc1006/telecom-ops-claude-code-plugins.git
cd telecom-ops-claude-code-plugins
# Run in Claude Code
/plugin marketplace add ./telecom-ops-tests/dev-marketplace
/plugin install telecom-ops@dev-marketplace
```
### Enable the Plugin
```bash
/plugin enable telecom-ops
```
### Verify Installation
Restart Claude Code and run:
```bash
/plugin list
```
The `telecom-ops` plugin should be listed as enabled.
## Test Cases
### Test 1: Intent Parse
```
Use the /intent parse command provided by the telecom-ops plugin,
convert this intent into a KRM draft and list the expected output:
VR network, 5 Mbps downlink, 9 ms latency, single UE test.
```
**Expected Result:**
- Generate `QoSIntent.yaml` (containing 5QI=7, 9ms latency, 5Mbps bandwidth)
- Generate `NetworkSlice.yaml` (eMBB type, single UE configuration)
- Generate `Kptfile` and `README.md`
- Output path hint
### Test 2: O2 Status
```
Demonstrate the /o2 status --site edge01 command,
if not yet connected to an actual O2-IMS, use stub text to reply to site/health/capacity fields.
```
**Expected Result:**
- Display site `edge01` health status (OK/DEGRADED)
- Display CPU, memory, and network capacity and usage
- Explain how to configure a real O2-IMS MCP server
### Test 3: Hook Verification
```
Perform an action that triggers a tool invocation and describe in the response:
(1) What messages should I see in the terminal to determine if the PostToolUse hook has been triggered?
(2) If you want to add PreToolUse or Notification hooks, how should hooks.json be extended?
```
**Expected Result:**
- Terminal displays `[telecom-ops] PostToolUse hook triggered...`
- Provide PreToolUse and Notification hooks configuration examples
- Explain the usage of `${CLAUDE_PLUGIN_ROOT}` variable
### Automated Testing
Run all tests in headless mode:
```bash
bash telecom-ops-tests/scripts/run_headless.sh
```
Test results will be stored in the `telecom-ops-tests/runs/` directory.
## Technical Details
### S-NSSAI Mapping Rules
The plugin automatically maps to the corresponding S-NSSAI based on the service type:
| Service Type | SST | SD | Purpose |
|---------|-----|-----|------|
| VR/Video Streaming | 1 (eMBB) | 000001 | Enhanced Mobile Broadband |
| IoT Sensors | 2 (mMTC) | 000002 | Massive Machine-Type Communications |
| Remote Surgery/Autonomous Vehicles | 3 (URLLC) | 000003 | Ultra-Reliable Low-Latency Communications |
### 5QI Mapping
| 5QI | Resource Type | Priority | Packet Delay Budget | Applicable Scenario |
|-----|---------|--------|---------------------|---------|
| 5 | GBR | 10 | 100ms | IMS Voice |
| 7 | GBR | 70 | 100ms | Video Streaming (default) |
| 9 | Non-GBR | 90 | 300ms | Web Browsing |
| 82 | GBR | 19 | 10ms | Low-Latency eMBB |
### Hook Execution Flow
```
User Request
↓
Claude processes
↓
Tool Calls (Write/Edit/Bash/etc.)
↓
[PreToolUse Hook] ← Configurable
↓
Tool Execution
↓
[PostToolUse Hook] ← Currently Configured
↓
Result returned to Claude
↓
[Notification Hook] ← Configurable
↓
Response to User
```
## Development and Extension
### Add a New Slash Command
1. Create a new `.md` file in `telecom-ops/commands/`
2. Define description and argument-hint using frontmatter
3. Write command documentation and usage examples
4. Restart Claude Code to load the new command
### Add a New Agent
1. Create a new `.md` file in `telecom-ops/agents/`
2. Define agent name, description, tools, and model
3. Write agent capabilities and guidelines
4. Restart Claude Code to load the new agent
### Configure Hooks
Edit `telecom-ops/hooks/hooks.json`:
```json
{
"hooks": {
"PreToolUse": [...],
"PostToolUse": [...],
"Notification": [...]
}
}
```
Supported matchers:
- `"*"` - Match all
- `"Write|Edit"` - Match specific tools
- `"error"` - Match error notifications
### Integrate with MCP Server
1. Implement an MCP protocol-compliant server
2. Update `telecom-ops/.mcp.json` configuration
3. Set environment variables (API endpoint, token, etc.)
4. Restart Claude Code to start the MCP server
5. Use tools with the `mcp__` prefix
## Frequently Asked Questions
### Q: Hook not triggered?
**A:** Check the following:
1. Script execution permissions: `chmod +x telecom-ops/scripts/*.sh`
2. Hook configuration correctness: check `hooks/hooks.json` syntax
3. Plugin enabled: `/plugin list`
4. Restart Claude Code and verify terminal output
### Q: Slash Command not found?
**A:**
1. Confirm plugin installed: `/plugin list`
2. Confirm plugin enabled: `/plugin enable telecom-ops`
3. Restart Claude Code
4. Check command file format (requires frontmatter)
### Q: How to connect to a real O2-IMS?
**A:** Currently, the MCP Server integration feature is not fully developed. Requires:
1. Implement an O2-IMS MCP server (refer to MCP protocol specifications)
2. Update `.mcp.json` configuration with actual API endpoint
3. Set authentication information (recommended using environment variables)
4. Test connection and tool availability
### Q: Can generated KRM files be deployed directly?
**A:** Generated files are initial templates, requiring adjustments based on the actual environment:
- Coverage area
- Network function deployment target
- Resource quota
- Namespace and labels
Recommended process:
1. Use plugin to generate initial configuration
2. Manually review and adjust parameters
3. Use `kpt fn render` for validation
4. Submit to GitOps repository
5. Deploy through Nephio/Config Sync
## Related Resources
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
- [Claude Code Plugin Development Guide](https://docs.claude.com/en/docs/claude-code/plugins)
- [O-RAN Alliance](https://www.o-ran.org/)
- [Nephio Project](https://nephio.org/)
- [3GPP TS 23.501 - 5G System Architecture](https://www.3gpp.org/DynaReport/23501.htm)
- [Kpt Package Management](https://kpt.dev/)
## License
This project is licensed under the MIT License.
## Contributions
Welcome to submit issues and pull requests!
**Developer:**
- Telecom Plugin Developer
**Repository:**
- https://github.com/thc1006/telecom-ops-claude-code-plugins
## Version History
### v0.0.1 (2025-10-12)
- Initial version
- Implemented `/telecom-ops:intent-parse` command
- Implemented `/telecom-ops:o2-status` command
- Added `intent-translator` agent
- Configured PostToolUse hook
- Provided MCP server stub configuration
- Complete test suite and documentation
