mcp-vala/docs/api-reference.md

MCP Vala Library API Reference

This document provides comprehensive API documentation for the MCP Vala library, covering all public classes, interfaces, and methods.

Table of Contents

1. Core Namespace
2. Types Namespace
3. Resources Namespace
4. Tools Namespace
5. Prompts Namespace
6. Common Namespace

Core Namespace

Mcp.Core.Server

The main server class that orchestrates all MCP functionality.

Constructor

public Server (
    Mcp.Types.Protocol.ServerInfo server_info,
    Mcp.Types.Protocol.ServerCapabilities capabilities
)

Parameters:

• server_info: Information about the server (name, version, description)
• capabilities: Server capabilities (resources, tools, prompts, logging)

Properties

public Mcp.Resources.Manager resource_manager { get; }
public Mcp.Tools.Manager tool_manager { get; }
public Mcp.Prompts.Manager prompt_manager { get; }
public bool is_running { get; }
public bool is_initialized { get; }

Signals

public signal void initialized ();
public signal void shutdown ();

Methods

public async bool start () throws Error
public async void stop ()
public void send_notification (string method, Variant? params = null)

Example

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

var capabilities = new Mcp.Types.Protocol.ServerCapabilities ();
capabilities.logging = true;
capabilities.tools = new Mcp.Types.Protocol.ToolsCapabilities ();

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

// Start server
bool started = yield server.start ();
if (started) {
    print ("Server started successfully\n");
}

Jsonrpc Integration

The library now uses Jsonrpc.Server from jsonrpc-glib-1.0 for handling JSON-RPC communication. The custom MessageHandler and StdioTransport classes have been removed in favor of the standard implementation.

Key Benefits

• Standard-compliant JSON-RPC 2.0 implementation
• Robust error handling with Jsonrpc.Error
• Built-in support for async/await patterns
• Proper STDIO transport handling
• Automatic message parsing and formatting

Mcp.Core.McpError

Error domain for MCP-specific errors.

Error Codes

public static const int PARSE_ERROR = -32700;
public static const int INVALID_REQUEST = -32600;
public static const int METHOD_NOT_FOUND = -32601;
public static const int INVALID_PARAMS = -32602;
public static const int INTERNAL_ERROR = -32603;
public static const int RESOURCE_NOT_FOUND = -32604;
public static const int TRANSPORT_ERROR = -32605;

Types Namespace

Mcp.Types.Protocol.ServerInfo

Information about the MCP server.

Constructor

public ServerInfo (
    string name,
    string version,
    string? description = null
)

Properties

public string name { get; set; }
public string version { get; set; }
public string? description { get; set; }

Mcp.Types.Protocol.ServerCapabilities

Server capabilities configuration.

Properties

public bool logging { get; set; }
public Mcp.Types.Protocol.ResourcesCapabilities? resources { get; set; }
public Mcp.Types.Protocol.ToolsCapabilities? tools { get; set; }
public Mcp.Types.Protocol.PromptsCapabilities? prompts { get; set; }

Mcp.Types.Protocol.ResourcesCapabilities

Resource-related capabilities.

Properties

public bool subscribe { get; set; }
public bool list_changed { get; set; }

Mcp.Types.Protocol.ToolsCapabilities

Tool-related capabilities.

Properties

public bool list_changed { get; set; }

Mcp.Types.Protocol.PromptsCapabilities

Prompt-related capabilities.

Properties

public bool list_changed { get; set; }

Jsonrpc Integration

The library now uses Jsonrpc.Server from jsonrpc-glib-1.0 for handling JSON-RPC communication. Custom JSON-RPC message types have been removed in favor of the standard implementation.

Communication Pattern

The library internally converts between Json.Node (used for MCP protocol types) and GLib.Variant (used by Jsonrpc.Server) for seamless integration.

Error Handling

Errors are now handled using Jsonrpc.Error for proper JSON-RPC 2.0 error responses.

Mcp.Types.Common

Common content types used across the MCP protocol.

Mcp.Types.Common.ContentBlock

Base interface for content blocks.

Subclasses

public class TextContent : Mcp.Types.Common.ContentBlock
public class ImageContent : Mcp.Types.Common.ContentBlock
public class ResourceContents : Mcp.Types.Common.ContentBlock

Mcp.Types.Common.TextContent

Text content block.

Constructor

public TextContent (string text)

Properties

public string text { get; construct; }
public string type { get; default = "text"; }

Mcp.Types.Common.ImageContent

Image content block.

Constructor

public ImageContent (string data, string mime_type)

Properties

public string data { get; construct; }
public string mime_type { get; construct; }
public string type { get; default = "image"; }

Mcp.Types.Common.ResourceContents

Base interface for resource contents.

Subclasses

public class TextResourceContents : Mcp.Types.Common.ResourceContents
public class BlobResourceContents : Mcp.Types.Common.ResourceContents

Mcp.Types.Common.TextResourceContents

Text-based resource contents.

Constructor

public TextResourceContents (string uri, string text)

Properties

public string uri { get; construct; }
public string text { get; construct; }
public string mime_type { get; default = "text/plain"; }

Mcp.Types.Common.BlobResourceContents

Binary resource contents.

Constructor

public BlobResourceContents (string uri, uint8[] data, string? mime_type = null)

Properties

public string uri { get; construct; }
public uint8[] data { get; construct; }
public string mime_type { get; construct; }

Mcp.Types.Common.Annotations

Resource annotations.

Properties

public double? priority { get; set; }
public string? audience { get; set; }
public bool? expire_time { get; set; }

Resources Namespace

Mcp.Resources.Provider

Interface for resource providers.

Methods

public abstract async Gee.ArrayList<Mcp.Resources.Types.Resource> list_resources (string? cursor) throws Error
public abstract async Mcp.Types.Common.ResourceContents read_resource (string uri) throws Error
public virtual async void subscribe (string uri) throws Error
public virtual async void unsubscribe (string uri) throws Error

Mcp.Resources.BaseProvider

Base implementation for resource providers.

Constructor

protected BaseProvider ()

Properties

public signal void resource_updated (string uri);

Methods

public Gee.ArrayList<string> get_subscriptions ()
public bool is_subscribed (string uri)
public void notify_resource_updated (string uri)
protected virtual Mcp.Resources.Types.Resource? get_resource_metadata (string uri)
protected string guess_mime_type (string uri)

Mcp.Resources.Manager

Manages resource providers and handles resource operations.

Methods

public void register_provider (string name, Mcp.Resources.Provider provider)
public void unregister_provider (string name)
public async Gee.ArrayList<Mcp.Resources.Types.Resource> list_resources (string? cursor) throws Error
public async Mcp.Types.Common.ResourceContents read_resource (string uri) throws Error
public async void subscribe (string uri) throws Error
public async void unsubscribe (string uri) throws Error
public async Gee.ArrayList<Mcp.Resources.Types.ResourceTemplate> list_templates () throws Error
public void register_template (string name, Mcp.Resources.Types.ResourceTemplate template)
public void unregister_template (string name)

Mcp.Resources.Types.Resource

Resource definition.

Constructor

public Resource (string uri, string name)

Properties

public string uri { get; set; }
public string name { get; set; }
public string? title { get; set; }
public string? description { get; set; }
public string? mime_type { get; set; }
public Mcp.Types.Common.Annotations? annotations { get; set; }
public int64? size { get; set; }

Methods

public Json.Node to_json ()
public Resource.from_json (Json.Node node) throws Error

Mcp.Resources.Types.ResourceTemplate

Resource template for dynamic resource creation.

Constructor

public ResourceTemplate (string uri_template, string name)

Properties

public string uri_template { get; set; }
public string name { get; set; }
public string? title { get; set; }
public string? description { get; set; }
public string? mime_type { get; set; }
public Mcp.Types.Common.Annotations? annotations { get; set; }

Tools Namespace

Mcp.Tools.Executor

Interface for tool executors.

Methods

public abstract Mcp.Tools.Types.ToolDefinition get_definition () throws Error
public abstract async Mcp.Tools.Types.CallToolResult execute (Json.Object arguments) throws Error

Mcp.Tools.BaseExecutor

Base implementation for tool executors.

Constructor

protected BaseExecutor (Mcp.Tools.Types.ToolDefinition definition)

Methods

public virtual Mcp.Tools.Types.ToolDefinition get_definition () throws Error
public async Mcp.Tools.Types.CallToolResult execute (Json.Object arguments) throws Error
protected virtual void validate_arguments (Json.Object arguments) throws Error
protected Mcp.Tools.Types.CallToolResult create_text_result (string text)
protected Mcp.Tools.Types.CallToolResult create_text_results (string[] texts)
protected Mcp.Tools.Types.CallToolResult create_error_result (Error error)
protected Mcp.Tools.Types.CallToolResult create_structured_result (string text, Json.Object structured_data)
protected string? get_string_arg (Json.Object arguments, string name, string? default_value = null)
protected bool get_bool_arg (Json.Object arguments, string name, bool default_value = false)
protected int get_int_arg (Json.Object arguments, string name, int default_value = 0)
protected double get_double_arg (Json.Object arguments, string name, double default_value = 0.0)
protected abstract async Mcp.Tools.Types.CallToolResult do_execute (Json.Object arguments) throws Error

Mcp.Tools.Manager

Manages tool executors and handles tool operations.

Methods

public void register_executor (string name, Mcp.Tools.Executor executor)
public void unregister_executor (string name)
public async Gee.ArrayList<Mcp.Tools.Types.ToolDefinition> list_tools () throws Error
public async Mcp.Tools.Types.CallToolResult call_tool (string name, Json.Object arguments) throws Error

Mcp.Tools.Types.ToolDefinition

Tool definition.

Constructor

public ToolDefinition (string name, Json.Object input_schema)

Properties

public string name { get; set; }
public string? title { get; set; }
public string? description { get; set; }
public Json.Object input_schema { get; set; }
public Json.Object? output_schema { get; set; }
public Mcp.Tools.Types.ToolExecution? execution { get; set; }
public Mcp.Tools.Types.ToolAnnotations? annotations { get; set; }

Methods

public Json.Node to_json ()
public ToolDefinition.from_json (Json.Node node) throws Error

Mcp.Tools.Types.CallToolResult

Result of calling a tool.

Constructor

public CallToolResult ()

Properties

public Gee.ArrayList<Mcp.Types.Common.ContentBlock> content { get; set; }
public Json.Object? structured_content { get; set; }
public bool is_error { get; set; }

Methods

public Json.Node to_json ()
public CallToolResult.from_json (Json.Node node) throws Error

Mcp.Tools.Types.ToolExecution

Tool execution settings.

Constructor

public ToolExecution (string task_support = "forbidden")

Properties

public string task_support { get; set; }

Mcp.Tools.Types.ToolAnnotations

Tool annotations.

Constructor

public ToolAnnotations ()

Properties

public string? audience { get; set; }
public double? priority { get; set; }

Prompts Namespace

Mcp.Prompts.Template

Interface for prompt templates.

Methods

public abstract Mcp.Prompts.Types.PromptDefinition get_definition ()
public abstract async Mcp.Prompts.Types.GetPromptResult get_prompt (Json.Object arguments) throws Error

Mcp.Prompts.BaseTemplate

Base implementation for prompt templates.

Constructor

protected BaseTemplate (string name, string? title = null, string? description = null)

Methods

public virtual Mcp.Prompts.Types.PromptDefinition get_definition ()
public virtual async Mcp.Prompts.Types.GetPromptResult get_prompt (Json.Object arguments) throws Error
protected virtual void validate_arguments (Json.Object arguments) throws Error
protected virtual Gee.ArrayList<Mcp.Prompts.Types.PromptMessage> generate_messages (Json.Object arguments)
protected void add_argument (string name, string? title = null, string? description = null, bool required = false)
protected string substitute_variables (string template, Json.Object arguments)
protected Mcp.Types.Common.TextContent create_text_content (string template, Json.Object arguments)
protected Mcp.Prompts.Types.PromptMessage create_user_message (string template, Json.Object arguments)
protected Mcp.Prompts.Types.PromptMessage create_assistant_message (string template, Json.Object arguments)

Mcp.Prompts.Manager

Manages prompt templates and handles prompt operations.

Methods

public void register_template (string name, Mcp.Prompts.Template template)
public void unregister_template (string name)
public async Gee.ArrayList<Mcp.Prompts.Types.PromptDefinition> list_prompts () throws Error
public async Mcp.Prompts.Types.GetPromptResult get_prompt (string name, Json.Object arguments) throws Error

Mcp.Prompts.Types.PromptDefinition

Prompt definition.

Constructor

public PromptDefinition (string name)

Properties

public string name { get; set; }
public string? title { get; set; }
public string? description { get; set; }
public Gee.ArrayList<Mcp.Prompts.Types.PromptArgument> arguments { get; set; }

Methods

public Json.Node to_json ()
public PromptDefinition.from_json (Json.Node node) throws Error

Mcp.Prompts.Types.PromptArgument

Prompt argument definition.

Constructor

public PromptArgument (string name)

Properties

public string name { get; set; }
public string? title { get; set; }
public string? description { get; set; }
public bool required { get; set; }

Methods

public Json.Node to_json ()
public PromptArgument.from_json (Json.Node node) throws Error

Mcp.Prompts.Types.GetPromptResult

Result of getting a prompt.

Constructor

public GetPromptResult ()

Properties

public string? description { get; set; }
public Gee.ArrayList<Mcp.Prompts.Types.PromptMessage> messages { get; set; }

Methods

public Json.Node to_json ()
public GetPromptResult.from_json (Json.Node node) throws Error

Mcp.Prompts.Types.PromptMessage

Prompt message.

Constructor

public PromptMessage (string role, Mcp.Types.Common.ContentBlock content)

Properties

public string role { get; set; }
public Mcp.Types.Common.ContentBlock content { get; set; }

Methods

public Json.Node to_json ()
public PromptMessage.from_json (Json.Node node) throws Error

Usage Patterns

Server Initialization Pattern

public class MyMcpServer : GLib.Object {
    private Mcp.Core.Server server;
    
    public MyMcpServer () {
        // 1. Create server info
        var server_info = new Mcp.Types.Protocol.ServerInfo (
            "my-server",
            "1.0.0",
            "Description of my server"
        );
        
        // 2. Configure capabilities
        var capabilities = new Mcp.Types.Protocol.ServerCapabilities ();
        capabilities.logging = true;
        
        // 3. Create server
        server = new Mcp.Core.Server (server_info, capabilities);
        
        // 4. Set up components
        setup_components ();
    }
    
    private void setup_components () {
        // Register resources, tools, and prompts
    }
    
    public async int run () {
        // Start server and run main loop
        yield server.start ();
        new MainLoop ().run ();
        return 0;
    }
}

Resource Provider Pattern

public class MyResourceProvider : Mcp.Resources.BaseProvider {
    private HashTable<string, string> storage;
    
    public MyResourceProvider () {
        storage = new HashTable<string, string> (str_hash, str_equal);
        initialize_data ();
    }
    
    public override async Gee.ArrayList<Mcp.Resources.Types.Resource> list_resources (string? cursor) throws Error {
        var resources = new Gee.ArrayList<Mcp.Resources.Types.Resource> ();
        
        foreach (var entry in storage.get_keys ()) {
            var resource = new Mcp.Resources.Types.Resource (entry, entry);
            resource.mime_type = guess_mime_type (entry);
            resources.add (resource);
        }
        
        return resources;
    }
    
    public override async Mcp.Types.Common.ResourceContents read_resource (string uri) throws Error {
        if (!storage.contains (uri)) {
            throw new Mcp.Core.McpError.RESOURCE_NOT_FOUND ("Resource not found");
        }
        
        return new Mcp.Types.Common.TextResourceContents (uri, storage[uri]);
    }
}

Tool Executor Pattern

public class MyTool : Mcp.Tools.BaseExecutor {
    public MyTool () {
        // Define input schema
        var input_schema = new Json.Object ();
        input_schema.set_string_member ("type", "object");
        
        var properties = new Json.Object ();
        var param = new Json.Object ();
        param.set_string_member ("type", "string");
        param.set_string_member ("description", "Parameter description");
        properties.set_object_member ("param", param);
        
        input_schema.set_object_member ("properties", properties);
        
        var required = new Json.Array ();
        required.add_string_element ("param");
        input_schema.set_array_member ("required", required);
        
        var definition = new Mcp.Tools.Types.ToolDefinition ("my_tool", input_schema);
        definition.description = "Description of my tool";
        
        base (definition);
    }
    
    protected override async Mcp.Tools.Types.CallToolResult do_execute (Json.Object arguments) throws Error {
        string param = get_string_arg (arguments, "param");
        
        // Process input
        string result = process_parameter (param);
        
        return create_text_result ("Result: %s".printf (result));
    }
    
    private string process_parameter (string input) {
        // Custom processing logic
        return input.up ();
    }
}

Prompt Template Pattern

public class MyPrompt : Mcp.Prompts.BaseTemplate {
    public MyPrompt () {
        base ("my_prompt", "My Prompt", "Description of my prompt");
        
        // Add arguments
        add_argument ("topic", "Topic", "The topic to generate content for", true);
        add_argument ("style", "Style", "Writing style", false, "neutral");
    }
    
    protected override Gee.ArrayList<Mcp.Prompts.Types.PromptMessage> generate_messages (Json.Object arguments) {
        var messages = new Gee.ArrayList<Mcp.Prompts.Types.PromptMessage> ();
        
        string topic = get_string_arg (arguments, "topic");
        string style = get_string_arg (arguments, "style", "neutral");
        
        string template = """Generate {{style}} content about {{topic}}.""";
        
        messages.add (create_user_message (template, arguments));
        return messages;
    }
    
    private string? get_string_arg (Json.Object arguments, string name, string? default_value = null) {
        if (arguments.has_member (name)) {
            return arguments.get_string_member (name);
        }
        return default_value;
    }
}

JSON-RPC Protocol Implementation

The library implements the JSON-RPC 2.0 specification for MCP:

Request Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tools/list",
  "params": {}
}

Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "tools": [...]
  }
}

Error Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": null
  }
}

Notification Format

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed",
  "params": {}
}

Type System

The library uses Vala's type system for compile-time safety:

Primitives

• string - Text data
• int/int64 - Integer values
• double - Floating-point values
• bool - Boolean values

Collections

• Gee.ArrayList<T> - Dynamic arrays
• HashTable<K,V> - Key-value maps
• Json.Object - JSON objects
• Json.Array - JSON arrays
• Json.Node - Generic JSON value

Null Safety

Optional types use ? suffix:

public string? description { get; set; }  // Can be null
public string name { get; set; }           // Cannot be null

Error Handling

Error Hierarchy

Mcp.Core.McpError
├── PARSE_ERROR (-32700)
├── INVALID_REQUEST (-32600)
├── METHOD_NOT_FOUND (-32601)
├── INVALID_PARAMS (-32602)
├── INTERNAL_ERROR (-32603)
├── RESOURCE_NOT_FOUND (-32604)
└── TRANSPORT_ERROR (-32605)

Error Handling Pattern

try {
    // MCP operation
} catch (Mcp.Core.McpError e) {
    // Handle MCP-specific errors
    stderr.printf ("MCP Error [%d]: %s\n", e.code, e.message);
} catch (GLib.Error e) {
    // Handle other errors
    stderr.printf ("GLib Error: %s\n", e.message);
}

Best Practices

1. Always validate input before processing
2. Use structured results for complex data
3. Handle errors gracefully and provide meaningful messages
4. Follow async patterns for I/O operations
5. Document custom components with Valadoc comments
6. Use appropriate MIME types for resources
7. Implement subscription notifications for dynamic content
8. Test with real MCP clients to verify compatibility

Version Compatibility

The library follows MCP specification version "2025-11-25" and maintains backward compatibility where possible. Future versions will be additive and non-breaking.

Migration Guide

From Custom JSON-RPC to Jsonrpc

If you were using custom JSON-RPC handling in previous versions:

1. No API changes required - The public API remains the same
2. Internal improvements - Better error handling and IO reliability
3. Performance benefits - Optimized JSON parsing and message handling
4. Standard compliance - Full JSON-RPC 2.0 compliance through jsonrpc-glib-1.0

The migration is transparent for existing code using the library's public API.