🚀 MCP Server for SEED Internet Emulator

[zzw4257]

🚀 MCP Server for SEED Internet Emulator

Summary: This PR introduces a complete Model Context Protocol (MCP) Server, turning the SEED Internet Emulator into an interactive environment for LLM agents.

Status	Tools Count	Primary Runtime	Category
🟢 Ready for Review	53 Tools	Python 3.10+	Infrastructure / Security

---

📋 Overview

The MCP Server acts as a bridge between LLM-based agents (like seed-agent) and the SEED Emulator. It enables agents to:

• Build: Define AS, Routers, and Networks via natural language.
• Operate: Configure OSPF/BGP and manage container lifecycles.
• Simulate: Inject faults and execute complex BGP hijack or DoS attack scenarios.

---

🏗️ Architecture

I use a Layered Hybrid Architecture to ensure both high-performance static tool access and flexible dynamic operation discovery.

graph TD A[LLM Agent / Client] -- "MCP Protocol (stdio)" --> B[MCP Server] subgraph "MCP Server Layer" B --> B1[Infrastructure Tools] B --> B2[Routing & Peering] B --> B3[Dynamic Ops Tools] B --> R[EmulatorRuntime Singleton] end R -- "Python API" --> C[SEED Emulator Core] C -- "Docker API" --> D[Network Nodes / Services] 

Loading

---

🛠️ Tool Inventory (Highlight)

I've implemented 53 tools categorized by their lifecycle stage.

🔹 1. Infrastructure (Static & High-Frequency)

Tool	Description	Key Arguments
create_as	Create Autonomous System	asn: int
create_router	Create BGP/OSPF router	asn, name
create_network	Create internal network	asn, name, prefix
connect_to_ix	Connect router to IX	asn, router_name, ix_id

🔹 2. Routing & Compilation

Tool	Description	Key Arguments
configure_ospf	Configure OSPF on AS	asn
set_as_relationship	Define Provider/Peer/Customer	asn1, asn2, rel
render_simulation	Render topology to internal state	-
start_simulation	Start Docker containers	-

🔹 3. Dynamic Operations (Runtime Discovery)

Tool	Description	Key Arguments
exec_command	Execute shell in container	container, command
inject_fault	Inject network faults (delay/loss)	container, fault_type
start_attack	Launch BGP Hijack / DoS	scenario, target
capture_traffic	Tcpdump on specific interface	container, interface

---

📐 Key Design Decisions

Important

Stateful Singleton Runtime: The EmulatorRuntime (in runtime.py) manages the emulator state (designing → rendered → running). This ensures that an LLM can perform multi-turn operations (e.g., "Add a router" then "Start it") without losing context.

• Idempotency: All tools are safe to retry. Calling create_as(100) twice returns the existing object instead of an error.
• Error Tolerance: Tools catch internal exceptions and return "Agent-friendly" error messages, preventing the entire LLM chain from crashing.
• Discovery: Ops tools are registered dynamically, allowing the server to expose new security tools without updating the core client logic.

---

📂 Reviewer's Guide

Importance	File	Purpose
⭐⭐⭐	mcp-server/server.py	Entry Point: All tool definitions and MCP registration.
⭐⭐⭐	mcp-server/runtime.py	Core State: Singleton logic for emulator lifecycle.
⭐⭐	mcp-server/verify_operations.py	Integration test showing an agent performing an attack.
⭐	mcp-server/tests/	Unit tests for tool logic.

---

🧪 Verification Plan

1. Automated Tests

cd mcp-server && pytest tests/

2. Manual Integration Demo

Verify tool discovery and execution:

# Verify dynamic tool discovery and basic topology build python3 mcp-server/verify_operations.py

---

🔮 Future Roadmap

• RPKI Support: Tools for prefix origin validation.
• Traffic Gen: Integration with iperf3 and hping3 tools.
• Visualizer: Real-time web-based topology viewer.

---

Reviewers: | Labels: feature, mcp, emulator
Ready for Review. 🚀

---