mcp-vala

MCP Vala Library

A comprehensive Vala implementation of the Model Context Protocol (MCP) version "2025-11-25" using jsonrpc-gobject for STDIO communication.

Introduction

The MCP Vala Library provides a complete implementation of the Model Context Protocol (MCP) in Vala, enabling developers to create MCP servers with minimal boilerplate code. MCP is a protocol that allows language models to securely interact with external resources, tools, and prompts through a standardized JSON-RPC interface.

This library offers a clean, type-safe, and asynchronous API that follows Vala's programming conventions while maintaining full compliance with the MCP specification.

Features

• Core MCP Protocol Support: Full implementation of MCP v2025-11-25 specification
• JSON-RPC 2.0: Standard-compliant implementation using jsonrpc-glib-1.0
• STDIO Transport: Standard input/output communication with proper handling
• Type Safety: Leverages Vala's type system while using Json-Glib for JSON handling
• Asynchronous Design: Non-blocking operations throughout
• Extensible Architecture: Clean interfaces for custom providers and executors
• Resource Management: Built-in file system provider with extensible provider interface
• Tool Execution: Simple tool registration and execution framework
• Prompt Handling: Template-based prompt system with argument support
• Error Handling: Comprehensive error domain with proper JSON-RPC error codes
• IO Reliability: Robust error handling and message parsing through jsonrpc-glib-1.0

Quick Start

Installation

From Source

# Clone the repository
git clone https://github.com/your-repo/mcp-vala.git
cd mcp-vala

# Configure and build
meson setup builddir
meson compile -C builddir

# Install (optional)
sudo meson install -C builddir

Dependencies

• Vala compiler (valac) >= 0.56
• Meson build system (meson) >= 0.59
• Required dependencies:
  • glib-2.0 >= 2.70
  • gobject-2.0 >= 2.70
  • gio-2.0 >= 2.70
  • json-glib-1.0 >= 1.6
  • jsonrpc-glib-1.0 >= 3.34
  • gio-unix-2.0 (for STDIO transport)
  • gee-0.8 (for collections)

Minimal Example

Create a minimal MCP server with just a few lines of code:

using Mcp;

int main (string[] args) {
    // Create server info
    var server_info = new Mcp.Types.Protocol.ServerInfo (
        "minimal-server",
        "1.0.0",
        "A minimal MCP server"
    );
    
    // Create capabilities
    var capabilities = new Mcp.Types.Protocol.ServerCapabilities ();
    
    // Create and start server
    var server = new Mcp.Core.Server (server_info, capabilities);
    
    // Run the server (blocking)
    server.run.begin ();
    
    // Keep the main loop running
    var loop = new MainLoop ();
    loop.run ();
    
    return 0;
}

Compile and run:

valac --pkg mcp-vala --pkg json-glib-1.0 --pkg jsonrpc-glib-1.0 --pkg gio-unix-2.0 --pkg gee-0.8 minimal.vala -o minimal-server
./minimal-server

Main Features

Resources

Resources represent data that can be read by clients, such as files, database entries, or API responses. The library provides:

• Built-in file system resource provider
• Extensible resource provider interface
• Resource templates for dynamic resource creation

• Subscription support for resource change notifications

  // Register a file system provider
  var provider = new Mcp.Resources.Provider.FilesystemProvider ("/path/to/directory");
  server.resource_manager.register_provider (provider);
  

Tools

Tools are functions that clients can execute, such as running commands, performing calculations, or interacting with external services.

public class CalculatorTool : Object, Mcp.Tools.Executor {
    public Mcp.Tools.Types.ToolDefinition get_definition () {
        var input_schema = new Json.Object ();
        input_schema.set_string_member ("type", "object");
        
        var properties = new Json.Object ();
        
        var expr_prop = new Json.Object ();
        expr_prop.set_string_member ("type", "string");
        expr_prop.set_string_member ("description", "Mathematical expression to evaluate");
        properties.set_object_member ("expression", expr_prop);
        
        input_schema.set_object_member ("properties", properties);
        input_schema.set_array_member ("required", new Json.Array ());
        
        return new Mcp.Tools.Types.ToolDefinition ("calculator", input_schema);
    }
    
    public async Mcp.Tools.Types.CallToolResult execute (Json.Object arguments) throws Error {
        string expression = arguments.get_string_member ("expression");
        
        // Simple evaluation (in production, use a proper math parser)
        string result = eval_expression (expression);
        
        var content = new Mcp.Types.Common.TextContent (result);
        var contents = new Gee.ArrayList<Mcp.Types.Common.ContentBlock> ();
        contents.add (content);
        
        var call_result = new Mcp.Tools.Types.CallToolResult ();
        call_result.content = contents;
        
        return call_result;
    }
}

// Register the tool
server.tool_manager.register_executor (new CalculatorTool ());

Prompts

Prompts are templates that can be filled with arguments to generate consistent messages for language models.

public class CodeReviewPrompt : Object, Mcp.Prompts.Template {
    public Mcp.Prompts.Types.PromptDefinition get_definition () {
        var prompt = new Mcp.Prompts.Types.PromptDefinition ("code_review");
        prompt.description = "Generate a code review for the provided code";
        
        var code_arg = new Mcp.Prompts.Types.PromptArgument ("code");
        code_arg.description = "The code to review";
        code_arg.required = true;
        prompt.arguments.add (code_arg);
        
        var style_arg = new Mcp.Prompts.Types.PromptArgument ("style");
        style_arg.description = "Review style (strict, moderate, relaxed)";
        prompt.arguments.add (style_arg);
        
        return prompt;
    }
    
    public async Mcp.Prompts.Types.GetPromptResult render (Json.Object arguments) throws Error {
        string code = arguments.get_string_member ("code");
        string style = arguments.has_member ("style") ? arguments.get_string_member ("style") : "moderate";
        
        string prompt_text = @"Please review the following code using a $style style:\n\n$code\n\nProvide feedback on:\n1. Code quality\n2. Potential bugs\n3. Performance considerations\n4. Best practices";
        
        var content = new Mcp.Types.Common.TextContent (prompt_text);
        var message = new Mcp.Prompts.Types.PromptMessage ("user", content);
        
        var result = new Mcp.Prompts.Types.GetPromptResult ();
        result.messages.add (message);
        
        return result;
    }
}

// Register the prompt
server.prompt_manager.register_template (new CodeReviewPrompt ());

API Overview

Core Classes

• Mcp.Core.Server: Main server class that handles the MCP protocol using Jsonrpc.Server
• Mcp.Core.Error: Error domain and utilities

Manager Classes

• Mcp.Resources.Manager: Manages resource providers and handles resource operations
• Mcp.Tools.Manager: Manages tool executors and handles tool operations
• Mcp.Prompts.Manager: Manages prompt templates and handles prompt operations

Type Definitions

• Mcp.Types.Protocol: Core protocol types (ServerInfo, Capabilities, etc.)
• Mcp.Types.Common: Common content types used across the protocol

Building and Testing

Build Commands

# Configure the build
meson setup builddir

# Build the library
meson compile -C builddir

# Run tests (when available)
meson test -C builddir

# Build examples
meson compile -C builddir examples

# Install
sudo meson install -C builddir

Building Examples

The library includes several examples that demonstrate different aspects of the MCP protocol:

# Build all examples
meson compile -C builddir examples

# Run specific examples
./builddir/examples/minimal-server
./builddir/examples/filesystem-server
./builddir/examples/calculator-server
./builddir/examples/chat-server

Usage Patterns

Server Initialization

// Create server information
var server_info = new Mcp.Types.Protocol.ServerInfo (
    "my-server",
    "1.0.0",
    "Description of my MCP server"
);

// Configure capabilities
var capabilities = new Mcp.Types.Protocol.ServerCapabilities ();
capabilities.logging = true;
capabilities.resources = new Mcp.Types.Protocol.ResourcesCapabilities ();
capabilities.tools = new Mcp.Types.Protocol.ToolsCapabilities ();
capabilities.prompts = new Mcp.Types.Protocol.PromptsCapabilities ();

// Create server
var server = new Mcp.Core.Server (server_info, capabilities);

Error Handling

The library provides a comprehensive error domain with proper JSON-RPC error codes:

try {
    var result = yield server.tool_manager.call_tool ("calculator", arguments);
    // Handle result
} catch (Mcp.Core.McpError e) {
    // Handle MCP-specific errors
    stderr.printf ("MCP Error: %s (code: %d)\n", e.message, e.code);
} catch (Error e) {
    // Handle other errors
    stderr.printf ("Error: %s\n", e.message);
}

Asynchronous Operations

All operations that involve I/O are asynchronous:

// List resources
var resource_list = yield server.resource_manager.list_resources ();

// Call a tool
var tool_result = yield server.tool_manager.call_tool ("my_tool", arguments);

// Get a prompt
var prompt = yield server.prompt_manager.get_prompt ("my_prompt", arguments);

Architecture

The implementation follows these key design principles:

1. Standard JSON-RPC Implementation: Uses jsonrpc-glib-1.0 for standard-compliant JSON-RPC 2.0 communication
2. Interface-Based Design: Extensible providers and executors with well-defined contracts
3. Type Safety: Strong typing with Vala's type system
4. Error Handling: Comprehensive error domain with proper JSON-RPC error codes
5. Asynchronous Operations: Non-blocking I/O and async method signatures
6. Protocol Compliance: Full MCP v2025-11-25 specification support
7. IO Reliability: Robust STDIO transport and message handling through jsonrpc-glib-1.0

Project Structure

mcp-vala/
├── src/
│   ├── core/
│   │   ├── error.vala              # Error domain and utilities
│   │   └── server.vala             # Main server class using Jsonrpc.Server
│   ├── types/
│   │   ├── protocol.vala           # Protocol types (ServerInfo, Capabilities)
│   │   └── common.vala           # Common content types
│   ├── resources/
│   │   ├── types.vala            # Resource data types
│   │   ├── provider.vala          # Resource provider interface
│   │   └── manager.vala          # Resource manager
│   ├── tools/
│   │   ├── types.vala            # Tool data types
│   │   ├── executor.vala          # Tool executor interface
│   │   └── manager.vala          # Tool manager
│   ├── prompts/
│   │   ├── types.vala            # Prompt data types
│   │   ├── template.vala          # Prompt template interface
│   │   └── manager.vala          # Prompt manager
│   └── meson.build                # Library build configuration
├── examples/
│   ├── minimal-server.vala        # Minimal server example
│   ├── filesystem-server.vala     # File system resource example
│   ├── calculator-server.vala     # Tool execution example
│   ├── chat-server.vala           # Prompt handling example
│   └── meson.build               # Examples build configuration
├── docs/
│   ├── developer-guide.md        # Developer guide
│   └── api-reference.md          # API documentation
├── meson.build                    # Main build configuration
├── CHANGELOG.md                   # Version history
└── README.md                     # This file

License

This library is licensed under the GNU Lesser General Public License v2.1 or later. See individual source files for specific license information.

Contributing

Contributions are welcome! Please ensure:

• Code follows Vala naming conventions
• Comprehensive documentation with Valadoc comments
• Tests for new functionality
• Adherence to the architecture design

Status

The core MCP server functionality is implemented and ready for use. The library now uses jsonrpc-glib-1.0 for standard-compliant JSON-RPC 2.0 communication, providing improved IO reliability and error handling. This provides a solid foundation for building MCP servers in Vala with proper protocol compliance and extensibility.