feat: add custom profile creation capability with comprehensive guidelines

Add nettune.create_profile tool to enable creation of custom optimization profiles. Update documentation with detailed guidelines for profile creation, including risk level selection, sysctl parameter recommendations, buffer size calculations for high-BDP links, and qdisc selection criteria. Implement HTTP and MCP endpoints for profile creation with validation.

- Add POST /profiles endpoint for creating custom profiles

Author: jtsang4

README.md

@@ -61,6 +61,7 @@ Or use the NPM wrapper:
 | `nettune.snapshot_server`         | Create a configuration snapshot for rollback        |
 | `nettune.list_profiles`           | List available optimization profiles                |
 | `nettune.show_profile`            | Show details of a specific profile                  |
+| `nettune.create_profile`          | Create a custom optimization profile                |
 | `nettune.apply_profile`           | Apply a profile (dry_run or commit mode)            |
 | `nettune.rollback`                | Rollback to a previous snapshot                     |
 | `nettune.status`                  | Get current server status and configuration         |
@@ -139,6 +140,7 @@ Flags:
 ### Profile Endpoints
 
 - `GET /profiles` - List profiles
+- `POST /profiles` - Create a new profile
 - `GET /profiles/:id` - Get profile details
 
 ### System Endpoints
@@ -205,23 +207,64 @@ Analyze the baseline results to classify the network situation:
 - Diagnosis: Current configuration is performing well
 - Recommended action: No changes needed; document current state
 
-### Phase 3: Profile Selection
+### Phase 3: Profile Selection or Creation
 
 Based on diagnosis:
 
 1. Call `nettune.list_profiles` to see available profiles
 2. Call `nettune.show_profile` for candidate profiles to understand their settings
-3. Select the most appropriate profile based on:
-   - User's stated goal (throughput vs latency vs balanced)
-   - Diagnosed issue type
-   - Server's current state
+3. Decide whether to use an existing profile or create a custom one:
+
+**Use existing profile when:**
+- A built-in profile closely matches the diagnosed issue
+- User wants a conservative, well-tested configuration
+- The network situation fits a common pattern (Type A or B)
+
+**Create custom profile when:**
+- Existing profiles don't address the specific issue
+- User has special requirements (e.g., specific buffer sizes, particular qdisc)
+- Fine-tuned parameters are needed based on measured BDP
+- Combining settings from multiple profiles would be beneficial
 
 Profile selection guidelines:
 - For Type A issues: Start with `bbr-fq-tuned-32mb` (increased buffers)
 - For Type B issues: Start with `bbr-fq-default` (conservative, with FQ qdisc)
-- For high-BDP links (high bandwidth × high RTT): Prefer larger buffer profiles
+- For high-BDP links (high bandwidth × high RTT): Prefer larger buffer profiles or create custom with calculated buffer sizes
 - For low-latency requirements: Prefer profiles without aggressive buffering
 
+### Creating Custom Profiles
+
+When creating a custom profile with `nettune.create_profile`, follow these guidelines:
+
+**Risk Level Selection:**
+- `low`: Only safe, widely-tested settings (e.g., enabling BBR, basic FQ)
+- `medium`: Moderate buffer increases, standard optimizations
+- `high`: Aggressive tuning, large buffers, experimental settings
+
+**Sysctl Parameter Guidelines:**
+
+| Parameter | Purpose | Conservative | Aggressive |
+|-----------|---------|--------------|------------|
+| `net.core.rmem_max` | Max receive buffer | 16MB | 64MB+ |
+| `net.core.wmem_max` | Max send buffer | 16MB | 64MB+ |
+| `net.ipv4.tcp_rmem` | TCP receive buffer (min/default/max) | "4096 131072 16777216" | "4096 524288 67108864" |
+| `net.ipv4.tcp_wmem` | TCP send buffer (min/default/max) | "4096 65536 16777216" | "4096 524288 67108864" |
+| `net.ipv4.tcp_congestion_control` | Congestion algorithm | bbr | bbr |
+| `net.ipv4.tcp_mtu_probing` | MTU discovery | 1 | 1 |
+| `net.ipv4.tcp_slow_start_after_idle` | Slow start behavior | 1 (safe) | 0 (better for persistent connections) |
+
+**Buffer Size Calculation (for high-BDP links):**
+```
+Required buffer = Bandwidth (bytes/sec) × RTT (seconds) × 2
+Example: 1 Gbps link with 100ms RTT = 125MB/s × 0.1s × 2 = 25MB
+```
+
+**Qdisc Selection:**
+- `fq` (Fair Queue): Best for BBR, provides flow isolation
+- `fq_codel`: Good for reducing bufferbloat, AQM built-in
+- `cake`: Advanced shaping, good for limited bandwidth scenarios
+- `pfifo_fast`: Default, minimal processing overhead
+
 ### Phase 4: Safe Application
 
 1. **Create Snapshot**: Call `nettune.snapshot_server` BEFORE any changes
@@ -277,6 +320,13 @@ Provide a summary including:
 - Compare latency during load vs baseline
 - RTT inflation > 2x suggests buffering issues
 
+### nettune.create_profile
+- Use when existing profiles don't match the diagnosed issue
+- Calculate buffer sizes based on measured bandwidth × RTT × 2
+- Start with `risk_level: "medium"` unless you have specific reasons
+- Always include a clear description explaining the profile's purpose
+- For high-BDP scenarios, set appropriate tcp_rmem/tcp_wmem based on BDP calculation
+
 ### nettune.apply_profile
 - ALWAYS use dry_run first
 - ALWAYS set auto_rollback_seconds for commit
@@ -317,11 +367,12 @@ When recommending changes:
 1. Runs baseline tests (status, RTT, throughput, latency-under-load)
 2. Analyzes results and classifies the issue
 3. Lists and reviews available profiles
-4. Creates a snapshot
-5. Does a dry-run and explains proposed changes
-6. After user approval, commits with auto-rollback
-7. Re-runs tests and compares results
-8. Provides a comprehensive summary
+4. Selects an existing profile OR creates a custom profile based on diagnosis
+5. Creates a snapshot
+6. Does a dry-run and explains proposed changes
+7. After user approval, commits with auto-rollback
+8. Re-runs tests and compares results
+9. Provides a comprehensive summary
 
 ## Troubleshooting
 

internal/client/http/client.go

@@ -207,6 +207,23 @@ func (c *Client) GetProfile(id string) (*types.Profile, error) {
 	return &result, nil
 }
 
+// CreateProfile calls POST /profiles to create a new profile
+func (c *Client) CreateProfile(profile *types.Profile) (*types.ProfileMeta, error) {
+	resp, err := c.doRequest("POST", "/profiles", profile)
+	if err != nil {
+		return nil, err
+	}
+	if !resp.Success {
+		return nil, resp.Error
+	}
+
+	var result types.ProfileMeta
+	if err := json.Unmarshal(resp.Data, &result); err != nil {
+		return nil, err
+	}
+	return &result, nil
+}
+
 // CreateSnapshot calls POST /sys/snapshot
 func (c *Client) CreateSnapshot() (*types.Snapshot, error) {
 	resp, err := c.doRequest("POST", "/sys/snapshot", nil)

internal/client/mcp/server.go

@@ -180,6 +180,50 @@ func (s *Server) registerTools() {
 		),
 		s.handleStatus,
 	)
+
+	// Tool: nettune.create_profile
+	s.mcpServer.AddTool(
+		mcp.NewTool("nettune.create_profile",
+			mcp.WithDescription("Create a new configuration profile for network optimization. The profile can then be applied using nettune.apply_profile."),
+			mcp.WithString("id",
+				mcp.Required(),
+				mcp.Description("Unique profile ID (alphanumeric with hyphens, e.g., 'my-custom-profile')"),
+			),
+			mcp.WithString("name",
+				mcp.Required(),
+				mcp.Description("Human-readable profile name (e.g., 'Low Latency Gaming Profile')"),
+			),
+			mcp.WithString("description",
+				mcp.Description("Detailed description of what this profile does and when to use it"),
+			),
+			mcp.WithString("risk_level",
+				mcp.Required(),
+				mcp.Description("Risk level of the profile"),
+				mcp.Enum("low", "medium", "high"),
+			),
+			mcp.WithBoolean("requires_reboot",
+				mcp.Description("Whether applying this profile requires a system reboot (default: false)"),
+			),
+			mcp.WithObject("sysctl",
+				mcp.Description("Sysctl parameters to set. Keys are sysctl paths (e.g., 'net.core.rmem_max'), values are the desired settings."),
+			),
+			mcp.WithString("qdisc_type",
+				mcp.Description("Queue discipline type for traffic control"),
+				mcp.Enum("fq", "fq_codel", "cake", "pfifo_fast"),
+			),
+			mcp.WithString("qdisc_interfaces",
+				mcp.Description("Which interfaces to apply qdisc to"),
+				mcp.Enum("default-route", "all"),
+			),
+			mcp.WithObject("qdisc_params",
+				mcp.Description("Additional qdisc parameters (type-specific, e.g., {'flow_limit': '10000'} for fq)"),
+			),
+			mcp.WithBoolean("systemd_ensure_qdisc_service",
+				mcp.Description("Whether to create a systemd service to persist qdisc settings across reboots (default: false)"),
+			),
+		),
+		s.handleCreateProfile,
+	)
 }
 
 // Tool handlers
@@ -338,6 +382,79 @@ func (s *Server) handleStatus(ctx context.Context, request mcp.CallToolRequest)
 	})), nil
 }
 
+func (s *Server) handleCreateProfile(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := parseArgs(request.Params.Arguments)
+
+	// Required fields
+	id := getStringArg(args, "id", "")
+	name := getStringArg(args, "name", "")
+	riskLevel := getStringArg(args, "risk_level", "")
+
+	if id == "" {
+		return mcp.NewToolResultError("Error: id is required"), nil
+	}
+	if name == "" {
+		return mcp.NewToolResultError("Error: name is required"), nil
+	}
+	if riskLevel == "" {
+		return mcp.NewToolResultError("Error: risk_level is required"), nil
+	}
+
+	// Optional fields
+	description := getStringArg(args, "description", "")
+	requiresReboot := getBoolArg(args, "requires_reboot", false)
+
+	// Build profile
+	profile := &types.Profile{
+		ID:             id,
+		Name:           name,
+		Description:    description,
+		RiskLevel:      riskLevel,
+		RequiresReboot: requiresReboot,
+	}
+
+	// Parse sysctl (map[string]interface{})
+	if sysctl := getMapArg(args, "sysctl"); sysctl != nil {
+		profile.Sysctl = sysctl
+	}
+
+	// Parse qdisc config
+	qdiscType := getStringArg(args, "qdisc_type", "")
+	qdiscInterfaces := getStringArg(args, "qdisc_interfaces", "")
+	if qdiscType != "" {
+		profile.Qdisc = &types.QdiscConfig{
+			Type:       qdiscType,
+			Interfaces: qdiscInterfaces,
+		}
+		if qdiscInterfaces == "" {
+			profile.Qdisc.Interfaces = "default-route" // default
+		}
+		if qdiscParams := getMapArg(args, "qdisc_params"); qdiscParams != nil {
+			profile.Qdisc.Params = qdiscParams
+		}
+	}
+
+	// Parse systemd config
+	ensureQdiscService := getBoolArg(args, "systemd_ensure_qdisc_service", false)
+	if ensureQdiscService {
+		profile.Systemd = &types.SystemdConfig{
+			EnsureQdiscService: true,
+		}
+	}
+
+	// Create profile via HTTP client
+	result, err := s.client.CreateProfile(profile)
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("Error creating profile: %v", err)), nil
+	}
+
+	return mcp.NewToolResultText(toJSON(map[string]interface{}{
+		"success": true,
+		"message": fmt.Sprintf("Profile '%s' created successfully", id),
+		"profile": result,
+	})), nil
+}
+
 // Helper functions for argument parsing
 
 // parseArgs converts the any type arguments to map[string]interface{}
@@ -404,6 +521,15 @@ func getBoolArg(args map[string]interface{}, key string, defaultVal bool) bool {
 	return defaultVal
 }
 
+func getMapArg(args map[string]interface{}, key string) map[string]interface{} {
+	if v, ok := args[key]; ok {
+		if m, ok := v.(map[string]interface{}); ok {
+			return m
+		}
+	}
+	return nil
+}
+
 func toJSON(v interface{}) string {
 	data, err := json.MarshalIndent(v, "", "  ")
 	if err != nil {

internal/server/api/handlers/profile.go

@@ -54,6 +54,51 @@ func (h *ProfileHandler) Get(c *gin.Context) {
 	success(c, profile)
 }
 
+// CreateProfileRequest represents a request to create a new profile
+type CreateProfileRequest struct {
+	ID             string                 `json:"id" binding:"required"`
+	Name           string                 `json:"name" binding:"required"`
+	Description    string                 `json:"description,omitempty"`
+	RiskLevel      string                 `json:"risk_level" binding:"required,oneof=low medium high"`
+	RequiresReboot bool                   `json:"requires_reboot,omitempty"`
+	Sysctl         map[string]interface{} `json:"sysctl,omitempty"`
+	Qdisc          *types.QdiscConfig     `json:"qdisc,omitempty"`
+	Systemd        *types.SystemdConfig   `json:"systemd,omitempty"`
+}
+
+// Create handles POST /profiles
+func (h *ProfileHandler) Create(c *gin.Context) {
+	var req CreateProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		badRequest(c, err.Error())
+		return
+	}
+
+	// Convert request to Profile
+	profile := &types.Profile{
+		ID:             req.ID,
+		Name:           req.Name,
+		Description:    req.Description,
+		RiskLevel:      req.RiskLevel,
+		RequiresReboot: req.RequiresReboot,
+		Sysctl:         req.Sysctl,
+		Qdisc:          req.Qdisc,
+		Systemd:        req.Systemd,
+	}
+
+	// Save profile (validation happens inside Save)
+	if err := h.profileService.Save(profile); err != nil {
+		if errors.Is(err, types.ErrValidationFailed) {
+			badRequest(c, err.Error())
+			return
+		}
+		internalError(c, err.Error())
+		return
+	}
+
+	success(c, profile.ToMeta())
+}
+
 func notFound(c *gin.Context, message string) {
 	c.JSON(404, gin.H{"success": false, "error": gin.H{"code": "NOT_FOUND", "message": message}})
 }

internal/server/api/server.go

@@ -118,6 +118,7 @@ func (s *Server) setupRouter() {
 	profiles := authorized.Group("/profiles")
 	{
 		profiles.GET("", profileHandler.List)
+		profiles.POST("", profileHandler.Create)
 		profiles.GET("/:id", profileHandler.Get)
 	}
 

js/README.md

@@ -109,6 +109,7 @@ Once connected, the following tools are available:
 | `nettune.snapshot_server` | Create a server state snapshot |
 | `nettune.list_profiles` | List available optimization profiles |
 | `nettune.show_profile` | Show details of a specific profile |
+| `nettune.create_profile` | Create a custom optimization profile |
 | `nettune.apply_profile` | Apply an optimization profile |
 | `nettune.rollback` | Rollback to a previous snapshot |
 | `nettune.status` | Get current server status |

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtsang/nettune-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "description": "MCP stdio wrapper for nettune - TCP network optimization tool",
   "type": "module",