mcp-oxia

A Model Context Protocol (MCP) server implementation in Rust for Oxia, a scalable metadata store and coordination service.

Overview

This MCP server provides AI models with tools to interact with Oxia storage through the Model Context Protocol. It implements JSON-RPC 2.0 communication over stdio, allowing seamless integration with MCP-compatible AI systems.

Features

• Full MCP Protocol Support: Implements MCP protocol version 2024-11-05
• Oxia Integration: Provides tools for interacting with Oxia storage
• JSON-RPC 2.0: Standard JSON-RPC communication over stdio
• Async/Await: Built with Tokio for high-performance async operations

Available Tools

The MCP server exposes the following tools for Oxia operations. Each tool accepts an optional namespace parameter (defaults to "default"):

1. oxia_get: Retrieve a value by key from Oxia

   • Input: namespace (string, optional, default: "default"), key (string)
   • Returns: The value associated with the key, or a not found message

2. oxia_put: Store a key-value pair in Oxia

   • Input: namespace (string, optional, default: "default"), key (string), value (string)
   • Returns: Success confirmation

3. oxia_delete: Delete a key from Oxia

   • Input: namespace (string, optional, default: "default"), key (string)
   • Returns: Success confirmation

4. oxia_list: List keys with an optional prefix filter

   • Input: namespace (string, optional, default: "default"), prefix (string, optional)
   • Returns: List of matching keys

5. oxia_exists: Check if a key exists in Oxia

   • Input: namespace (string, optional, default: "default"), key (string)
   • Returns: Boolean indicating existence

Building

cargo build --release

Running

The server communicates via stdin/stdout using JSON-RPC 2.0:

cargo run

Or with the compiled binary:

./target/release/mcp-oxia

Configuration

The Oxia namespace is specified as a parameter when calling each tool, not as a server-level configuration. This allows different tools to operate on different namespaces as needed.

MCP Protocol

The server implements the following MCP methods:

• initialize: Initialize the MCP connection and exchange capabilities
• tools/list: List all available tools
• tools/call: Execute a specific tool with provided arguments

Example Usage

JSON-RPC Protocol

Here's an example of interacting with the server via JSON-RPC:

// Initialize the connection
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "example-client", "version": "1.0.0"}}}

// List available tools
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

// Store a value (using default namespace)
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "oxia_put", "arguments": {"key": "mykey", "value": "myvalue"}}}

// Store a value in a specific namespace
{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "oxia_put", "arguments": {"namespace": "my-namespace", "key": "mykey", "value": "myvalue"}}}

// Retrieve a value
{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "oxia_get", "arguments": {"key": "mykey"}}}

Using with Opencode Agent

To use this MCP server with an opencode agent, configure your MCP client (e.g., Claude Desktop) with the example configuration provided in example-config.json. The opencode agent can then use the Oxia tools to store and retrieve code snippets, configurations, or any other data in the Oxia storage system.

Example workflow:

1. The opencode agent connects to the MCP server
2. It can store code snippets using oxia_put with optional namespace parameter
3. Retrieve them later with oxia_get
4. List all stored items with oxia_list
5. Check existence with oxia_exists
6. Clean up with oxia_delete

Each tool call can specify a different namespace if needed, allowing the opencode agent to organize data across multiple namespaces.

Development

Project Structure

mcp-oxia/
├── src/
│   ├── main.rs      # Entry point and stdio handling
│   ├── mcp.rs       # MCP protocol types and structures
│   ├── server.rs    # MCP server implementation
│   └── oxia.rs      # Oxia client interface
├── Cargo.toml       # Project dependencies
└── README.md        # This file

Dependencies

• tokio: Async runtime
• serde: Serialization framework
• serde_json: JSON serialization
• anyhow: Error handling
• thiserror: Error type derivation

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.