MCPR: Rust implementation of Model Context Protocol

An MCP connection follows a strict lifecycle of three main stages:

1. Initialization: The Client sends an initialize request (containing protocol version and capabilities). The Server responds with its own capabilities and info. The Client then sends an initialized notification to acknowledge.
2. Message Exchange: The active phase where tool_call requests, request_input requests, and optional progress notifications are exchanged.
3. Termination: The connection is closed via a shutdown request and response to ensure a clean exit.

The Model Context Protocol (MCP) uses a client-server architecture to connect AI applications (Hosts) with tools and data sources.

• Host: The parent application (e.g., Claude Desktop, an IDE) that initiates the connection.
• Client: An entity embedded in the Host that maintains a 1:1 connection with a specific server.
• Server: A service that provides tools, context, and capabilities to the client.
• Tools: The specific functional units provided by the server (e.g., web search, code execution).

MCP supports different transport layers depending on whether the communication is local or over a network:

• Stdio Transport (Local): Used for local communication where the Client writes to the Server's stdin and reads from the Server's stdout.
• SSE Transport (Web): Used for web-based communication. The Client sends messages via HTTP POST /messages and the Server sends updates back via an SSE Event Stream.

For SSE (Server-Sent Events) transport, the server runs as a web service. The generated project includes a mock SSE implementation for testing.

1. Start the server (defaults to port 8080):

   ./server/target/debug/my-sse-project-server --port 8080

2. Connect the client using the --uri flag:

   ./client/target/debug/my-sse-project-client --uri "http://localhost:8080"

Clients also support an --interactive mode for manual testing and a one-shot mode using --name <name>.

To use MCPR in your Rust project, add it to your Cargo.toml dependencies.

Important: Avoid version 0.2.0 as it has been yanked due to critical SSE transport issues. Use version 0.2.3 or later.

To use the CLI tools (like the project generator), install the package globally using cargo install.

[dependencies]
mcpr = "0.2.3"

cargo install mcpr

For stdio transport, the server communicates via standard input/output. You can run the server and pipe its output directly to the client, or run them in separate terminals using a URI.

Piping method:

./server/target/debug/my-stdio-project-server | ./client/target/debug/my-stdio-project-client

URI method:

1. Run the server in one terminal.
2. Run the client in another terminal using the --uri flag pointing to the server executable.

./client/target/debug/my-stdio-project-client --uri "stdio://./server/target/debug/my-stdio-project-server"

The server can be run in two modes:

1. Standalone process: Runs in the foreground.
2. Background process: Runs in the background, redirecting output to a log file. This is useful for testing multiple clients connecting to a single server instance.

# Option 1: Start the server as a standalone process
cd server
cargo run

# Option 2: Start the server in the background
cd server
./target/debug/github-tools-server < /dev/null > server_output.log 2>&1 &

To see detailed information about the MCP protocol exchange and internal state, set the RUST_LOG environment variable to debug or trace when running your server or client.

RUST_LOG=debug cargo run

You can use the github-tools structure as a template for your own MCP application.

1. Scaffold the directory structure:

   mkdir -p my-mcp-project/{client,server}/src
   cp examples/github-tools/client/Cargo.toml my-mcp-project/client/
   cp examples/github-tools/server/Cargo.toml my-mcp-project/server/

2. Customize the Client: Update Cargo.toml and create a new main.rs in my-mcp-project/client/src/.
3. Implement Server Tools: Update the server's Cargo.toml and create a new main.rs in my-mcp-project/server/src/. To add new functionality, create new structs that implement the Tool trait.
4. Test: Build the server, connect with your client, and verify tool execution.