svrnty-mcp-server/docs/api/README.md

# OpenHarbor.MCP.Server - API Reference

**Version:** 1.0.0
**Last Updated:** 2025-10-19
**Status:** Production-Ready

---

## Table of Contents

- [Core Abstractions](#core-abstractions)
  - [IMcpServer](#imcpserver)
  - [IMcpTool](#imcptool)
- [Infrastructure](#infrastructure)
  - [McpServer](#mcpserver)
  - [HttpTransport](#httptransport)
- [Models](#models)
  - [McpToolSchema](#mcptoolschema)
  - [McpToolResult](#mcptoolresult)
- [ASP.NET Core Integration](#aspnet-core-integration)
  - [Service Extensions](#service-extensions)
  - [Endpoint Mapping](#endpoint-mapping)

---

## Core Abstractions

### IMcpServer

**Namespace:** `OpenHarbor.MCP.Core.Abstractions`

Interface defining the core MCP server contract.

#### Methods

##### ExecuteToolAsync

```csharp
Task<McpToolResult> ExecuteToolAsync(
    string toolName,
    Dictionary<string, object> parameters,
    CancellationToken cancellationToken = default)
```

Executes a tool by name with the given parameters.

**Parameters:**
- `toolName` (string): The name of the tool to execute
- `parameters` (Dictionary<string, object>): Tool input parameters
- `cancellationToken` (CancellationToken): Optional cancellation token

**Returns:** `Task<McpToolResult>` - The result of the tool execution

**Throws:**
- `ToolNotFoundException` - If the tool doesn't exist
- `InvalidParametersException` - If parameters don't match schema
- `OperationCanceledException` - If cancelled

**Example:**
```csharp
var result = await server.ExecuteToolAsync(
    "search_documents",
    new Dictionary<string, object>
    {
        ["query"] = "architecture patterns",
        ["maxResults"] = 10
    }
);
```

##### ListToolsAsync

```csharp
Task<IEnumerable<McpToolInfo>> ListToolsAsync(
    CancellationToken cancellationToken = default)
```

Lists all available tools.

**Returns:** `Task<IEnumerable<McpToolInfo>>` - Collection of tool metadata

**Example:**
```csharp
var tools = await server.ListToolsAsync();
foreach (var tool in tools)
{
    Console.WriteLine($"{tool.Name}: {tool.Description}");
}
```

---

### IMcpTool

**Namespace:** `OpenHarbor.MCP.Core.Abstractions`

Interface for implementing MCP tools.

#### Properties

##### Name

```csharp
string Name { get; }
```

Unique identifier for the tool (e.g., "search_documents").

**Requirements:**
- Must be lowercase
- Use underscores for word separation
- No spaces or special characters

##### Description

```csharp
string Description { get; }
```

Human-readable description of what the tool does.

##### Schema

```csharp
McpToolSchema Schema { get; }
```

JSON Schema defining the tool's input parameters.

#### Methods

##### ExecuteAsync

```csharp
Task<McpToolResult> ExecuteAsync(
    Dictionary<string, object> parameters,
    CancellationToken cancellationToken = default)
```

Executes the tool with validated parameters.

**Parameters:**
- `parameters` (Dictionary<string, object>): Validated input parameters
- `cancellationToken` (CancellationToken): Cancellation support

**Returns:** `Task<McpToolResult>` - Success or error result

**Example Implementation:**
```csharp
public class SearchTool : IMcpTool
{
    public string Name => "search_documents";
    public string Description => "Search documents by query";

    public McpToolSchema Schema => new()
    {
        Type = "object",
        Properties = new Dictionary<string, McpProperty>
        {
            ["query"] = new()
            {
                Type = "string",
                Description = "Search query",
                Required = true
            }
        }
    };

    public async Task<McpToolResult> ExecuteAsync(
        Dictionary<string, object> parameters,
        CancellationToken ct = default)
    {
        var query = parameters["query"].ToString();
        var results = await SearchAsync(query, ct);
        return McpToolResult.Success(results);
    }
}
```

---

## Infrastructure

### McpServer

**Namespace:** `OpenHarbor.MCP.Infrastructure`

Default implementation of `IMcpServer`.

#### Constructor

```csharp
public McpServer(ToolRegistry toolRegistry)
```

**Parameters:**
- `toolRegistry` (ToolRegistry): Registry containing all available tools

**Example:**
```csharp
var registry = new ToolRegistry();
registry.AddTool(new SearchTool());
registry.AddTool(new GetDocumentTool());

var server = new McpServer(registry);
```

#### Methods

##### StartAsync

```csharp
Task StartAsync(CancellationToken cancellationToken = default)
```

Starts the MCP server (initializes transport).

##### StopAsync

```csharp
Task StopAsync(CancellationToken cancellationToken = default)
```

Gracefully stops the server.

---

### HttpTransport

**Namespace:** `OpenHarbor.MCP.AspNetCore.Extensions`

HTTP transport implementation for MCP protocol.

#### Configuration

```json
{
  "Mcp": {
    "Transport": {
      "Type": "Http",
      "Port": 5050
    }
  }
}
```

#### Endpoints

##### POST /mcp/invoke

Invokes MCP methods via JSON-RPC 2.0.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": {
      "query": "test"
    }
  }
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": "Search results...",
    "isSuccess": true
  }
}
```

##### GET /health

Health check endpoint.

**Response:**
```json
{
  "status": "Healthy",
  "timestamp": "2025-10-19T12:00:00Z"
}
```

---

## Models

### McpToolSchema

**Namespace:** `OpenHarbor.MCP.Core.Models`

JSON Schema representation for tool parameters.

#### Properties

```csharp
public class McpToolSchema
{
    public string Type { get; set; }  // "object"
    public Dictionary<string, McpProperty> Properties { get; set; }
    public List<string> Required { get; set; }
}

public class McpProperty
{
    public string Type { get; set; }  // "string", "number", "boolean", "array", "object"
    public string Description { get; set; }
    public bool Required { get; set; }
    public object Default { get; set; }
}
```

#### Example

```csharp
var schema = new McpToolSchema
{
    Type = "object",
    Properties = new Dictionary<string, McpProperty>
    {
        ["query"] = new()
        {
            Type = "string",
            Description = "Search query",
            Required = true
        },
        ["maxResults"] = new()
        {
            Type = "number",
            Description = "Maximum number of results",
            Required = false,
            Default = 10
        }
    }
};
```

---

### McpToolResult

**Namespace:** `OpenHarbor.MCP.Core.Models`

Represents the result of a tool execution.

#### Properties

```csharp
public class McpToolResult
{
    public bool IsSuccess { get; set; }
    public string Content { get; set; }
    public string ErrorMessage { get; set; }
    public int? ErrorCode { get; set; }
}
```

#### Static Factory Methods

##### Success

```csharp
public static McpToolResult Success(object content)
```

Creates a successful result.

**Example:**
```csharp
return McpToolResult.Success(new
{
    results = documents,
    count = documents.Count
});
```

##### Error

```csharp
public static McpToolResult Error(string message, int? code = null)
```

Creates an error result.

**Example:**
```csharp
return McpToolResult.Error("Document not found", 404);
```

---

## ASP.NET Core Integration

### Service Extensions

**Namespace:** `OpenHarbor.MCP.AspNetCore`

#### AddMcpServer

```csharp
public static IServiceCollection AddMcpServer(
    this IServiceCollection services,
    McpServer server)
```

Registers MCP server and dependencies.

**Example:**
```csharp
var registry = new ToolRegistry();
registry.AddTool(new SearchTool());

var server = new McpServer(registry);
builder.Services.AddMcpServer(server);
```

---

### Endpoint Mapping

#### MapMcpEndpoints

```csharp
public static IEndpointRouteBuilder MapMcpEndpoints(
    this IEndpointRouteBuilder endpoints,
    McpServer server)
```

Maps HTTP endpoints for MCP protocol.

**Example:**
```csharp
var app = builder.Build();
app.MapMcpEndpoints(server);
```

**Mapped Endpoints:**
- `POST /mcp/invoke` - JSON-RPC 2.0 method invocation
- `GET /health` - Health check

---

## JSON-RPC 2.0 Methods

### tools/list

Lists all available tools.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "search_documents",
        "description": "Search documents by query",
        "inputSchema": { ... }
      }
    ]
  }
}
```

### tools/call

Executes a tool.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": {
      "query": "test",
      "maxResults": 10
    }
  }
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": { "results": [...] },
    "isSuccess": true
  }
}
```

---

## Error Handling

### Error Codes

| Code | Meaning |
|------|---------|
| `-32700` | Parse error (invalid JSON) |
| `-32600` | Invalid request |
| `-32601` | Method not found |
| `-32602` | Invalid params |
| `-32603` | Internal error |

### Error Response

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "method": "invalid_method"
    }
  }
}
```

---

## Complete Example

### Creating an MCP Server

```csharp
using OpenHarbor.MCP.Core;
using OpenHarbor.MCP.Core.Abstractions;
using Microsoft.AspNetCore.Builder;

// 1. Create tools
public class SearchTool : IMcpTool
{
    public string Name => "search_documents";
    public string Description => "Search documents";

    public McpToolSchema Schema => new()
    {
        Type = "object",
        Properties = new Dictionary<string, McpProperty>
        {
            ["query"] = new() { Type = "string", Required = true }
        }
    };

    public async Task<McpToolResult> ExecuteAsync(
        Dictionary<string, object> parameters,
        CancellationToken ct = default)
    {
        var query = parameters["query"].ToString();
        // Implementation here
        return McpToolResult.Success($"Results for: {query}");
    }
}

// 2. Set up server
var builder = WebApplication.CreateBuilder(args);

var registry = new ToolRegistry();
registry.AddTool(new SearchTool());

var server = new McpServer(registry);
builder.Services.AddMcpServer(server);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenLocalhost(5050);
});

var app = builder.Build();

// 3. Map endpoints
app.MapMcpEndpoints(server);
app.MapHealthChecks("/health");

// 4. Start server
await app.RunAsync();
```

### Calling from Client

```bash
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "search_documents",
      "arguments": {
        "query": "test"
      }
    }
  }'
```

---

## See Also

- [Server Architecture](../architecture.md)
- [Configuration Guide](../configuration.md)
- [Security Guide](../security.md)
- [TDD Guide](../tdd-guide.md)

---

**Document Type:** API Reference
**Version:** 1.0.0
**Last Updated:** 2025-10-19
**Maintained By:** Svrnty Development Team