# 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](#core-namespace)
2. [Types Namespace](#types-namespace)
3. [Resources Namespace](#resources-namespace)
4. [Tools Namespace](#tools-namespace)
5. [Prompts Namespace](#prompts-namespace)
6. [Common Namespace](#common-namespace)

## Core Namespace

### Mcp.Core.Server

The main server class that orchestrates all MCP functionality.

#### Constructor

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

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

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

#### Methods

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

#### Example

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

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

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

#### Properties

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

### Mcp.Types.Protocol.ServerCapabilities

Server capabilities configuration.

#### Properties

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

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

### Mcp.Types.Protocol.ToolsCapabilities

Tool-related capabilities.

#### Properties

```vala
public bool list_changed { get; set; }
```

### Mcp.Types.Protocol.PromptsCapabilities

Prompt-related capabilities.

#### Properties

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

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

```vala
public TextContent (string text)
```

#### Properties

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

#### Mcp.Types.Common.ImageContent

Image content block.

#### Constructor

```vala
public ImageContent (string data, string mime_type)
```

#### Properties

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

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

#### Mcp.Types.Common.TextResourceContents

Text-based resource contents.

#### Constructor

```vala
public TextResourceContents (string uri, string text)
```

#### Properties

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

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

#### Properties

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

#### Mcp.Types.Common.Annotations

Resource annotations.

#### Properties

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

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

```vala
protected BaseProvider ()
```

#### Properties

```vala
public signal void resource_updated (string uri);
```

#### Methods

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

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

```vala
public Resource (string uri, string name)
```

#### Properties

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

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

```vala
public ResourceTemplate (string uri_template, string name)
```

#### Properties

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

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

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

#### Methods

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

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

```vala
public ToolDefinition (string name, Json.Object input_schema)
```

#### Properties

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

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

### Mcp.Tools.Types.CallToolResult

Result of calling a tool.

#### Constructor

```vala
public CallToolResult ()
```

#### Properties

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

#### Methods

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

### Mcp.Tools.Types.ToolExecution

Tool execution settings.

#### Constructor

```vala
public ToolExecution (string task_support = "forbidden")
```

#### Properties

```vala
public string task_support { get; set; }
```

### Mcp.Tools.Types.ToolAnnotations

Tool annotations.

#### Constructor

```vala
public ToolAnnotations ()
```

#### Properties

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

## Prompts Namespace

### Mcp.Prompts.Template

Interface for prompt templates.

#### Methods

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

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

#### Methods

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

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

```vala
public PromptDefinition (string name)
```

#### Properties

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

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

### Mcp.Prompts.Types.PromptArgument

Prompt argument definition.

#### Constructor

```vala
public PromptArgument (string name)
```

#### Properties

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

#### Methods

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

### Mcp.Prompts.Types.GetPromptResult

Result of getting a prompt.

#### Constructor

```vala
public GetPromptResult ()
```

#### Properties

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

#### Methods

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

### Mcp.Prompts.Types.PromptMessage

Prompt message.

#### Constructor

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

#### Properties

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

#### Methods

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

## Usage Patterns

### Server Initialization Pattern

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

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

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

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

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

### Response Format

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

### Error Response Format

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

### Notification Format

```json
{
  "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:
```vala
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

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