Viam MCP SDK

Welcome to the Viam MCP SDK, a Rust library for integrating with the Model Context Protocol (MCP). This SDK provides the necessary tools and abstractions to build MCP-compliant servers and clients using Rust and WebAssembly.

Overview

The Model Context Protocol (MCP) is a specification for communication between AI models and hosting environments. This SDK aims to simplify the implementation of MCP servers and clients by providing:

• JSON-RPC 2.0 handling for MCP communication
• Tools for building MCP-compliant WASM components
• Support for the MCP specification as defined at spec.modelcontextprotocol.io

Installation

Add this crate to your Rust project using:

[dependencies]
viam-mcp-sdk = "0.1.0"

Or using Cargo:

cargo add viam-mcp-sdk

If you have the repository locally and want to use it directly (useful for development or testing changes before publication), you can specify the path to the local repository:

[dependencies]
viam-mcp-sdk = { path = "../path/to/viam-mcp-sdk" }

Usage

Detailed usage instructions and examples will be added soon. Check the examples directory for sample implementations of MCP servers using this SDK.

Creating Handlers and Tools with VIAM MCP SDK

The VIAM MCP SDK allows developers to create custom handlers and tools to extend the functionality of MCP server components. Handlers and tools can be used to process specific commands or implement custom logic for your server.

Overview

• Handlers: Implement the CommandHandler trait to process JSON-RPC commands. They can manage server initialization, custom methods, and more.
• Tools: Implement the ToolHandler trait to define callable tools with specific inputs and outputs. Tools are typically used for more complex operations that may involve external API calls or form submissions.

Example: Creating a Custom Tool

Below is a simplified example of creating a custom tool, inspired by the fetch_dog_tool in the example project:

use viam_mcp_sdk::tool::ToolHandler;
use viam_mcp_sdk::command::JsonRpcError;
use serde_json::{Value, json};

pub struct SimpleDogTool;

impl ToolHandler for SimpleDogTool {
    fn call(&self, _input: &Value) -> Result<Value, JsonRpcError> {
        // Simulate fetching a dog image URL (in a real scenario, this would call an API)
        let image_url = "https://example.com/dog.jpg";
        
        // Return the result as JSON
        Ok(json!({
            "imageUrl": image_url
        }))
    }
    
    fn name(&self) -> &'static str {
        "simpleDogTool"
    }
    
    fn description(&self) -> &'static str {
        "Fetches a URL for a dog image."
    }
    
    fn input_schema(&self) -> &'static str {
        r#"{
            "type": "object",
            "properties": {}
        }"#
    }
}

Using Your Custom Tool

1. Define Your Tool: Create a new Rust file in your project (e.g., src/handlers/simple_dog_tool.rs) and add the code above.
2. Register the Tool: In your main library file (e.g., src/lib.rs), ensure your tool is registered with the ToolRegistry or directly used in your server component setup. Here's an example of how to add SimpleDogTool to the handlers map, inspired by the example project:

use viam_mcp_sdk::mcp_server_component;
use viam_mcp_sdk::tool::ToolHandler;
use handlers::simple_dog_tool::SimpleDogTool;

mcp_server_component! {
    handlers => {
        tools => {
            SimpleDogTool
        }
    }
}

This assumes you've organized your code with the SimpleDogTool in a module under handlers. Adjust the import path as necessary based on your project structure.

3. Integrate with MCP Server: Refer to the example in examples/mcp-server-component for how to integrate tools with the server component.

For more detailed examples, including how to make HTTP requests or handle form submissions, see the example project.

Documentation

API documentation will be available soon. In the meantime, refer to the source code and comments for detailed information on the SDK's functionality.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests on our GitHub repository.

License

This project is licensed under the MIT License.

Contact

For questions or support, please open an issue on GitHub or contact the maintainers.