# Uten Agent Terminal MCP

An MCP server that gives an AI agent terminal-style capabilities through
[FastMCP](https://github.com/jlowin/fastmcp). It exposes tools for running shell
commands, executing Python code, reading and writing files, searching text, and
creating or deleting folders.

## Features

- Run shell commands through the `bash` tool.
- Execute inline Python code.
- Execute Python files.
- Find files with glob patterns.
- Search file content with `findstr`.
- Read and write files.
- Create and delete folders.
- Run over MCP `stdio`, which makes it suitable for local MCP clients.

## Requirements

- Python 3.12 or newer
- `fastmcp`

The project currently uses Python `3.14` locally, as defined in
`.python-version`.

## Installation

Clone the project and install the package in editable mode:

```powershell
git clone <your-repository-url>
cd MCP_PYPI
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
```

If you use `uv`, you can install the locked dependencies with:

```powershell
uv sync
```

## Usage

Start the MCP server:

```powershell
uten_agentic_terminal_mcp
```

The server runs with `stdio` transport, so it is intended to be launched by an
MCP-compatible client.

After installation, you can also run the module directly:

```powershell
python -m agentic_terminal.main
```

## Available Tools

| Tool | Description |
| --- | --- |
| `bash(command)` | Runs a shell command and returns stdout or stderr. |
| `python_code(code)` | Runs inline Python code and returns stdout or stderr. |
| `python_file(file)` | Runs a Python file and returns stdout or stderr. |
| `glob(pattern)` | Returns files matching a glob pattern. |
| `grep(pattern, file)` | Searches a file using Windows `findstr`. |
| `read_file(file)` | Reads a file and returns its contents. |
| `write_file(file, content)` | Writes content to a file. |
| `create_folder(folder)` | Creates a folder if it does not already exist. |
| `delete_folder(folder)` | Deletes a folder recursively. |

## Project Structure

```text
MCP_PYPI/
+-- src/
|   +-- agentic_terminal/
|       +-- __init__.py
|       +-- main.py
|       +-- tools.py
+-- dist/
+-- pyproject.toml
+-- uv.lock
+-- README.md
```

## Build

To build the package:

```powershell
python -m build
```

The generated wheel and source distribution will be placed in `dist/`.

## Publish

After building, publish with Twine:

```powershell
twine upload dist/*
```

For TestPyPI:

```powershell
twine upload --repository testpypi dist/*
```

## Security Notice

This MCP server exposes powerful local system tools. It can run shell commands,
execute Python code, write files, and delete folders. Only use it with MCP
clients and agents that you trust, and avoid running it with unnecessary system
privileges.

## License

This project is licensed under the MIT License. See `LICENSE` for details.