# Copilot Instructions for windows-mcp-server
## Project Overview
This is a Windows MCP (Model Context Protocol) server exposing system information and control tools for Windows environments. It is designed for integration with AI agents and MCP clients (e.g., LM Studio, Claude Desktop, VSCode MCP Inspector).
## Architecture & Key Files
- `main.py`: All MCP tool definitions and core logic. Each tool is a Python function decorated with `@mcp.tool`, returning structured data (Pydantic models or dicts) for system queries.
- `utils.py`: (If present) Utility functions for system operations. Some helpers are now inlined in `main.py`.
- `pyproject.toml`: Dependency and build configuration. Uses Python 3.13+, `mcp[cli]`, `psutil`, `pydantic`.
- `README.md`: Up-to-date documentation of available tools, parameters, and return types. Use this as the canonical source for tool shape and examples.
## Developer Workflows
- **Run the server:**
```powershell
uv run --with mcp mcp dev main.py
```
This installs dependencies and launches the MCP server for local development.
- **Connect MCP clients:**
Use the configuration block in `README.md` to connect external clients. The server exposes tools as described in the README table.
- **No explicit test suite** is present. Validate changes by running the server and using MCP Inspector or a compatible client.
## Patterns & Conventions
- **Tool Definition:**
- Use `@mcp.tool` decorator for each exposed function.
- Return types should be structured (Pydantic models or dicts) for easy client parsing.
- Example:
```python
@mcp.tool(name="Windows-drive-status", description="Get drive info")
def get_drive_status(drive: str) -> DriveInfo:
...
```
- **System Queries:**
- Prefer pure Python APIs (`psutil`, `shutil`, `ctypes`) for robustness.
- PowerShell is used only for GPU info, always parsed as JSON for reliability.
- **Drive Handling:**
- Normalize drive letters (accepts "C", "C:", "C:\\").
- Use helpers for drive enumeration and disk usage.
- **Process Sampling:**
- For CPU, prime `cpu_percent`, sleep 0.3s, then sample for accuracy.
- Return top processes as a list of `ProcessInfo` objects.
- **Error Handling:**
- Return default/empty structured objects on error (never raise uncaught exceptions to MCP clients).
## Integration Points
- **External dependencies:**
- `psutil` for system info
- `pydantic` for models
- `mcp[cli]` for MCP protocol
- **No database or persistent storage** is used.
- **No background tasks or async code**; all tools are synchronous.
## Example Tool Entry
See `README.md` for a full table. Example:
| Tool Name | Description | Parameters | Returns |
|-----------|-------------|------------|---------|
| Windows-top-processes-by-cpu | Get top X processes by CPU usage | amount: int = 5 | ProcessInfo[] { pid, name, cpu_percent, memoryMB } |
## How to Extend
- Add new tools by defining a function in `main.py` and decorating with `@mcp.tool`.
- If the function is a utility that does not return external data but provide to tools, use a helper function in `utils.py`. Use this also for functions that are used by multiple tools.
- Use structured return types for new tools.
- Update `README.md` table and examples when adding or changing tools.
## Memory Update:
- If any new information was gathered during the interaction, update your memory as follows:
- a) Create entries for new entities or facts.
- b) Connect them to the current entities using relations
- c) Store facts about them as observations
---
If any conventions or workflows are unclear, please request clarification or examples from the user.
