mcp-server-ppt mcp-server-guide.instructions.md

MCP Server Development Guide

All action methods are synchronous. Tool signatures are async Task<string> only to satisfy MCP SDK requirements, but action method implementations use NO async/await.

LLM-Facing Content Rules

NO EMOJIS in LLM-consumed content - Never use emoji characters in:

• Tool XML comments (/// <summary>) - MCP SDK extracts these
• MCP Prompt files (Prompts/Content/*.md and skills/shared/*.md) - Direct LLM consumption
• Any code documentation consumed by LLMs

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

DO keep emojis in user-facing content: READMEs, FEATURES.md, user documentation, examples - humans appreciate visual aids.

Implementation Patterns

Action-Based Routing

[McpServerTool]
public async Task<string> PptSlide(string action, string pptPath, ...)
{
    return action.ToLowerInvariant() switch
    {
        "list" => List(...),      // Synchronous methods
        "view" => View(...),      // No await!
        _ => ThrowUnknownAction(action, "list", "view", ...)
    };
}

The file tool is hand-written — parity is NOT structural there

Every other MCP tool is generated from a Core interface marked [ServiceCategory], so the CLI counterpart appears by construction and cannot drift. PptFileTool.cs is the one exception, and its own header comment says so: "hand-coded because session management is not generated."

That makes it the only tool where adding an action to MCP silently leaves the CLI behind — and it is the bootstrap layer every workflow calls first. This already happened: test shipped on MCP and never reached the CLI (#131), while the CLI README documented a file test command that did not exist.

When you touch PptFileAction:

1. Add the matching command in src/PptMcp.CLI/Commands/SessionCommands.cs
2. Register it in the session branch in src/PptMcp.CLI/Program.cs
3. Run scripts\check-session-parity.ps1 — it is a pre-commit gate and will fail otherwise