{
  "sample": true,
  "sample_notice": "SAMPLE / illustrative AI Build case study. The client scenario is anonymized and generic. No real client name is used and no performance metric is invented. File/tool counts describe this sample artifact, not a customer outcome.",
  "deliverable": "AI Build",
  "price_usd": 499,
  "payment_methods": ["stripe_card", "x402_usdc_testnet"],
  "title": "AI Build Case Study: A Read-Only MCP Server Wrapping an Existing REST API",
  "slug": "sample-mcp-server-build-casestudy-2026-06-17",
  "scenario": "A mid-size SaaS team runs a stable internal REST API for product catalog and order lookup. They want an AI assistant to answer 'what's the status of order X?' and 'is product Y in stock?' directly, read-only, without rebuilding anything. The right-sized solution is a thin read-only MCP server that wraps the existing API so any MCP-compatible assistant can discover and call a few safe, well-described tools.",
  "scope": {
    "in_scope": [
      "Read-only MCP server (stdio + HTTP transport) over the existing REST API",
      "4 tools: get_order_status, search_products, get_product_stock, list_recent_orders",
      "Self-describing JSON schemas for every tool input/output",
      "Auth pass-through via API key from environment (never hard-coded)",
      "Input validation and safe error messages (no internal stack traces leaked)",
      "README with connect instructions for an MCP-compatible client",
      "Smoke test script that lists tools and exercises each one",
      "One revision round"
    ],
    "out_of_scope": [
      "Any write/mutate operations (create/update/delete)",
      "Changes to the underlying REST API",
      "Hosting / production deployment (handoff is repo + run instructions)",
      "Long-lived support contract beyond the included revision round"
    ]
  },
  "build_phases": [
    {"phase": 1, "name": "Discovery & schema design", "detail": "Read the existing REST API's documented endpoints, selected four read paths mapping to support questions, designed strict typed input schemas so an agent can call them correctly without prompt hand-holding."},
    {"phase": 2, "name": "Server scaffold", "detail": "Stood up an MCP server using the official SDK pattern: register tools with name, description, and input schema; transport over stdio for local clients and HTTP for remote ones."},
    {"phase": 3, "name": "Wrapping logic", "detail": "Each tool maps to one REST call; responses filtered to needed fields; errors normalized into clear messages; upstream API key read from environment, never embedded."},
    {"phase": 4, "name": "Safety pass", "detail": "Confirmed no write surface, validated inputs reject malformed args, ensured failures return a clean message rather than leaking internals."},
    {"phase": 5, "name": "Test & handoff", "detail": "Smoke script lists all tools and runs each against a sandbox; README explains how to connect from an MCP-compatible client."}
  ],
  "files_delivered": [
    {"path": "src/index.ts", "purpose": "MCP server entry; registers tools, wires stdio + HTTP transport"},
    {"path": "src/tools/orders.ts", "purpose": "get_order_status, list_recent_orders"},
    {"path": "src/tools/products.ts", "purpose": "search_products, get_product_stock"},
    {"path": "src/lib/rest-client.ts", "purpose": "thin REST wrapper; reads API_KEY from env"},
    {"path": "src/lib/schemas.ts", "purpose": "input/output JSON schemas for all four tools"},
    {"path": "scripts/smoke-test.mjs", "purpose": "lists tools and exercises each against a sandbox"},
    {"path": ".env.example", "purpose": "required env vars (API base URL, API key) documented"},
    {"path": "README.md", "purpose": "connect instructions + run/test steps"}
  ],
  "artifact_stats": {
    "file_count": 8,
    "tool_count": 4,
    "all_tools_read_only": true,
    "transports": ["stdio", "http"],
    "note": "These counts describe the sample artifact itself, not a customer result."
  },
  "tools": [
    {
      "name": "get_order_status",
      "description": "Look up the current status of an order by its ID. Read-only.",
      "inputSchema": {"type": "object", "properties": {"order_id": {"type": "string", "description": "The order identifier"}}, "required": ["order_id"]}
    },
    {
      "name": "search_products",
      "description": "Search the product catalog by keyword. Read-only.",
      "inputSchema": {"type": "object", "properties": {"query": {"type": "string", "description": "Search keywords"}, "limit": {"type": "integer", "description": "Max results (optional)"}}, "required": ["query"]}
    },
    {
      "name": "get_product_stock",
      "description": "Return current stock level for a product. Read-only.",
      "inputSchema": {"type": "object", "properties": {"product_id": {"type": "string", "description": "The product identifier"}}, "required": ["product_id"]}
    },
    {
      "name": "list_recent_orders",
      "description": "List recent orders, most recent first. Read-only.",
      "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer", "description": "Max orders to return (optional)"}}, "required": []}
    }
  ],
  "outcome": "The deliverable lets any MCP-compatible assistant discover the four tools at runtime and answer order-status and stock questions by calling the existing API directly, with no write access and no change to the backend. The MCP layer is purely additive: existing REST clients keep working unchanged. No customer performance figures are published; this describes the capability delivered, not a specific metric.",
  "why_this_shape": "Wrapping an existing REST API in an MCP server is a common, low-cost pattern: the business logic stays put and is exposed to AI agents through self-describing schemas rather than being rebuilt. Read-only scope keeps the security surface minimal, the right default when the consumer is an autonomous agent.",
  "key_points": [
    "Right-sized $499 build: a thin, read-only MCP server wrapping an API the team already runs.",
    "Fixed scope: 4 read-only tools with strict self-describing schemas; writes and hosting excluded.",
    "Safety-first: env-based auth, input validation, no leaked internals, no mutate surface.",
    "Delivered as a small testable repo (8 files, smoke test, README) with run instructions.",
    "Additive architecture: existing REST clients keep working; the MCP layer serves AI agents in parallel.",
    "No real client names and no invented metrics; illustrative scenario only."
  ],
  "sources": [
    {"ref": 1, "title": "Model Context Protocol — official documentation", "publisher": "modelcontextprotocol.io", "url": "https://modelcontextprotocol.io/", "type": "primary_spec_docs"},
    {"ref": 2, "title": "Model Context Protocol specification", "publisher": "modelcontextprotocol.io", "url": "https://spec.modelcontextprotocol.io/", "type": "primary_spec"}
  ],
  "published_at": "2026-06-17T11:10:00.000Z",
  "author": "SaSame SRL (EU / Romania AI-native studio)",
  "generator": "sasame-build-agent",
  "agent_card": "https://live-vps.sasame.online/.well-known/agent-card.json",
  "public_mcp": "https://live-vps.sasame.online/public-mcp",
  "mcp_registry": "online.sasame/research",
  "contact": "consulting@srl-sasame.com"
}