Skip to content
Back to search

mcpr

Model Context Protocol (MCP) implementation in Rust

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conikeec--mcpr/badge.svg)](/listings/conikeec--mcpr)

HTML

<a href="/listings/conikeec--mcpr"><img src="/api/listings/conikeec--mcpr/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Add MCPR to your `Cargo.toml`:

[dependencies]
mcpr = "0.2.3"  # Make sure to use 0.2.3 or later, as 0.2.0 has been yanked

For CLI tools, install globally:

cargo install mcpr

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 490 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCPR - Model Context Protocol for Rust
  2. A Rust implementation of Anthropic's [Model Context Protocol (MCP)](https://docs.anthropic.com/claude/docs/model-context-protocol), an open standard for connecting AI assistants to data sources and tools.
  3. > **⚠️ IMPORTANT NOTICE**: Version 0.2.0 has been yanked due to critical issues with the SSE transport implementation. Please use version 0.2.3 instead, which includes important fixes for client-server communication, message handling, and template generation. If you're already using 0.2.0, we strongly recommend upgrading to 0.2.3 to avoid potential issues.
  4. ## Examples
  5. **[View Demo on Github Tools MCP Client/Server](https://asciinema.org/a/708211)**
  6. ![MCPR Demo](https://asciinema.org/a/708211.png)
  7. Check out our [GitHub Tools example](examples/github-tools/README.md) for a complete implementation of an MCP client-server application that interacts with GitHub repositories. This example demonstrates how to build a client that can query repository READMEs and search for repositories, with support for multiple servers and client-server disconnection scenarios. It's a great starting point for understanding how to build your own MCP applications.
  8. ## Features
  9. - **Schema Definitions**: Complete implementation of the MCP schema
  10. - **Transport Layer**: Multiple transport options including stdio and SSE
  11. - **High-Level Client/Server**: Easy-to-use client and server implementations
  12. - **CLI Tools**: Generate server and client stubs
  13. - **Project Generator**: Quickly scaffold new MCP projects
  14. - **Mock Implementations**: Built-in mock transports for testing and development
  15. ## Coming Soon
  16. - **WebSocket Transport**: WebSocket transport implementation is planned but not yet implemented
  17. ## Installation
  18. Add MCPR to your `Cargo.toml`:
  19. ```toml
  20. [dependencies]
  21. mcpr = "0.2.3" # Make sure to use 0.2.3 or later, as 0.2.0 has been yanked
  22. ```
  23. For CLI tools, install globally:
  24. ```bash
  25. cargo install mcpr
  26. ```
  27. ## Usage
  28. ### High-Level Client
  29. The high-level client provides a simple interface for communicating with MCP servers:
  30. ```rust
  31. use mcpr::{
  32. client::Client,
  33. transport::stdio::StdioTransport,
  34. };
  35. // Create a client with stdio transport
  36. let transport = StdioTransport::new();
  37. let mut client = Client::new(transport);
  38. // Initialize the client
  39. client.initialize()?;
  40. // Call a tool
  41. let request = MyToolRequest { /* ... */ };
  42. let response: MyToolResponse = client.call_tool("my_tool", &request)?;
  43. // Shutdown the client
  44. client.shutdown()?;
  45. ```
  46. ### High-Level Server
  47. The high-level server makes it easy to create MCP-compatible servers:
  48. ```rust
  49. use mcpr::{
  50. server::{Server, ServerConfig},
  51. transport::stdio::StdioTransport,
  52. Tool,
  53. };
  54. // Configure the server
  55. let server_config = ServerConfig::new()
  56. .with_name("My MCP Server")
  57. .with_version("1.0.0")
  58. .with_tool(Tool {
  59. name: "my_tool".to_string(),
  60. description: "My awesome tool".to_string(),
  61. parameters_schema: serde_json::json!({
  62. "type": "object",
  63. "properties": {
  64. // Tool parameters schema
  65. },
  66. "required": ["param1", "param2"]
  67. }),
  68. });
  69. // Create the server
  70. let mut server = Server::new(server_config);
  71. // Register tool handlers
  72. server.register_tool_handler("my_tool", |params| {
  73. // Parse parameters and handle the tool call
  74. // ...
  75. Ok(serde_json::to_value(response)?)
  76. })?;
  77. // Start the server with stdio transport
  78. let transport = StdioTransport::new();
  79. server.start(transport)?;
  80. ```
  81. ## Creating MCP Projects
  82. MCPR includes a project generator to quickly scaffold new MCP projects with different transport types.
  83. ### Using the CLI
  84. ```bash
  85. # Generate a project with stdio transport
  86. mcpr generate-project --name my-stdio-project --transport stdio
  87. # Generate a project with SSE transport
  88. mcpr generate-project --name my-sse-project --transport sse
  89. ```
  90. ### Project Structure
  91. Each generated project includes:
  92. ```
  93. my-project/
  94. ├── client/ # Client implementation
  95. │ ├── src/
  96. │ │ └── main.rs # Client code
  97. │ └── Cargo.toml # Client dependencies
  98. ├── server/ # Server implementation
  99. │ ├── src/
  100. │ │ └── main.rs # Server code
  101. │ └── Cargo.toml # Server dependencies
  102. ├── test.sh # Combined test script
  103. ├── test_server.sh # Server-only test script
  104. ├── test_client.sh # Client-only test script
  105. └── run_tests.sh # Script to run all tests
  106. ```
  107. ### Local Development with Templates
  108. When developing with generated templates, you can switch between using the published crate version and your local development version:
  109. ```toml
  110. # In the generated Cargo.toml files (both client and server)
  111. # For local development, uncomment this line and comment out the crates.io version:
  112. # mcpr = { path = "/path/to/your/mcpr" }
  113. # For production, use version from crates.io:
  114. mcpr = "0.2.3"
  115. ```
  116. This allows you to:
  117. 1. Test your local MCPR changes with generated projects
  118. 2. Easily switch back to the stable published version
  119. 3. Develop and test new features in isolation
  120. The template generator automatically uses the current crate version, ensuring that generated projects always reference the latest release.
  121. ### Building Projects
  122. ```bash
  123. # Build the server
  124. cd my-project/server
  125. cargo build
  126. # Build the client
  127. cd my-project/client
  128. cargo build
  129. ```
  130. ### Running Projects
  131. #### Stdio Transport
  132. For stdio transport, you typically run the server and pipe its output to the client:
  133. ```bash
  134. # Run the server and pipe to client
  135. ./server/target/debug/my-stdio-project-server | ./client/target/debug/my-stdio-project-client
  136. ```
  137. Or use the client to connect to the server:
  138. ```bash
  139. # Run the server in one terminal
  140. ./server/target/debug/my-stdio-project-server
  141. # Run the client in another terminal
  142. ./client/target/debug/my-stdio-project-client --uri "stdio://./server/target/debug/my-stdio-project-server"
  143. ```
  144. #### SSE Transport
  145. For SSE transport, you run the server first, then connect with the client. The generated project includes a mock SSE transport implementation for testing:
  146. ```bash
  147. # Run the server (default port is 8080)
  148. ./server/target/debug/my-sse-project-server --port 8080
  149. # In another terminal, run the client
  150. ./client/target/debug/my-sse-project-client --uri "http://localhost:8080"
  151. ```
  152. The SSE transport supports both interactive and one-shot modes:
  153. ```bash
  154. # Interactive mode
  155. ./client/target/debug/my-sse-project-client --interactive
  156. # One-shot mode
  157. ./client/target/debug/my-sse-project-client --name "Your Name"
  158. ```
  159. The mock SSE transport implementation includes:
  160. - Automatic response generation for initialization
  161. - Echo-back functionality for tool calls
  162. - Proper error handling and logging
  163. - Support for all MCP message types
  164. #### Interactive Mode
  165. Clients support an interactive mode for manual testing:
  166. ```bash
  167. ./client/target/debug/my-project-client --interactive
  168. ```
  169. ### Running Tests
  170. Each generated project includes test scripts:
  171. ```bash
  172. # Run all tests
  173. ./run_tests.sh
  174. # Run only server tests
  175. ./test_server.sh
  176. # Run only client tests
  177. ./test_client.sh
  178. # Run the combined test (original test script)
  179. ./test.sh
  180. ```
  181. ## Transport Options
  182. MCPR supports multiple transport options:
  183. ### Stdio Transport
  184. The simplest transport, using standard input/output:
  185. ```rust
  186. use mcpr::transport::stdio::StdioTransport;
  187. let transport = StdioTransport::new();
  188. ```
  189. ### SSE Transport
  190. Server-Sent Events transport for web-based applications:
  191. ```rust
  192. use mcpr::transport::sse::SSETransport;
  193. // For server
  194. let transport = SSETransport::new("http://localhost:8080");
  195. // For client
  196. let transport = SSETransport::new("http://localhost:8080");
  197. ```
  198. ### WebSocket Transport (Coming Soon)
  199. WebSocket transport for bidirectional communication is currently under development.
  200. ## Detailed Testing Guide
  201. This section provides comprehensive instructions for generating and testing projects with both stdio and SSE transports.
  202. ### Generating Projects
  203. When generating projects, make sure to specify the correct transport type and output directory:
  204. ```bash
  205. # Generate a stdio project
  206. mcpr generate-project --name test-stdio-project --transport stdio --output /tmp
  207. # Generate an SSE project
  208. mcpr generate-project --name test-sse-project --transport sse --output /tmp
  209. ```
  210. Note: The `--output` parameter specifies where to create the project directory. If omitted, the project will be created in the current directory.
  211. ### Testing Stdio Transport Projects
  212. 1. **Build the project**:
  213. ```bash
  214. cd /tmp/test-stdio-project
  215. cd server && cargo build
  216. cd ../client && cargo build
  217. ```
  218. 2. **Run the server and client together**:
  219. ```bash
  220. cd /tmp/test-stdio-project
  221. ./server/target/debug/test-stdio-project-server | ./client/target/debug/test-stdio-project-client
  222. ```
  223. You should see output similar to:
  224. ```
  225. [INFO] Using stdio transport
  226. [INFO] Initializing client...
  227. [INFO] Server info: {"protocol_version":"2024-11-05","server_info":{"name":"test-stdio-project-server","version":"1.0.0"},"tools":[{"description":"A simple hello world tool","input_schema":{"properties":{"name":{"description":"Name to greet","type":"string"}},"required":["name"],"type":"object"},"name":"hello"}]}
  228. [INFO] Running in one-shot mode with name: Default User
  229. [INFO] Calling tool 'hello' with parameters: {"name":"Default User"}
  230. [INFO] Received message: Hello, Default User!
  231. Hello, Default User!
  232. [INFO] Shutting down client
  233. [INFO] Client shutdown complete
  234. ```
  235. 3. **Run with detailed logging**:
  236. ```bash
  237. RUST_LOG=debug ./server/target/debug/test-stdio-project-server | RUST_LOG=debug ./client/target/debug/test-stdio-project-client
  238. ```
  239. 4. **Run with a custom name**:
  240. ```bash
  241. ./server/target/debug/test-stdio-project-server | ./client/target/debug/test-stdio-project-client --name "Your Name"
  242. ```
  243. ### Testing SSE Transport Projects
  244. 1. **Build the project**:
  245. ```bash
  246. cd /tmp/test-sse-project
  247. cd server && cargo build
  248. cd ../client && cargo build
  249. ```
  250. 2. **Run the server**:
  251. ```bash
  252. cd /tmp/test-sse-project/server
  253. RUST_LOG=trace cargo run -- --port 8084 --debug
  254. ```
  255. 3. **In another terminal, run the client**:
  256. ```bash
  257. cd /tmp/test-sse-project/client
  258. RUST_LOG=trace cargo run -- --uri "http://localhost:8084" --name "Test User"
  259. ```
  260. You should see output similar to:
  261. ```
  262. [INFO] Using SSE transport with URI: http://localhost:8084
  263. [INFO] Initializing client...
  264. [INFO] Server info: {"protocol_version":"2024-11-05","server_info":{"name":"test-sse-project-server","version":"1.0.0"},"tools":[{"description":"A simple hello world tool","input_schema":{"properties":{"name":{"description":"Name to greet","type":"string"}},"required":["name"],"type":"object"},"name":"hello"}]}
  265. [INFO] Running in one-shot mode with name: Test User
  266. [INFO] Calling tool 'hello' with parameters: {"name":"Test User"}
  267. [INFO] Received message: Hello, Test User!
  268. Hello, Test User!
  269. [INFO] Shutting down client
  270. [INFO] Client shutdown complete
  271. ```
  272. ### Troubleshooting
  273. #### Common Issues with Stdio Transport
  274. 1. **Pipe Connection Issues**:
  275. - Ensure that the server output is properly piped to the client input
  276. - Check for any terminal configuration that might interfere with piping
  277. 2. **Process Termination**:
  278. - The server process will terminate after the client disconnects
  279. - For long-running sessions, consider using the interactive mode
  280. #### Common Issues with SSE Transport
  281. 1. **Dependency Issues**:
  282. If you encounter dependency errors when building generated projects, you may need to update the `Cargo.toml` files to point to your local MCPR crate (see the [Local Development with Templates](#local-development-with-templates) section):
  283. ```toml
  284. # For local development, uncomment this line:
  285. mcpr = { path = "/path/to/your/mcpr" }
  286. # And comment out the crates.io version:
  287. # mcpr = "0.2.3"
  288. ```
  289. 2. **Port Already in Use**:
  290. If the SSE server fails to start with a "port already in use" error, try a different port:
  291. ```bash
  292. ./server/target/debug/test-sse-project-server --port 8085
  293. ```
  294. 3. **Connection Refused**:
  295. If the client cannot connect to the server, ensure the server is running and the port is correct:
  296. ```bash
  297. # Check if the server is listening on the port
  298. netstat -an | grep 8084
  299. ```
  300. 4. **HTTP Method Not Allowed (405)**:
  301. If you see HTTP 405 errors, ensure that the server is correctly handling all required HTTP methods (GET and POST) for the SSE transport.
  302. 5. **Client Registration Issues**:
  303. The SSE transport requires client registration before message exchange. Ensure that:
  304. - The client successfully registers with the server
  305. - The client ID is properly passed in polling requests
  306. - The server maintains the client connection state
  307. ### Interactive Testing
  308. Both transport types support interactive mode for manual testing:
  309. ```bash
  310. # For stdio transport
  311. ./client/target/debug/test-stdio-project-client --interactive
  312. # For SSE transport
  313. ./client/target/debug/test-sse-project-client --uri "http://localhost:8084" --interactive
  314. ```
  315. In interactive mode, you can:
  316. - Enter tool names and parameters manually
  317. - Test different parameter combinations
  318. - Observe the server's responses in real-time
  319. ### Advanced Testing
  320. For more advanced testing scenarios:
  321. 1. **Testing with Multiple Clients**:
  322. The SSE transport supports multiple concurrent clients:
  323. ```bash
  324. # Start multiple client instances in different terminals
  325. ./client/target/debug/test-sse-project-client --uri "http://localhost:8084" --name "User 1"
  326. ./client/target/debug/test-sse-project-client --uri "http://localhost:8084" --name "User 2"
  327. ```
  328. 2. **Testing Error Handling**:
  329. Test how the system handles errors by sending invalid requests:
  330. ```bash
  331. # In interactive mode, try calling a non-existent tool
  332. > call nonexistent_tool {"param": "value"}
  333. ```
  334. 3. **Performance Testing**:
  335. For performance testing, you can use tools like Apache Bench or wrk to simulate multiple concurrent clients.
  336. ## Debugging
  337. Enable debug logging for detailed information:
  338. ```bash
  339. # Set environment variable for debug logging
  340. RUST_LOG=debug cargo run
  341. ```
  342. ## Contributing
  343. 1. Fork the repository
  344. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  345. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  346. 4. Push to the branch (`git push origin feature/amazing-feature`)
  347. 5. Open a Pull Request
  348. ## License
  349. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.