Metadata-Version: 2.4
Name: vcosmos-mcp-server
Version: 0.1.3
Summary: A Model Context Protocol (MCP) server for querying vCosmos Test Logic API - Units Under Test (UUTs) and tasks
Project-URL: Homepage, https://github.com/yourusername/vcosmos-mcp-server
Project-URL: Repository, https://github.com/yourusername/vcosmos-mcp-server
Project-URL: Documentation, https://github.com/yourusername/vcosmos-mcp-server#readme
Project-URL: Bug Tracker, https://github.com/yourusername/vcosmos-mcp-server/issues
Author-email: Iverson Lu <iverson.lu@hp.com>
Maintainer-email: Iverson Lu <iverson.lu@hp.com>
License: MIT
License-File: LICENSE
Keywords: api,mcp,model-context-protocol,test,vcosmos
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: mcp>=1.13.1
Description-Content-Type: text/markdown

# 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

```mermaid
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:**
   ```bash
   uv add mcp
   ```

2. **Set your authentication token:**
   ```powershell
   # PowerShell
   $env:VCOSMOS_TOKEN = "your_token_here"
   
   # Linux/Mac
   export VCOSMOS_TOKEN="your_token_here"
   ```

3. **Run the server:**
   ```bash
   python vcosmos_mcp_server.py
   ```

### VS Code Integration

Add this configuration to your VS Code MCP settings:

```json
{
  "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:
```json
{
  "tool": "query_vcosmos_uuts",
  "arguments": {
    "site": "hp-tnn-prd",
    "limit": 10,
    "health_status": "Healthy"
  }
}
```

Query recent failed tasks:
```json
{
  "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:**
```json
[
  {
    "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:**
```json
[
  {
    "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:

```bash
# 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! 🚀
