# mcp-server
**Framework for building MCP servers with pluggable backends**
[](https://github.com/avrabe/mcp-loxone/blob/main/LICENSE)
This crate provides the server infrastructure for building Model Context Protocol servers in Rust. You implement a backend trait, and this handles the protocol details, transport layer, and infrastructure concerns.
## What This Crate Does
The main idea is simple: you implement the `McpBackend` trait for your domain (databases, APIs, file systems, etc.), and this crate handles all the MCP protocol work.
**Infrastructure handled for you:**
- Protocol compliance and message routing
- Multiple transport support (stdio, HTTP, WebSocket)
- Authentication and security middleware integration
- Request validation and error handling
- Monitoring and health checks
**You focus on:**
- Your domain logic (what tools/resources you provide)
- How to execute operations in your system
- Your specific business rules and validation
## Real-World Example
This framework currently powers the **Loxone MCP Server**, which implements 30+ tools for home automation. It successfully works with MCP Inspector, Claude Desktop, and HTTP clients like n8n.
## Quick Start
```toml
[dependencies]
mcp-server = "0.1.0"
mcp-protocol = "0.1.0"
mcp-transport = "0.1.0"
tokio = { version = "1.0", features = ["full"] }
async-trait = "0.1"
```
```rust
use mcp_server::{McpServer, McpBackend, ServerConfig};
use mcp_protocol::*;
use mcp_transport::TransportConfig;
use async_trait::async_trait;
use std::collections::HashMap;
// Your backend implementation
#[derive(Clone)]
struct MyBackend {
data: HashMap<String, String>,
}
#[async_trait]
impl McpBackend for MyBackend {
type Error = Box<dyn std::error::Error + Send + Sync>;
type Config = ();
async fn initialize(_config: Self::Config) -> Result<Self, Self::Error> {
Ok(MyBackend {
data: HashMap::new(),
})
}
fn get_server_info(&self) -> ServerInfo {
ServerInfo {
protocol_version: ProtocolVersion::default(),
capabilities: ServerCapabilities {
tools: Some(ToolsCapability { list_changed: Some(false) }),
..Default::default()
},
server_info: Implementation {
name: "My MCP Server".to_string(),
version: "1.0.0".to_string(),
},
instructions: Some("A simple key-value store server".to_string()),
}
}
async fn list_tools(&self, _request: PaginatedRequestParam) -> Result<ListToolsResult, Self::Error> {
Ok(ListToolsResult {
tools: vec![
Tool {
name: "store_value".to_string(),
description: "Store a key-value pair".to_string(),
input_schema: serde_json::json!({
"type": "object",
"properties": {
"key": {"type": "string"},
"value": {"type": "string"}
},
"required": ["key", "value"]
}),
}
],
next_cursor: String::new(),
})
}
async fn call_tool(&self, request: CallToolRequestParam) -> Result<CallToolResult, Self::Error> {
match request.name.as_str() {
"store_value" => {
// Your business logic here
Ok(CallToolResult {
content: vec![Content::text("Value stored successfully".to_string())],
is_error: Some(false),
})
}
_ => Err("Unknown tool".into()),
}
}
// Implement other required methods (can return empty/default for unused features)
async fn list_resources(&self, _: PaginatedRequestParam) -> Result<ListResourcesResult, Self::Error> {
Ok(ListResourcesResult { resources: vec![], next_cursor: String::new() })
}
async fn read_resource(&self, _: ReadResourceRequestParam) -> Result<ReadResourceResult, Self::Error> {
Err("No resources available".into())
}
async fn list_prompts(&self, _: PaginatedRequestParam) -> Result<ListPromptsResult, Self::Error> {
Ok(ListPromptsResult { prompts: vec![], next_cursor: String::new() })
}
async fn get_prompt(&self, _: GetPromptRequestParam) -> Result<GetPromptResult, Self::Error> {
Err("No prompts available".into())
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let backend = MyBackend::initialize(()).await?;
let config = ServerConfig {
server_info: backend.get_server_info(),
transport_config: TransportConfig::Stdio, // or Http { port: 3001 }
..Default::default()
};
let mut server = McpServer::new(backend, config).await?;
server.run().await?;
Ok(())
}
```
## Current Status
**Works well for basic to complex use cases.** The Loxone implementation proves this can handle real-world complexity with multiple tools, resources, and concurrent operations.
**What's solid:**
- ✅ Backend trait is stable and well-tested
- ✅ Transport integration works (stdio, HTTP, WebSocket)
- ✅ Authentication middleware integrates cleanly
- ✅ Error handling and protocol compliance
- ✅ Async/await throughout with good performance
**Areas for improvement:**
- 📝 More examples for different use cases
- 🧪 Better testing utilities for backend implementations
- 🔧 Some advanced features could be more polished
- 📊 More comprehensive monitoring hooks
## Features
### Multiple Transports
```rust
// For Claude Desktop integration
TransportConfig::Stdio
// For HTTP clients (n8n, web apps)
TransportConfig::Http { port: 3001 }
// For real-time applications
TransportConfig::WebSocket { port: 3001 }
```
### Built-in Security
When enabled, you get authentication, rate limiting, and input validation automatically:
```rust
let mut config = ServerConfig::default();
config.auth_config.enabled = true; // Requires API keys
config.security_config.rate_limit = Some(100); // Requests per minute
```
### Monitoring Integration
The framework provides hooks for monitoring and observability:
```rust
// Health checks, metrics, and request tracing work automatically
// Custom monitoring can be added through the backend trait
```
## Comparing to the Loxone Implementation
The **Loxone MCP Server** is our main reference implementation. It shows how to:
- Handle 30+ tools with complex business logic
- Integrate with external systems (HTTP APIs)
- Manage connection pooling and caching
- Structure tools by domain (lighting, climate, security)
- Handle real-world error conditions
If you're building something similar in complexity, the Loxone code is a good reference for patterns and organization.
## Contributing
This crate is actively used and maintained as part of the Loxone MCP server. Improvements often come from real-world usage patterns we discover.
Most useful contributions:
1. **Better examples** - Show patterns for different domains
2. **Testing utilities** - Make it easier to test backend implementations
3. **Documentation** - Especially for complex integration scenarios
4. **Performance improvements** - Based on real usage patterns
## License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
**Repository:** https://github.com/avrabe/mcp-loxone