# 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

```bash
# 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:

```vala
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:

```bash
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

```vala
// 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.

```vala
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.

```vala
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`](src/core/server.vala): Main server class that handles the MCP protocol using Jsonrpc.Server
- [`Mcp.Core.Error`](src/core/error.vala): Error domain and utilities

### Manager Classes

- [`Mcp.Resources.Manager`](src/resources/manager.vala): Manages resource providers and handles resource operations
- [`Mcp.Tools.Manager`](src/tools/manager.vala): Manages tool executors and handles tool operations
- [`Mcp.Prompts.Manager`](src/prompts/manager.vala): Manages prompt templates and handles prompt operations

### Type Definitions

- [`Mcp.Types.Protocol`](src/types/protocol.vala): Core protocol types (ServerInfo, Capabilities, etc.)
- [`Mcp.Types.Common`](src/types/common.vala): Common content types used across the protocol

## Building and Testing

### Build Commands

```bash
# 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:

```bash
# 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

```vala
// 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:

```vala
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:

```vala
// 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.