convert-contents

Instructions

@startuml Two Modes - Technical View
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v20.0/dist
!include AWSPuml/AWSCommon.puml

!include AWSPuml/AWSSimplified.puml
!include AWSPuml/General/Users.puml
!include AWSPuml/NetworkingContentDelivery/APIGateway.puml
!include AWSPuml/SecurityIdentityCompliance/Cognito.puml
!include AWSPuml/Compute/Lambda.puml
!include AWSPuml/Database/DynamoDB.puml

left to right direction

Users(sources, "Events", "millions of users")
APIGateway(votingAPI, "Voting API", "user votes")
Cognito(userAuth, "User Authentication", "jwt to submit votes")
Lambda(generateToken, "User Credentials", "return jwt")
Lambda(recordVote, "Record Vote", "enter or update vote per user")
DynamoDB(voteDb, "Vote Database", "one entry per user")

sources --> userAuth
sources --> votingAPI
userAuth <--> generateToken
votingAPI --> recordVote
recordVote --> voteDb
@enduml

Implementation Reference

• src/mcp_pandoc_md2pptx/server.py:101-179 (handler)

  The handle_call_tool function is the handler for the 'convert-contents' tool. It extracts arguments (contents, input_file, output_file, template), validates them, optionally applies a diagram filter and template, then uses pypandoc to convert markdown content/file to PPTX format.

  @server.call_tool()
  async def handle_call_tool(
      name: str, arguments: dict | None
  ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:    
      """
      Handle tool execution requests.
      Tools can modify server state and notify clients of changes.
      """
      if name not in ["convert-contents"]:
          raise ValueError(f"Unknown tool: {name}")
      
      if not arguments:
          raise ValueError("Missing arguments")
  
      # Extract arguments
      contents = arguments.get("contents")
      input_file = arguments.get("input_file")
      output_file = arguments.get("output_file")
      template = arguments.get("template")
      
      # Validate input parameters
      if not contents and not input_file:
          raise ValueError("Either 'contents' or 'input_file' must be provided")
      
      if not output_file:
          raise ValueError("output_file path is required")
      
      # Validate template if provided
      if template and not os.path.exists(template):
          raise ValueError(f"Template document not found: {template}")
      
      try:
          # Create output directory if it doesn't exist
          output_path = Path(output_file)
          output_path.parent.mkdir(parents=True, exist_ok=True)
          
          # Prepare conversion arguments
          extra_args = []
          
          # Add diagram filter by default
          if DIAGRAM_FILTER_PATH.exists():
              extra_args.extend(["--lua-filter", str(DIAGRAM_FILTER_PATH)])
          
          # Handle template for pptx format
          if template:
              extra_args.extend(["--reference-doc", template])
          
          # Convert content using pypandoc
          if input_file:
              if not os.path.exists(input_file):
                  raise ValueError(f"Input file not found: {input_file}")
              
              pypandoc.convert_file(
                  input_file,
                  "pptx",
                  outputfile=output_file,
                  extra_args=extra_args
              )
          else:
              pypandoc.convert_text(
                  contents,
                  "pptx",
                  format="markdown",
                  outputfile=output_file,
                  extra_args=extra_args
              )
          
          result_message = f"Markdown successfully converted to PPTX and saved to: {output_file}"
          
          return [
              types.TextContent(
                  type="text",
                  text=result_message
              )
          ]
          
      except Exception as e:
          error_msg = f"Error converting markdown to PPTX: {str(e)}"
          raise ValueError(error_msg)

• src/mcp_pandoc_md2pptx/server.py:73-98 (schema)

  The inputSchema for the 'convert-contents' tool defines four properties: contents (markdown string), input_file (path to .md file), output_file (required PPTX output path), and template (optional PPTX template path). Uses oneOf to require either contents+output_file or input_file+output_file.

      inputSchema={
          "type": "object",
          "properties": {
              "contents": {
                  "type": "string",
                  "description": "Markdown content to be converted (required if input_file not provided)"
              },
              "input_file": {
                  "type": "string",
                  "description": "Complete path to Markdown input file (e.g., '/path/to/input.md')"
              },
              "output_file": {
                  "type": "string",
                  "description": "Complete path where to save the PPTX output including filename and .pptx extension (required)"
              },
              "template": {
                  "type": "string",
                  "description": "Path to a template PPTX document to use for styling"
              }
          },
          "oneOf": [
              {"required": ["contents", "output_file"]},
              {"required": ["input_file", "output_file"]}
          ]
      },
  )

• src/mcp_pandoc_md2pptx/server.py:21-99 (registration)

  The 'convert-contents' tool is registered via the handle_list_tools function decorated with @server.list_tools(), returning a types.Tool with name='convert-contents' and its description/inputSchema.

      return [
          types.Tool(
              name="convert-contents",
              description=(
                  "Converts Markdown content to PowerPoint (PPTX) format.\n\n"
                  "🚨 REQUIREMENTS:\n"
                  "1. Input: Only Markdown format is supported\n"
                  "2. Output: Only PPTX format is supported\n"
                  "3. File Path: Complete output path with filename and .pptx extension is required\n\n"
                  "✅ Usage Example:\n"
                  "'Convert this markdown to PowerPoint and save as /presentations/demo.pptx'\n\n"
                  "🎨 PPTX STYLING:\n"
                  "* Use template parameter to apply custom PowerPoint templates\n"
                  "* Create templates with your branding, fonts, and slide layouts\n"
                  "* Example: 'Convert markdown to PPTX using /templates/theme.pptx as template and save as /presentations/pitch.pptx'\n\n"
                  "➡️ Diagram Support:\n"
                  "* Diagram using mermaid, plantuml, graphviz is supported by default. Referencing external resource in plantuml is also supported.\n"
                  """* Example: \n```plantuml
  @startuml Two Modes - Technical View
  ' Uncomment the line below for "dark mode" styling
  '!$AWS_DARK = true
  
  !define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v20.0/dist
  !include AWSPuml/AWSCommon.puml
  
  !include AWSPuml/AWSSimplified.puml
  !include AWSPuml/General/Users.puml
  !include AWSPuml/NetworkingContentDelivery/APIGateway.puml
  !include AWSPuml/SecurityIdentityCompliance/Cognito.puml
  !include AWSPuml/Compute/Lambda.puml
  !include AWSPuml/Database/DynamoDB.puml
  
  left to right direction
  
  Users(sources, "Events", "millions of users")
  APIGateway(votingAPI, "Voting API", "user votes")
  Cognito(userAuth, "User Authentication", "jwt to submit votes")
  Lambda(generateToken, "User Credentials", "return jwt")
  Lambda(recordVote, "Record Vote", "enter or update vote per user")
  DynamoDB(voteDb, "Vote Database", "one entry per user")
  
  sources --> userAuth
  sources --> votingAPI
  userAuth <--> generateToken
  votingAPI --> recordVote
  recordVote --> voteDb
  @enduml
  ```\n\n"""
                  "📋 Creating Reference Documents:\n"
                  "* Generate PPTX template: pandoc -o template.pptx --print-default-data-file reference.pptx\n"
                  "* Customize in PowerPoint: fonts, colors, slide layouts\n"
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "contents": {
                          "type": "string",
                          "description": "Markdown content to be converted (required if input_file not provided)"
                      },
                      "input_file": {
                          "type": "string",
                          "description": "Complete path to Markdown input file (e.g., '/path/to/input.md')"
                      },
                      "output_file": {
                          "type": "string",
                          "description": "Complete path where to save the PPTX output including filename and .pptx extension (required)"
                      },
                      "template": {
                          "type": "string",
                          "description": "Path to a template PPTX document to use for styling"
                      }
                  },
                  "oneOf": [
                      {"required": ["contents", "output_file"]},
                      {"required": ["input_file", "output_file"]}
                  ]
              },
          )
      ]