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

Architecture Patterns

Core patterns for PowerPointMcp development

.NET Class Design (MANDATORY)

1. One Public Class Per File - standard .NET practice.
2. File Name = Class Name - ShapeCommands.cs contains ShapeCommands.
3. Partial Classes for Large Implementations - split when a class grows past ~15 methods or spans multiple sub-concerns (not needed yet at current Core domain sizes).
4. Descriptive Names - no over-optimization (ShapeCommands not Commands).
5. Folder = Organization, Not Identity - Commands/domain folders group files; the type name itself doesn't encode the folder.

Layered Architecture (CRITICAL)

ComInterop (STA thread, OLE message filter, PresentationBatch work queue)
    ↓
Core (domain commands: Presentation, Slide, Shape, TextFrame, Table, Notes, Layout, Master,
      Animation, Image, Media, Chart, Export — all but Presentation carry a [ServiceCategory] attribute)
    ↓
Service (PowerPointMcpService: session registry + dispatch, shared codebase)
    ↓                                              ↓
McpServer (in-process, ServiceBridge)        CLI / pptcli (named-pipe daemon, ServiceClient)

• ComInterop owns all direct COM object lifetime and STA-thread marshaling. Core never talks to Microsoft.Office.Interop.PowerPoint types outside of a batch.Execute(...) callback.
• Core commands take IPresentationBatch batch as an explicit first parameter (no ambient session state). Domains other than Presentation also carry a [ServiceCategory("name", "PascalName")] attribute (and an [McpTool(...)] attribute describing the generated tool) so PowerPointMcp.Generators.Mcp/.Cli can discover them — mirroring mcp-server-excel's generator pipeline.
• Service (PowerPointMcp.Service) resolves sessionId → IPresentationBatch via its own PresentationSessionRegistry, then calls the matching Core command with the resolved batch. Both entry points call into this same dispatch logic (ServiceRegistry.{Category}.RouteAction) — MCP in-process via ServiceBridge.ForwardToService, CLI over a named pipe via ServiceClient/IPowerPointDaemonRpc.
• McpServer tools are thin either way: the 7 hand-written session/template tools (PresentationTools.cs) resolve sessionId → batch directly via PresentationSessionRegistry.TryGet; the 11 generated action-dispatch tools (slide/shape/chart/etc., one per [ServiceCategory] domain) forward straight to the shared PowerPointMcpService. No domain logic lives in either.