Lab 06 - 09: Prompt Handlers

#!/usr/bin/env python3
"""
Complete MCP (Model Context Protocol) Server Implementation
Built step by step for learning purposes.
Step 9: Register Prompt Handlers
"""

import asyncio
import json
from typing import Any, Optional

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import (
  Tool,
  Resource,
  Prompt,
  TextContent,
  ImageContent,
  EmbeddedResource,
)
import sys

class CompleteMCPServer:
  """
  A comprehensive MCP Server implementation showcasing all protocol features.

  This class demonstrates:
  - Server initialization
  - Tool registration and execution
  - Resource management
  - Prompt templates
  - Request handling
  """

  def __init__(self):
    """Initialize the MCP Server instance."""
    self.server = Server("complete-mcp-server")
    self.data_store = {}  # Simple in-memory data storage
    print("Server instance created successfully!")

  def register_tools(self):
    """Register all available tools with the MCP server."""

    @self.server.list_tools()
    async def list_tools() -> list[Tool]:
      """
      Return the list of available tools.
      This is called when clients want to discover what tools are available.
      """
      return [
        Tool(
          name="calculate",
          description="Perform mathematical operations (add, subtract, multiply, divide)",
          inputSchema={
            "type": "object",
            "properties": {
              "operation": {
                "type": "string",
                "enum": ["add", "subtract", "multiply", "divide"],
                "description": "The operation to perform"
              },
              "a": {
                "type": "number",
                "description": "First number"
              },
              "b": {
                "type": "number",
                "description": "Second number"
              }
            },
            "required": ["operation", "a", "b"]
          }
        ),
        Tool(
          name="store_data",
          description="Store a key-value pair in the server's data store",
          inputSchema={
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "description": "The key to store"
              },
              "value": {
                "type": "string",
                "description": "The value to store"
              }
            },
            "required": ["key", "value"]
          }
        ),
        Tool(
          name="retrieve_data",
          description="Retrieve a value from the server's data store",
          inputSchema={
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "description": "The key to retrieve"
              }
            },
            "required": ["key"]
          }
        ),
        Tool(
          name="echo",
          description="Echo back the input text",
          inputSchema={
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "description": "Text to echo back"
              }
            },
            "required": ["text"]
          }
        )
      ]

    print("Tools registered: calculate, store_data, retrieve_data, echo")

  def register_tool_handlers(self):
    """Implement the actual logic for each tool."""

    @self.server.call_tool()
    async def call_tool(name: str, arguments: Any) -> list[TextContent]:
      """
      Handle tool execution requests.
      This is called when a client wants to execute a tool.
      """
      if name == "calculate":
        operation = arguments.get("operation")
        a = arguments.get("a")
        b = arguments.get("b")

        if operation == "add":
          result = a + b
        elif operation == "subtract":
          result = a - b
        elif operation == "multiply":
          result = a * b
        elif operation == "divide":
          if b == 0:
            return [TextContent(
              type="text",
              text="Error: Cannot divide by zero"
            )]
          result = a / b
        else:
          return [TextContent(
            type="text",
            text=f"Error: Unknown operation '{operation}'"
          )]

        return [TextContent(
          type="text",
          text=f"Result: {a} {operation} {b} = {result}"
        )]

      elif name == "store_data":
        key = arguments.get("key")
        value = arguments.get("value")
        self.data_store[key] = value
        return [TextContent(
          type="text",
          text=f"Stored: {key} = {value}"
        )]

      elif name == "retrieve_data":
        key = arguments.get("key")
        value = self.data_store.get(key)
        if value is None:
          return [TextContent(
            type="text",
            text=f"Error: Key '{key}' not found"
          )]
        return [TextContent(
          type="text",
          text=f"Retrieved: {key} = {value}"
        )]

      elif name == "echo":
        text = arguments.get("text")
        return [TextContent(
          type="text",
          text=f"Echo: {text}"
        )]

      else:
        return [TextContent(
          type="text",
          text=f"Error: Unknown tool '{name}'"
        )]

    print("Tool handlers implemented")

  def register_resources(self):
    """Register resources that clients can access."""

    @self.server.list_resources()
    async def list_resources() -> list[Resource]:
      """
      Return the list of available resources.
      This is called when clients want to discover what resources are available.
      """
      return [
        Resource(
          uri="resource://server-info",
          name="Server Information",
          description="Information about this MCP server",
          mimeType="application/json"
        ),
        Resource(
          uri="resource://data-store",
          name="Data Store",
          description="Current contents of the data store",
          mimeType="application/json"
        ),
        Resource(
          uri="resource://welcome",
          name="Welcome Message",
          description="Welcome message and server capabilities",
          mimeType="text/plain"
        )
      ]

    print("Resources registered: server-info, data-store, welcome")

  def register_resource_handlers(self):
    """Implement resource retrieval logic."""

    @self.server.read_resource()
    async def read_resource(uri: Any) -> str:
      """
      Handle resource read requests.
      This is called when a client wants to read a resource.
      """
      # Extract the URI string from the AnyUrl object
      uri_str = str(uri)

      if uri_str == "resource://server-info":
        info = {
          "name": "complete-mcp-server",
          "version": "1.0.0",
          "description": "A comprehensive MCP server implementation",
          "capabilities": {
            "tools": 4,
            "resources": 3,
            "prompts": 2
          }
        }
        return json.dumps(info, indent=2)

      elif uri_str == "resource://data-store":
        return json.dumps(self.data_store, indent=2)

      elif uri_str == "resource://welcome":
        return """Welcome to the Complete MCP Server!

This server demonstrates all MCP protocol capabilities:
- Tools: Execute operations and computations
- Resources: Access data and information
- Prompts: Get structured prompt templates

Explore the available tools and resources to see what this server can do."""

      else:
        raise ValueError(f"Unknown resource: {uri_str}")

    print("Resource handlers implemented")

  def register_prompts(self):
    """Register prompt templates for clients."""

    @self.server.list_prompts()
    async def list_prompts() -> list[Prompt]:
      """
      Return the list of available prompts.
      This is called when clients want to discover what prompts are available.
      """
      return [
        Prompt(
          name="analyze-data",
          description="Analyze data stored in the server",
          arguments=[
            {
              "name": "key",
              "description": "The key of the data to analyze",
              "required": True
            }
          ]
        ),
        Prompt(
          name="calculate-scenario",
          description="Walk through a calculation scenario",
          arguments=[
            {
              "name": "operation",
              "description": "The operation to demonstrate (add, subtract, multiply, divide)",
              "required": True
            }
          ]
        )
      ]

    print("Prompts registered: analyze-data, calculate-scenario")

  def register_prompt_handlers(self):
    """Implement prompt generation logic."""

    @self.server.get_prompt()
    async def get_prompt(name: str, arguments: dict) -> list[TextContent]:
      """
      Handle prompt generation requests.
      This is called when a client wants to get a prompt.
      """
      if name == "analyze-data":
        key = arguments.get("key", "unknown")
        value = self.data_store.get(key, "not found")

        prompt_text = f"""Analyze the following data from the server:

Key: {key}
Value: {value}

Please provide:
1. A description of what this data represents
2. Any patterns or insights you notice
3. Suggestions for how this data could be used

Use the retrieve_data tool if you need to fetch additional context."""

        return [TextContent(type="text", text=prompt_text)]

      elif name == "calculate-scenario":
        operation = arguments.get("operation", "add")

        prompt_text = f"""Let's work through a {operation} calculation scenario.

Use the calculate tool with the operation '{operation}'.
For example:
- Choose two numbers (a and b)
- Execute: calculate(operation="{operation}", a=10, b=5)
- Explain the result

This demonstrates how to use computational tools in the MCP server."""

        return [TextContent(type="text", text=prompt_text)]

      else:
        return [TextContent(
          type="text",
          text=f"Error: Unknown prompt '{name}'"
        )]

    print("Prompt handlers implemented")

  async def run(self):
    """Run the MCP server."""
    # Initialize everything
    self.register_tools()
    self.register_tool_handlers()
    self.register_resources()
    self.register_resource_handlers()
    self.register_prompts()
    self.register_prompt_handlers()

    # Connect to stdio
    async with stdio_server() as (read_stream, write_stream):
      print("Server running on stdio...")
      await self.server.run(
        read_stream,
        write_stream,
        self.server.create_initialization_options()
      )

async def main():
  """Main entry point."""
  server = CompleteMCPServer()
  await server.run()

if __name__ == "__main__":
  try:
    asyncio.run(main())
  except KeyboardInterrupt:
    print("Server stopped by user")
  except Exception as e:
    print(f"Error: {e}")
    sys.exit(1)