vcosmos-mcp-server 0.1.0

A Model Context Protocol (MCP) server for querying vCosmos Test Logic API - Units Under Test (UUTs) and tasks

vCosmos UUT MCP Server

A Model Context Protocol (MCP) server that provides tools to query Units Under Test (UUTs) and tasks from the vCosmos Test Logic API using the official MCP Python library.

🎯 Overview

This production-ready MCP server exposes vCosmos API functionality to MCP clients (like VS Code, Claude, etc.), allowing them to:

• Query UUTs with comprehensive filtering options (pool, site, status, product, health, etc.)
• Query vCosmos tasks with filtering and sorting capabilities
• Get data in optimized flat JSON format for LLM consumption
• Support for sorting and pagination

🏗️ Architecture

graph TD
    A[MCP Client<br/>VS Code, Claude, etc.] -->|MCP Protocol<br/>JSON-RPC over stdio| B[vCosmos MCP Server]
    
    subgraph B[vCosmos MCP Server]
        C[MCP Tools<br/>• query_vcosmos_uuts<br/>• query_vcosmos_tasks]
        D[VCosmosAPIClient Class<br/>built-in HTTP client]
    end
    
    B -->|HTTPS/REST| E[vCosmos Test Logic API<br/>https://vcosmos.hpcloud.hp.com/api/tl]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#e8f5e8

🔧 Available Tools

query_vcosmos_uuts

Query vCosmos test devices (UUT) with comprehensive filtering and sorting options.

Parameters:

• pool (optional): Device pool ID
• id (optional): UUT ID
• site (optional): Site name
• ip (optional): IP address
• status (optional): Device status
• internal_product_name (optional): Internal product name
• marketing_product_name (optional): Marketing product name
• phase (optional): Product phase
• release_year (optional): Release year
• limit (optional, default: 25): Return result count limit (1-5000)
• health_status (optional): Health status (Healthy, Unhealthy, Offline, Unregistered)
• sort_by (optional, default: "id"): Sort field
• sort_direction (optional, default: "asc"): Sort direction (asc, desc)

Returns:

• Flat JSON array of UUT objects with fields like: id, hostname, serial_number, site, ip_address, status, product_name, health_status, etc.

query_vcosmos_tasks

Query vCosmos tasks with filtering and sorting capabilities.

Parameters:

• status (optional): Task status filter (Waiting, Pending, Running, Done, etc.)
• result_status (optional): Result status filter (PASS, FAIL, None, etc.)
• site (optional): Site name filter
• job_id (optional): Job ID filter
• executor (optional): Executor filter
• uut_serial_number (optional): UUT serial number filter
• limit (optional, default: 25): Task count limit (1-50)
• sort_by (optional, default: "createdAt"): Sort field
• sort_direction (optional, default: "desc"): Sort direction (asc, desc)

Returns:

• Flat JSON array of task objects with fields like: id, job_id, status, result_status, finished_at, uut_serial_number

🚀 Quick Start

Prerequisites

• Python 3.8+
• Official MCP Python library
• Valid vCosmos authentication token

Installation

1. Install dependencies:

   uv add mcp
   

2. Set your authentication token:

   # PowerShell
   $env:VCOSMOS_TOKEN = "your_token_here"
   
   # Linux/Mac
   export VCOSMOS_TOKEN="your_token_here"
   

3. Run the server:

   python vcosmos_mcp_server.py
   

VS Code Integration

Add this configuration to your VS Code MCP settings:

{
  "mcpServers": {
    "vcosmos": {
      "command": "python",
      "args": ["d:/Dev/thin_mcp/vcosmos_mcp_server.py"],
      "env": {
        "VCOSMOS_TOKEN": "your_token_here"
      }
    }
  }
}

📋 Current Implementation

The current implementation (vcosmos_mcp_server.py) is a production-ready MCP server that includes:

• ✅ Official MCP Library: Uses the official MCP Python library
• ✅ Async Implementation: Full async/await support
• ✅ stdio Transport: JSON-RPC over stdio communication
• ✅ Two Main Tools: query_vcosmos_uuts and query_vcosmos_tasks
• ✅ Comprehensive Filtering: Multiple filter options for both UUTs and tasks
• ✅ Flat JSON Output: Optimized for LLM consumption
• ✅ Error Handling: Robust error handling and validation
• ✅ Built-in HTTP Client: No external dependencies except MCP library

Example Usage

Query UUTs by site:

{
  "tool": "query_vcosmos_uuts",
  "arguments": {
    "site": "hp-tnn-prd",
    "limit": 10,
    "health_status": "Healthy"
  }
}

Query recent failed tasks:

{
  "tool": "query_vcosmos_tasks", 
  "arguments": {
    "result_status": "FAIL",
    "limit": 5,
    "sort_by": "createdAt",
    "sort_direction": "desc"
  }
}

🔮 Features

UUT Query Features

• Filter by pool, site, IP, status, product names, phase, release year
• Health status filtering (Healthy, Unhealthy, Offline, Unregistered)
• Sorting by various fields (id, site, ip, status, etc.)
• Pagination with configurable limits (1-5000)
• Flat JSON output with clean field names

Task Query Features

• Filter by status, result status, site, job ID, executor
• UUT serial number filtering
• Sort by creation date, status, executor, etc.
• Pagination with configurable limits (1-50)
• Extracts UUT serial numbers and result statuses

Data Format

All responses are in flat JSON format optimized for LLM processing:

UUT Response Example:

[
  {
    "id": "6710bdbdf3e08f001a43b627",
    "hostname": "test-hostname",
    "serial_number": "8CC1180BC4", 
    "site": "hp-tnn-prd",
    "ip_address": "15.37.194.115",
    "status": "Idle",
    "product_name": "HP EliteDesk 800 G8",
    "health_status": "Healthy",
    "last_updated": "2025-08-22T13:45:54.377Z"
  }
]

Task Response Example:

[
  {
    "id": "68a955a3a5e663f2cca2e788",
    "job_id": "job123",
    "status": "Running", 
    "result_status": "PASS",
    "finished_at": "2025-08-23T10:30:00Z",
    "uut_serial_number": "000277072S"
  }
]

📁 File Structure

d:\Dev\thin_mcp\
├── vcosmos_mcp_server.py     # ✅ Production MCP Server (main file)
├── main.py                   # ✅ Original working script
├── vcosmos_client.py         # ✅ Legacy VCosmosAPI client module
├── README.md                 # ✅ Main project documentation
└── README_MCP.md            # ✅ This MCP server documentation

🧪 Testing the Server

You can test the server functionality by running it directly and checking the logs:

# Run the server and check startup logs
python vcosmos_mcp_server.py

# The server will show:
# INFO - Starting vCosmos MCP Server (using MCP library)
# INFO - VCOSMOS_TOKEN configured

For integration testing with MCP clients, configure the server in your MCP client and test the tools through the client interface.

🎯 Integration with MCP Clients

This server is ready for integration with:

• VS Code: Through MCP extensions and settings configuration
• Claude: Through MCP protocol support
• Custom Applications: Any application supporting the MCP standard

🔒 Security Notes

• The server uses the VCOSMOS_TOKEN environment variable for authentication
• Built-in HTTP client with proper timeout handling (30 seconds)
• No credentials are stored in the code
• All API communication uses HTTPS

🐛 Troubleshooting

1. "VCOSMOS_TOKEN environment variable not set":

   • Set the environment variable with your vCosmos API token
   • Verify the token has the correct permissions

2. "Request error" or API failures:

   • Check your network connection to vcosmos.hpcloud.hp.com
   • Verify your token is valid and not expired
   • Check if the vCosmos API endpoints are accessible

3. "Tool execution error":

   • Check the server logs for detailed error messages
   • Validate your tool parameters match the schema
   • Ensure limit values are within the allowed ranges

4. Empty results []:

   • Check if there are UUTs/tasks matching your filter criteria
   • Try broader filter parameters or remove filters to see all data
   • Verify your token has access to the requested site/pool

⚡ Performance Notes

• UUT queries support up to 5000 results per request
• Task queries support up to 50 results per request
• Built-in request timeout of 30 seconds
• Flat JSON output optimized for LLM token efficiency
• Minimal memory footprint with direct field extraction

This production-ready MCP server provides a robust bridge between your vCosmos infrastructure and AI/automation tools! 🚀