Examples
========

The mcp-cpp-sdk includes several example programs demonstrating different aspects
of the SDK and various usage patterns. All examples are located in the ``examples/``
directory.

Overview
--------

The SDK builds nine core examples plus 12 specialized feature examples:

1. **server_stdio** - Full-featured MCP server over stdio
2. **server_simple** - Minimal MCP server over stdio
3. **client_stdio** - MCP client demonstrating representative server operations
4. **interactive_client** - Interactive stdio client
5. **server_with_sampling** - Server with reverse RPC (sampling)
6. **echo_websocket** - WebSocket transport example
7. **http_loopback** - HTTP transport loopback demo
8. **llama_server** - llama.cpp MCP adapter
9. **debugger_server** - LLDB debugger MCP server (uses stubs when LLDB is unavailable)

Feature Examples
----------------

The ``examples/features/`` directory contains 12 specialized examples. They use
small, self-contained setups to demonstrate individual capabilities; some use
in-memory loopback and others exercise local network transports.

1. **progress_cancellation** - Real-time progress updates and request cancellation
2. **notifications_subscriptions** - Server-to-client notifications and subscription handling
3. **middleware** - Intercepting and processing requests via a middleware chain
4. **completions** - Argument completion suggestions for tools
5. **pagination** - Handling large lists via cursor-based pagination
6. **elicitation** - Server-initiated information requests (input forms)
7. **roots** - Declaring and discovering client-side root URIs
8. **error_handling** - Robust error patterns and exception management
9. **transport_memory** - Using in-memory transports for testing and modularity
10. **graceful_shutdown** - Clean exit patterns and signal handling
11. **http_server_convenience** - Simplified HTTP server setup via ``Server::run_http()``
12. **oauth_flow** - Loopback OAuth building blocks (discovery, PKCE, exchange, refresh)

These examples are non-interactive and designed to be run as part of a
test suite or to understand specific API patterns.

Benchmarks
----------

These examples exercise different transport paths and report measurements from
the local run. They are teaching benchmarks that run locally and in CI; for
sustained multi-service load testing, use the separate ``benchmark/`` suite.

1. **benchmark_stdio** - Measures roundtrip latency and throughput over the in-memory stdio-equivalent transport
2. **benchmark_http** - Performance analysis of the HTTP transport layer
3. **benchmark_websocket** - Benchmarking WebSocket communication throughput

Each benchmark performs a fixed number of iterations and reports total time,
average latency, and calls per second. The current examples run 1000 iterations
for the memory and HTTP transports, and 50 iterations for the WebSocket
transport to keep the automated run bounded.

Use the example closest to your integration as an API reference, then add the
deployment-specific validation, security, and error handling your application
requires.

server_stdio
------------

**Location**: ``examples/servers/stdio/server_stdio.cpp``

A complete MCP server implementation demonstrating:

* **All 4 handler signatures**: Async with context, async without context, sync with context, sync without context
* **Custom types**: JsonSerializable structs with to_json/from_json
* **Tools**: Typed add/greet handlers and JSON echo/uppercase handlers
* **Resources**: A typed static resource handler
* **Resource Templates**: Metadata registration for a URI template
* **Prompts**: Example prompt with arguments
* **Context logging**: Using ``Context::log_info()`` and other log levels

This example combines the main server registration patterns in one program.

**Key patterns demonstrated**:

* Type-safe tool handlers with custom input/output types
* Resource listing and reading
* Resource template metadata listing
* Prompt registration and retrieval
* Structured logging via Context

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-server-stdio

client_stdio
------------

**Location**: ``examples/clients/stdio/client_stdio.cpp``

A stdio MCP client demonstrating:

* **Connection**: Initialize handshake with server capabilities
* **Tools**: List available tools, call tools with typed arguments
* **Resources**: List resources, read resource contents
* **Resource Templates**: List template metadata
* **Prompts**: List prompts, get prompt with arguments
* **Completion**: Request completion suggestions
* **Notifications**: Send notifications to server

**Key patterns demonstrated**:

* Client initialization and capability negotiation
* Calling server methods with typed parameters
* Handling server responses
* Handling typed content variants in server responses

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-client-stdio

server_with_sampling
--------------------

**Location**: ``examples/advanced/server_with_sampling.cpp``

Demonstrates **reverse RPC** (server-to-client calls) via ``Context::sample_llm()``:

* **Server capabilities**: Declares tool support with change notifications
* **Sampling tool**: Tool handler that calls back to the client via ``ctx.sample_llm()``
* **Async context handlers**: Using ``Context&`` parameter for reverse RPC

This example shows how a server can request LLM sampling from a connected client,
enabling bidirectional communication patterns.

**Key patterns demonstrated**:

* Relying on the connected client to advertise its sampling capability
* Using ``Context::sample_llm()`` for reverse RPC
* Awaiting client responses within a tool handler
* Reading text content from the sampling response

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-server-sampling

echo_websocket
--------------

**Location**: ``examples/advanced/echo_websocket.cpp``

In-process loopback demonstration using **WebSocket transport** over TCP:

* **WebSocket transport**: Using ``WebSocketServerTransport`` and
  ``WebSocketClientTransport`` instead of stdio
* **Server + Client**: Both running in the same process
* **TCP acceptor**: Server listens on localhost port
* **Echo tool**: Simple echo tool that returns its input

This example shows how to use the WebSocket transport layer for network-based
MCP communication.

**Key patterns demonstrated**:

* Creating WebSocket transports from Boost.Beast streams
* Running server and client concurrently in one process
* TCP acceptor setup for WebSocket connections
* Same API for both stdio and WebSocket transports

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-echo-websocket

http_loopback
-------------

**Location**: ``examples/advanced/http_loopback.cpp``

In-process loopback demonstration using **Streamable HTTP transport**:

* **HttpServerTransport + HttpClientTransport**: Full HTTP stack for MCP communication
* **Anti-hang co_spawn pattern**: Safe concurrent server/client execution
* **MCP-Protocol-Version header**: Support for versioned HTTP headers (e.g., ``2025-11-25``)

This example shows how to use the HTTP transport layer for network-based
MCP communication with standard headers.

**Key patterns demonstrated**:

* Using ``HttpServerTransport`` and ``HttpClientTransport``
* Handling HTTP-specific MCP headers
* Coordinating server and client lifecycle in a single process

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-http-loopback

llama_server
------------

**Location**: ``examples/advanced/llama/llama_server.cpp``

MCP adapter for llama.cpp's ``llama-server`` (chat, completion, embedding):

* **External HTTP API integration**: Communicating with llama.cpp via Boost.Beast
* **Dual transport support**: Runtime selection between stdio and HTTP transports
* **CLI argument parsing**: Comprehensive configuration via command line flags

This example demonstrates how to wrap an existing external service in an MCP
server with stdio and HTTP deployment options.

**Key patterns demonstrated**:

* Asynchronous HTTP client requests within tool handlers
* Exposing external service capabilities (LLM) as MCP tools and resources
* Flexible transport configuration and CLI parameter management

**Build and run**:

.. code-block:: bash

   python scripts/build.py --examples
   ./build/release/example-llama-mcp
   # or with HTTP transport:
   ./build/release/example-llama-mcp --transport=http

debugger_server
---------------

**Location**: ``examples/advanced/debugger/debugger_server.cpp``

MCP server wrapping LLDB's SB API for programmatic debugging:

* **Optional external dependency**: Integration with ``liblldb``
* **LLDB SB API integration**: Tools for launching, attaching, stepping, and evaluation
* **Resource templates**: Dynamic discovery of threads and stack frames
* **RAII lifecycle management**: Safe initialization and termination of LLDB

This example shows how to build a complex MCP server that provides deep
integration with system-level debugging tools.

**Key patterns demonstrated**:

* Managing external library state within an MCP server
* Using resource templates for dynamic metadata discovery
* Implementing complex interactive workflows (debugging) via tools

**Build and run**:

.. code-block:: bash

   cmake -DBUILD_LLDB_EXAMPLE=ON -B build && cmake --build build
   ./build/release/example-debugger-server

Note: Requires ``-DBUILD_LLDB_EXAMPLE=ON`` and LLDB development libraries installed.

Building All Examples
---------------------

To build all examples at once:

.. code-block:: bash

   # Using build script (recommended)
   python scripts/build.py --examples

   # Or using CMake directly
   cmake -DBUILD_EXAMPLES=ON -B build && cmake --build build

   # Note: The debugger example is OFF by default:
   # cmake -DBUILD_LLDB_EXAMPLE=ON -B build && cmake --build build

All example binaries will be located in ``build/``.

Using Examples as Templates
---------------------------

Each example is designed to be self-contained and can be copied as a starting
point for your own applications:

1. Copy the example file to your project
2. Modify the server/client capabilities as needed
3. Add your custom tools, resources, or prompts
4. Update the CMakeLists.txt to include your new source file

For more details on the API used in these examples, see the :doc:`api/index`.