Build an MCP server

"""Sample MCP server for Kothadesk: a small online shop with three tools.

Run it, expose it over https, and connect it on a bot's Tools page (Add MCP server):

* ``search_products``  read-only: anyone can ask what is in stock.
* ``get_my_orders``    read-only: only for signed-in customers. Kothadesk sends the signed-in
                       user's id in the ``X-Kothadesk-End-User`` header; the model never
                       chooses whose orders it sees.
* ``start_return``     changes something: Kothadesk asks the visitor to confirm first.

Every request must carry ``Authorization: Bearer <MCP_TOKEN>`` (set in Kothadesk as the
server's Bearer token). The data is in memory; replace the three functions with calls to
your own database or API.
"""

import os
import secrets
from datetime import date, timedelta
from typing import Any

import uvicorn
from mcp.server.mcpserver import Context, MCPServer
from mcp.server.transport_security import TransportSecuritySettings
from mcp_types import ToolAnnotations
from starlette.types import Receive, Scope, Send

MCP_TOKEN = os.environ.get("MCP_TOKEN", "")
END_USER_HEADER = "x-kothadesk-end-user"

PRODUCTS = [
    {"sku": "TEA-ASSAM-250", "name": "Assam CTC tea, 250 g", "price_inr": 180, "in_stock": True},
    {
        "sku": "TEA-GREEN-100",
        "name": "Darjeeling green tea, 100 g",
        "price_inr": 320,
        "in_stock": True,
    },
    {"sku": "MUG-CERAMIC", "name": "Ceramic mug, 350 ml", "price_inr": 250, "in_stock": False},
]

ORDERS: dict[str, list[dict[str, Any]]] = {
    # Keyed by your own user id: the "sub" claim of the identity token your site signs.
    "user_1001": [
        {
            "order_id": "ORD-48213",
            "status": "shipped",
            "items": ["TEA-ASSAM-250"],
            "delivered_on": None,
            "eta": str(date.today() + timedelta(days=2)),
        },
        {
            "order_id": "ORD-47790",
            "status": "delivered",
            "items": ["MUG-CERAMIC"],
            "delivered_on": str(date.today() - timedelta(days=3)),
            "eta": None,
        },
    ],
}

RETURN_WINDOW_DAYS = 7

mcp = MCPServer("sample-shop")


@mcp.tool(
    name="search_products",
    title="Search products",
    annotations=ToolAnnotations(read_only_hint=True),
)
def search_products(query: str) -> dict[str, Any]:
    """Find products by name and say whether they are in stock and what they cost."""
    words = query.lower().split()
    found = [p for p in PRODUCTS if all(w in p["name"].lower() for w in words)]
    return {"results": found or [], "count": len(found)}


@mcp.tool(
    name="get_my_orders",
    title="My orders",
    annotations=ToolAnnotations(read_only_hint=True),
)
def get_my_orders(ctx: Context) -> dict[str, Any]:
    """List the signed-in customer's recent orders with status and expected delivery date."""
    user = _end_user(ctx)
    if user is None:
        return {"error": "Please sign in to see your orders."}
    return {"orders": ORDERS.get(user, [])}


@mcp.tool(
    name="start_return",
    title="Start a return",
    annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False),
)
def start_return(order_id: str, reason: str, ctx: Context) -> dict[str, Any]:
    """Start a return for one of the signed-in customer's delivered orders.

    Only orders delivered in the last 7 days can be returned."""
    user = _end_user(ctx)
    if user is None:
        return {"error": "Please sign in to start a return."}
    order = next((o for o in ORDERS.get(user, []) if o["order_id"] == order_id), None)
    if order is None:
        return {"error": f"No order {order_id} on this account."}
    if order["status"] != "delivered" or order["delivered_on"] is None:
        return {"error": "Only delivered orders can be returned."}
    if date.fromisoformat(order["delivered_on"]) < date.today() - timedelta(
        days=RETURN_WINDOW_DAYS
    ):
        return {"error": f"The {RETURN_WINDOW_DAYS}-day return window has passed."}
    return {
        "return_id": f"RET-{secrets.randbelow(90000) + 10000}",
        "order_id": order_id,
        "reason": reason,
        "next_step": "We will email a pickup slot within 24 hours.",
    }


def _end_user(ctx: Context) -> str | None:
    """The signed-in customer's id, set by Kothadesk from your verified identity token."""
    headers = {k.lower(): v for k, v in (ctx.headers or {}).items()}
    return headers.get(END_USER_HEADER) or None


def build_app() -> Any:
    inner = mcp.streamable_http_app(
        stateless_http=True,
        json_response=True,
        # Kothadesk calls from its servers, so the Host header is your public host name.
        transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
    )

    async def app(scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] == "http":
            headers = {k.decode().lower(): v.decode() for k, v in scope.get("headers", [])}
            if not MCP_TOKEN or not secrets.compare_digest(
                headers.get("authorization", ""), f"Bearer {MCP_TOKEN}"
            ):
                await send(
                    {
                        "type": "http.response.start",
                        "status": 401,
                        "headers": [(b"content-type", b"application/json")],
                    }
                )
                await send({"type": "http.response.body", "body": b'{"error":"unauthorized"}'})
                return
        await inner(scope, receive, send)

    return app


if __name__ == "__main__":
    if not MCP_TOKEN:
        raise SystemExit("Set MCP_TOKEN to a long random value first.")
    # All interfaces: it runs in a container or behind your reverse proxy.
    uvicorn.run(build_app(), host="0.0.0.0", port=int(os.environ.get("PORT", "8000")))  # noqa: S104

mcp>=2.2,<3
uvicorn>=0.30

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .
ENV PORT=8000
EXPOSE 8000
USER nobody
CMD ["python", "server.py"]

/**
 * Sample MCP server for Kothadesk (Node.js): a small online shop with three tools.
 *
 * Run it, expose it over https, and connect it on a bot's Tools page (Add MCP server):
 *
 * - search_products  read-only: anyone can ask what is in stock.
 * - get_my_orders    read-only: only for signed-in customers. Kothadesk sends the signed-in
 *                    user's id in the X-Kothadesk-End-User header (turn on "Signed-in users only"
 *                    for this tool); the model never chooses whose orders it sees.
 * - start_return     changes something: Kothadesk asks the visitor to confirm first.
 *
 * Every request must carry "Authorization: Bearer <MCP_TOKEN>" (set in Kothadesk as the
 * server's Bearer token). The data is in memory; replace the three handlers with calls to
 * your own database or API.
 */
import { randomInt, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const MCP_TOKEN = process.env.MCP_TOKEN ?? "";
const PORT = Number(process.env.PORT ?? 8000);
const END_USER_HEADER = "x-kothadesk-end-user";
const RETURN_WINDOW_DAYS = 7;
const DAY = 24 * 60 * 60 * 1000;

const isoDate = (offsetDays) => new Date(Date.now() + offsetDays * DAY).toISOString().slice(0, 10);

const PRODUCTS = [
  { sku: "TEA-ASSAM-250", name: "Assam CTC tea, 250 g", price_inr: 180, in_stock: true },
  { sku: "TEA-GREEN-100", name: "Darjeeling green tea, 100 g", price_inr: 320, in_stock: true },
  { sku: "MUG-CERAMIC", name: "Ceramic mug, 350 ml", price_inr: 250, in_stock: false },
];

/** Keyed by your own user id: the "sub" claim of the identity token your site signs. */
const ORDERS = {
  user_1001: [
    { order_id: "ORD-48213", status: "shipped", items: ["TEA-ASSAM-250"], delivered_on: null, eta: isoDate(2) },
    { order_id: "ORD-47790", status: "delivered", items: ["MUG-CERAMIC"], delivered_on: isoDate(-3), eta: null },
  ],
};

/** A tool result: JSON text the assistant reads. */
const result = (data) => ({ content: [{ type: "text", text: JSON.stringify(data) }] });

/** The signed-in customer's id, set by Kothadesk from your verified identity token. */
function endUser(extra) {
  const value = extra.requestInfo?.headers?.[END_USER_HEADER];
  return (Array.isArray(value) ? value[0] : value) || null;
}

function buildServer() {
  const mcp = new McpServer({ name: "sample-shop", version: "1.0.0" });

  mcp.registerTool(
    "search_products",
    {
      title: "Search products",
      description: "Find products by name and say whether they are in stock and what they cost.",
      inputSchema: { query: z.string().describe("Words from the product name, for example assam tea") },
      annotations: { readOnlyHint: true },
    },
    async ({ query }) => {
      const words = query.toLowerCase().split(/\s+/).filter(Boolean);
      const found = PRODUCTS.filter((p) => words.every((w) => p.name.toLowerCase().includes(w)));
      return result({ results: found, count: found.length });
    },
  );

  mcp.registerTool(
    "get_my_orders",
    {
      title: "My orders",
      description: "List the signed-in customer's recent orders with status and expected delivery date.",
      annotations: { readOnlyHint: true },
    },
    async (extra) => {
      const user = endUser(extra);
      if (!user) return result({ error: "Please sign in to see your orders." });
      return result({ orders: ORDERS[user] ?? [] });
    },
  );

  mcp.registerTool(
    "start_return",
    {
      title: "Start a return",
      description:
        "Start a return for one of the signed-in customer's delivered orders. Only orders delivered in the last 7 days can be returned.",
      inputSchema: {
        order_id: z.string().describe("The order number, for example ORD-47790"),
        reason: z.string().describe("Why the customer is returning it"),
      },
      annotations: { readOnlyHint: false, destructiveHint: false },
    },
    async ({ order_id, reason }, extra) => {
      const user = endUser(extra);
      if (!user) return result({ error: "Please sign in to start a return." });
      const order = (ORDERS[user] ?? []).find((o) => o.order_id === order_id);
      if (!order) return result({ error: `No order ${order_id} on this account.` });
      if (order.status !== "delivered" || !order.delivered_on) {
        return result({ error: "Only delivered orders can be returned." });
      }
      if (Date.parse(order.delivered_on) < Date.now() - RETURN_WINDOW_DAYS * DAY) {
        return result({ error: `The ${RETURN_WINDOW_DAYS}-day return window has passed.` });
      }
      return result({
        return_id: `RET-${randomInt(10000, 100000)}`,
        order_id,
        reason,
        next_step: "We will email a pickup slot within 24 hours.",
      });
    },
  );

  return mcp;
}

function authorized(req) {
  const given = Buffer.from(req.headers.authorization ?? "");
  const expected = Buffer.from(`Bearer ${MCP_TOKEN}`);
  return given.length === expected.length && timingSafeEqual(given, expected);
}

async function readJson(req) {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const text = Buffer.concat(chunks).toString("utf8");
  return text ? JSON.parse(text) : undefined;
}

if (!MCP_TOKEN) {
  console.error("Set MCP_TOKEN to a long random value first.");
  process.exit(1);
}

createServer(async (req, res) => {
  if (!authorized(req)) {
    res.writeHead(401, { "content-type": "application/json" }).end('{"error":"unauthorized"}');
    return;
  }
  if (!req.url?.startsWith("/mcp")) {
    res.writeHead(404).end();
    return;
  }
  try {
    // Stateless: a fresh server and transport per request, answered as plain JSON.
    const server = buildServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
      enableJsonResponse: true,
    });
    res.on("close", () => {
      void transport.close();
      void server.close();
    });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.method === "POST" ? await readJson(req) : undefined);
  } catch (error) {
    console.error(error);
    if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" }).end('{"error":"internal"}');
  }
}).listen(PORT, () => console.log(`Sample MCP server on http://0.0.0.0:${PORT}/mcp`));

{
  "name": "kothadesk-sample-mcp-server",
  "version": "1.0.0",
  "private": true,
  "description": "Sample MCP server for Kothadesk: a small online shop with three tools",
  "type": "module",
  "main": "server.mjs",
  "scripts": {
    "start": "node server.mjs"
  },
  "engines": {
    "node": ">=20"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.30.1",
    "zod": "^4.1.0"
  }
}

FROM node:22-slim
WORKDIR /app
COPY package.json .
RUN npm install --omit=dev --no-audit --no-fund
COPY server.mjs .
ENV PORT=8000
EXPOSE 8000
USER node
CMD ["node", "server.mjs"]