# OS Agent MCP Server

Small local [MCP](https://modelcontextprotocol.io/) server for OS tasks. It
gives an agent tools for finding files, reading and writing text, moving and
deleting paths, checking terminal processes, and opening a terminal in a
directory.

The tools return ordinary paths and short results, so an agent can use one
result as the input for the next call. For example, it can find a project and
open a terminal in that project directory.

## Requirements

- Python 3.10 or newer
- The dependencies installed in the existing `.venv`

## Run it

From the project directory, activate the virtual environment:

```powershell
.\.venv\Scripts\Activate.ps1
```

Limit the server to the current project directory:

```powershell
$env:MCP_ALLOWED_ROOTS = (Get-Location).Path
```

Then start the server:

```powershell
os-agent-mcp
```

The server uses stdio, so it waits for an MCP client and does not print a
normal command prompt message. It is configured for VS Code in
`.vscode/mcp.json`.

To install or repair the project dependencies in the existing environment:

```powershell
python -m pip install -e ".[dev]"
```

## Development

```powershell
python -m pytest
```

The tests cover the file search, file writing, and path permission behavior.