GET / - Health Check

Basic health check endpoint

{
  "status": "healthy",
  "message": "Nexus MCP Server Enhanced API is running",
  "tools_count": 39,
  "server_info": {
    "name": "NexusServer-Enhanced",
    "version": "0.9.1",
    "type": "HTTP-MCP Bridge"
  }
}

GET /tools - List All Tools

Get complete list of available tools with metadata

{
  "tools": [
    {
      "name": "add",
      "description": "Calculate the sum of two numbers (a + b)",
      "input_schema": {
        "type": "object",
        "properties": {
          "a": {"type": "number", "description": "First number"},
          "b": {"type": "number", "description": "Second number"}
        },
        "required": ["a", "b"]
      }
    }
  ],
  "count": 39,
  "server_info": {...}
}

GET /tools/{tool_name} - Tool Details

Get detailed information about a specific tool

{
  "name": "add",
  "description": "Calculate the sum of two numbers (a + b)",
  "input_schema": {
    "type": "object",
    "properties": {
      "a": {"type": "number"},
      "b": {"type": "number"}
    },
    "required": ["a", "b"]
  }
}

POST /execute - Execute Tool

Execute any available tool with parameters

Request:

{
  "tool_name": "add",
  "arguments": {
    "a": 10,
    "b": 5
  }
}

Response:

{
  "success": true,
  "result": {
    "sum": 15,
    "operation": "10 + 5",
    "message": "Addition completed successfully"
  },
  "execution_time": 0.001,
  "tool_name": "add"
}

POST /tools/{tool_name}/execute - Direct Tool Execution

Execute specific tool directly via URL path

curl -X POST http://localhost:9999/tools/add/execute \
  -H "Content-Type: application/json" \
  -d '{"a": 15, "b": 27}'

GET /health - Detailed Health Check

Comprehensive health status with system information

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:45Z",
  "uptime": 3600,
  "system": {
    "cpu_percent": 5.2,
    "memory_percent": 15.8,
    "disk_percent": 45.3
  },
  "tools": {
    "total": 39,
    "enabled": 39,
    "failed": 0
  }
}

GET /metrics - Prometheus Metrics

Prometheus-compatible metrics for monitoring

# HELP mcp_tool_executions_total Total number of tool executions
# TYPE mcp_tool_executions_total counter
mcp_tool_executions_total{tool_name="add",status="success"} 42

# HELP mcp_tool_execution_duration_seconds Tool execution duration
# TYPE mcp_tool_execution_duration_seconds histogram
mcp_tool_execution_duration_seconds_bucket{tool_name="add",le="0.1"} 38

Using requests library

import requests

# API base URL
BASE_URL = "http://localhost:9999"

def call_nexus_tool(tool_name, arguments):
    """Execute a Nexus tool via HTTP API"""
    response = requests.post(
        f"{BASE_URL}/execute",
        json={
            "tool_name": tool_name,
            "arguments": arguments
        }
    )
    return response.json()

# Example usage
result = call_nexus_tool("add", {"a": 10, "b": 5})
print(f"Result: {result['result']['sum']}")

# Generate secure password
password_result = call_nexus_tool("password_generate", {
    "length": 16,
    "include_symbols": True
})
print(f"Password: {password_result['result']['password']}")

# Get system information
system_info = call_nexus_tool("system_overview", {})
print(f"OS: {system_info['result']['os']}")

Using fetch API

class NexusClient {
    constructor(baseUrl = 'http://localhost:9999') {
        this.baseUrl = baseUrl;
    }

    async executeTool(toolName, arguments) {
        const response = await fetch(`${this.baseUrl}/execute`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                tool_name: toolName,
                arguments: arguments
            })
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    }

    async listTools() {
        const response = await fetch(`${this.baseUrl}/tools`);
        return await response.json();
    }
}

// Example usage
const nexus = new NexusClient();

// Execute mathematical calculation
nexus.executetool('add', { a: 15, b: 27 })
    .then(result => {
        console.log(`Sum: ${result.result.sum}`);
    });

// Generate UUID
nexus.executeTools('generate_uuid', { version: 4 })
    .then(result => {
        console.log(`UUID: ${result.result.uuid}`);
    });

Using net/http

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type NexusClient struct {
    BaseURL string
    Client  *http.Client
}

type ExecuteRequest struct {
    ToolName  string                 `json:"tool_name"`
    Arguments map[string]interface{} `json:"arguments"`
}

type ExecuteResponse struct {
    Success       bool                   `json:"success"`
    Result        map[string]interface{} `json:"result"`
    ExecutionTime float64                `json:"execution_time"`
    ToolName      string                 `json:"tool_name"`
}

func NewNexusClient(baseURL string) *NexusClient {
    return &NexusClient{
        BaseURL: baseURL,
        Client:  &http.Client{},
    }
}

func (c *NexusClient) ExecuteTool(toolName string, arguments map[string]interface{}) (*ExecuteResponse, error) {
    reqBody := ExecuteRequest{
        ToolName:  toolName,
        Arguments: arguments,
    }
    
    jsonData, err := json.Marshal(reqBody)
    if err != nil {
        return nil, err
    }
    
    resp, err := c.Client.Post(
        c.BaseURL+"/execute",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
    
    var result ExecuteResponse
    err = json.Unmarshal(body, &result)
    return &result, err
}

func main() {
    client := NewNexusClient("http://localhost:9999")
    
    // Execute addition
    result, err := client.ExecuteTool("add", map[string]interface{}{
        "a": 10,
        "b": 5,
    })
    
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    fmt.Printf("Sum: %.0f\n", result.Result["sum"])
}

Using reqwest and serde

use reqwest;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Serialize)]
struct ExecuteRequest {
    tool_name: String,
    arguments: HashMap,
}

#[derive(Deserialize)]
struct ExecuteResponse {
    success: bool,
    result: HashMap,
    execution_time: f64,
    tool_name: String,
}

struct NexusClient {
    base_url: String,
    client: reqwest::Client,
}

impl NexusClient {
    fn new(base_url: String) -> Self {
        NexusClient {
            base_url,
            client: reqwest::Client::new(),
        }
    }

    async fn execute_tool(&self, tool_name: &str, arguments: HashMap) -> Result> {
        let request = ExecuteRequest {
            tool_name: tool_name.to_string(),
            arguments,
        };

        let response = self.client
            .post(&format!("{}/execute", self.base_url))
            .json(&request)
            .send()
            .await?;

        let result: ExecuteResponse = response.json().await?;
        Ok(result)
    }
}

#[tokio::main]
async fn main() -> Result<(), Box> {
    let client = NexusClient::new("http://localhost:9999".to_string());
    
    let mut args = HashMap::new();
    args.insert("a".to_string(), serde_json::Value::Number(serde_json::Number::from(10)));
    args.insert("b".to_string(), serde_json::Value::Number(serde_json::Number::from(5)));
    
    let result = client.execute_tool("add", args).await?;
    
    println!("Sum: {}", result.result.get("sum").unwrap());
    
    Ok(())
}

Standard Error Response

{
  "success": false,
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'invalid_tool' not found",
    "details": {
      "available_tools": ["add", "subtract", "multiply", "divide"],
      "suggestion": "Did you mean 'add'?"
    }
  },
  "timestamp": "2024-01-15T10:30:45Z"
}