# mcp-pypi

## What this project is
This project is an MCP server built with FastMCP. It exposes tools that give an MCP client or agent basic terminal abilities, such as running commands, running Python, and working with files and folders. The server uses the MCP **stdio transport**, so it communicates over standard input and output and is meant to be started by an MCP client.

## What it does
1. Starts an MCP server over stdio.
2. Registers a set of tools that act on the local machine.

## MCP tools
The server provides these tools:

| Tool | Purpose | Notes |
| --- | --- | --- |
| `bash(command: str)` | Run a shell command. | Uses the system shell. Returns stderr on error. On success, it does not return a value in the current implementation. |
| `python_code(code: str)` | Run Python code. | Executes `python -c <code>`. Returns stdout or error text. |
| `python_file(file: str)` | Run a Python file. | Executes `python <file>`. Returns stdout or error text. |
| `glob(pattern: str)` | Find files by pattern. | Returns a list of matching paths. |
| `grep(pattern: str, file: str)` | Search for a pattern in a file. | Uses `findstr` on Windows. Prints matches and does not return a value in the current implementation. |
| `read_file(file: str)` | Read a file. | Returns file content or error text. |
| `write_file(file: str, content: str)` | Write a file. | Overwrites if the file exists and returns a success message or error text. |
| `create_folder(folder: str)` | Create a folder. | Returns a message if it was created or already exists. |
| `delete_folder(folder: str)` | Delete a folder. | Recursively removes the folder if it exists and returns a message. |

## Install
Python 3.10 or later is required.

From the repository root:

```
python -m pip install .
```

## Run as an MCP server
Start the server with the stdio transport:

```
mcp_pypi
```

Or:

```
python -m mcp_pypi.main
```

Then configure your MCP client to launch it with stdio. Example:

```
{
  "mcpServers": {
    "mcp-pypi": {
      "command": "mcp_pypi",
      "args": []
    }
  }
}
```

## Project layout
1. `src/mcp_pypi/tools.py` defines the MCP tools.
2. `src/mcp_pypi/main.py` starts the MCP server over stdio.
3. `test.py` starts the server directly for quick local runs.