mcp-server-powerpoint mcp-server-guide.instructions.md

MCP Server Development Guide

All tool methods in this project are synchronous — they return string, not Task<string>. There is no async/await anywhere in the Tools/ classes; COM access via IPresentationBatch.Execute is already synchronous from the caller's point of view (the async plumbing lives inside PresentationBatch, not in the tool methods).

LLM-Facing Content Rules

NO EMOJIS in LLM-consumed content — never use emoji characters in:

• Tool [Description(...)] attributes and XML /// <summary> comments — the MCP SDK extracts these into the tool schema an LLM reads directly.
• skills/shared/*.md and any future MCP prompt content.

Use plain text markers: "IMPORTANT:", "WARNING:", "NOTE:", "CRITICAL:".

DO keep emojis in user-facing content: README.md, this repo's own governance docs, and other human-read documentation — humans appreciate visual aids; LLM tool schemas do not need them and they cost tokens for no benefit.

Two Kinds of Tools: Hand-Written vs. Generated

Most of the MCP tool surface is generated, not hand-written. Before editing anything under Tools/, know which kind you're touching:

• Hand-written (PresentationTools.cs only): the single presentation MCP tool. It is action-dispatch like Excel's file tool, but stays hand-written because create/open/list/close need custom session-registry behavior and optional sessionId.
• Generated (everything else — slide, shape, textframe, table, notes, layout, master, animation, image, media, chart, smartart, export): one action-dispatch tool per [ServiceCategory] Core domain, emitted by PowerPointMcp.Generators.Mcp from the Core interface's [ServiceCategory]/[McpTool] attributes and XML doc comments. Never hand-write a new tool class for one of these domains — add the operation to the Core interface (with XML docs) and the generator picks it up. See architecture-patterns.instructions.md's Command Pattern section for the Core-side attribute shape.