mcp-server-ppt architecture-patterns.instructions.md

Architecture Patterns

Core patterns for PptMcp development

.NET Class Design (MANDATORY)

Official Docs: Framework Design Guidelines, Partial Classes

Key Rules

1. One Public Class Per File - Standard .NET practice (System.Text.Json, ASP.NET Core, EF Core)
2. File Name = Class Name - RangeCommands.cs contains RangeCommands
3. Partial Classes for Large Implementations - Split 15+ method classes by feature domain
4. Descriptive Names - No over-optimization (RangeCommands ✅, Commands ❌)
5. Folder = Organization, Not Identity - Commands/Range/RangeCommands.cs

Partial Class Pattern

When: Class has 15+ methods, multiple feature domains, team collaboration

Structure:

Commands/Range/
    IRangeCommands.cs           # Interface
    RangeCommands.cs            # Partial (constructor, DI)
    RangeCommands.Values.cs     # Partial (Get/Set values)
    RangeCommands.Formulas.cs   # Partial (formulas)
    RangeHelpers.cs             # Separate helper class

Benefits: Git-friendly, team-friendly, ~100-200 lines per file, mirrors .NET Framework patterns

---

TWO EQUAL ENTRY POINTS (CRITICAL)

PptMcp has TWO first-class entry points: MCP Server AND CLI. Both must have:

• Feature parity: Every action in MCP must exist in CLI and vice versa
• Parameter parity: Same parameters, same defaults, same validation
• Behavior parity: Same Core command, same result format

When adding or changing ANY feature, ALWAYS update BOTH entry points. See Rule 24 (Post-Change Sync).

MCP Server (MCP tools, JSON-RPC) ──► In-process PptMcpService ──► Core Commands ──► PowerPoint COM
CLI (command-line args, console)  ──► CLI Daemon (named pipe) ─────► Core Commands ──► PowerPoint COM

---

Command Pattern

Structure

Commands/
├── ISlideCommands.cs    # Interface
├── SlideCommands.cs     # Implementation