Building a Server: Tools, Resources & Prompts

# Colab cell 1 — run once. Installs the official 'mcp' SDK. No external
# API needed: the tool queries an in-memory store so you can see it run.
!pip install -q mcp

import os

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders-server")

# Server-side secret: read from the environment, used only inside tool
# bodies, and NEVER placed in a schema, description, or response — the
# model never sees it. A real server passes this to httpx; here we query
# an in-memory store instead so the cell runs offline.
API_KEY = os.environ.get("ORDERS_API_KEY", "dev-key-not-real")

ORDERS = [
    {"id": "A1001", "customer": "Acme",     "status": "open",      "total": 250, "note": "late delivery reported"},
    {"id": "A1002", "customer": "Globex",   "status": "shipped",   "total": 80,  "note": "on time"},
    {"id": "A1003", "customer": "Initech",  "status": "open",      "total": 420, "note": "late delivery, wants refund"},
    {"id": "A1004", "customer": "Umbrella", "status": "cancelled", "total": 15,  "note": "duplicate order"},
]


@mcp.tool()
def search_orders(query: str, status: str = "open", limit: int = 10) -> str:
    """Search customer orders by free-text query and status.

    Returns up to 'limit' order summaries (id, customer, status, total).
    Use for questions about order history or finding a specific order.
    Do NOT use for refunds or edits -- this tool is read-only.
    """
    if status not in {"open", "shipped", "cancelled"}:
        # instructive error the model can act on -- not a stack trace
        return (f"Error: unknown status {status!r}. Valid values: "
                "open, shipped, cancelled.")
    q = query.lower()
    hits = [o for o in ORDERS
            if o["status"] == status and q in o["note"].lower()][:limit]
    lines = [f"{o['id']} | {o['customer']} | {o['status']} | {o['total']}"
             for o in hits]
    return "\n".join(lines) if lines else "No orders matched."


# In production, mcp.run() serves the server over stdio and a host spawns it;
# in Colab that would block forever. Because @mcp.tool() leaves the function
# a normal callable, we invoke it directly to see the EXACT text the model
# would receive as the tool result:
print(search_orders("late delivery", status="open"))
print("--- unknown status ---")
print(search_orders("late delivery", status="pending"))

# Colab cell 2 — run cell 1 first (it defines mcp and ORDERS).
def fetch_recent(customer_id: str) -> str:     # stub for your real API call
    hits = [o for o in ORDERS if o["customer"].lower() == customer_id.lower()]
    return "\n".join(f"{o['id']} | {o['status']} | {o['total']}"
                      for o in hits) or f"No orders for {customer_id!r}."


@mcp.resource("orders://status-codes")
def status_codes() -> str:
    """Reference: every order status code and its meaning."""
    return ("open: placed, not yet shipped\n"
            "shipped: with carrier\n"
            "cancelled: cancelled before shipment")


@mcp.resource("orders://recent/{customer_id}")
def recent_orders(customer_id: str) -> str:
    """The 5 most recent orders for one customer, as a summary."""
    return fetch_recent(customer_id)     # your API call


@mcp.prompt()
def order_investigation(order_id: str) -> str:
    """Template for investigating a problematic order end to end."""
    return (f"Investigate order {order_id}. Steps: (1) fetch the order "
            f"and its status history; (2) check shipping events; "
            f"(3) summarize what went wrong and draft a customer reply. "
            f"Cite specific timestamps.")


# each primitive is a normal callable too — see what each returns:
print("[resource] status_codes:\n" + status_codes())
print("\n[resource] recent_orders('Acme'):\n" + recent_orders("Acme"))
print("\n[prompt] order_investigation('A1003'):\n" + order_investigation("A1003"))