# gremlin_mcp
Learning from this Youtube TUT https://www.youtube.com/watch?v=io02ZM0ADqM MCP Full Course for Beginners
Note: I asked Copilot or some other LLM to clean up the existing code for tools and added any others it thought would be useful. There are several tools that should be used with caution as they can modify the files and directories. I haven't tested tool usage properly. Need to build something useful with this mcp and with proper guardrails.


An MCP (Model Context Protocol) server that gives an agent terminal and
file-management capabilities: run shell/Python commands, search and read
files, and create/edit/delete files and folders.

Built on [FastMCP](https://github.com/jlowin/fastmcp).

## Tools

The server exposes **21 tools**, grouped as follows:

**Shell / Python execution**

| Tool | Purpose |
|------|---------|
| `run_command` | Run a shell command (cmd on Windows, sh on Unix) |
| `python_code` | Execute a Python snippet with the running interpreter |
| `python_file` | Execute a Python script file |

**Search & read**

| Tool | Purpose |
|------|---------|
| `glob_files` | List absolute paths matching a glob pattern |
| `grep` | Matching lines (with line numbers) in a single file |
| `search_text` | Recursive search under a directory |
| `read_file` | Read a whole file as UTF-8 |
| `read_file_lines` | Read a 1-based range of lines |
| `get_env_var` | Read an environment variable |

**Files & folders**

| Tool | Purpose |
|------|---------|
| `write_file` / `append_file` | Write or append UTF-8 text |
| `replace_in_file` | Find & replace, returns the count changed |
| `copy_file` / `move_file` | Copy or move (auto-creates parent dirs) |
| `delete_file` / `delete_folder` | Delete a file or folder |
| `create_folder` | Create a folder (including parents) |
| `list_dir` / `get_cwd` / `file_info` / `tree` | Directory introspection |

## Requirements

- Python >= 3.13
- `fastmcp >= 3.4.7`

## Installation

```bash
uv sync            # recommended
# or
python -m pip install -e .
```

## Starting the server

The server communicates over **stdio**, which is FastMCP's default transport.
Start it from the repo root with any of:

```bash
uv run python -m gremlin_mcp.main
python test.py serve
python start_gremlin_mcp_server.py
```

## Testing

### 1. Offline smoke test (no MCP client needed)

```bash
python test.py
```

This imports the server, calls **every** tool (creating and cleaning up a
temporary folder), and prints a `[PASS]`/`[FAIL]` summary plus a total.

### 2. Interactive web inspector

```bash
fastmcp dev inspector src/gremlin_mcp/main.py
```

Opens the MCP Inspector in your browser so you can browse the tools, read
their descriptions/examples, and call them interactively.

> Note: `fastmcp dev` is a subcommand group, so the `inspector` subcommand
> must be passed explicitly (`fastmcp dev src/...` alone will fail).

### 3. Quick CLI checks

```bash
fastmcp inspect src/gremlin_mcp/main.py    # server info + tool summary
fastmcp list   src/gremlin_mcp/main.py     # just the tool names
```

### 4. Connecting from an MCP client

Point your editor/client's MCP config at the server via stdio, for example:

```json
{
  "mcpServers": {
    "gremlin-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "gremlin_mcp.main"]
    }
  }
}
```

## Example tool calls

As an agent would issue them:

```
list_dir(path="src")
search_text(pattern="TODO", directory="src")
read_file(file="pyproject.toml")
write_file(file="hello.py", content="print('hi')")
python_code(code="print(6 * 7)")          # -> exit=0 / 42
replace_in_file(path="config.py", old="DEBUG = True", new="DEBUG = False")
tree(path=".", depth=2)
```

## Project layout

```
src/gremlin_mcp/
├── __init__.py
├── tools.py   # all tool definitions (21 tools)
└── main.py    # FastMCP server entry point
test.py        # offline smoke test / optional server launcher
start_gremlin_mcp_server.py   # minimal "run the server" launcher
```

## Security note

`run_command`, `python_code` and `python_file` execute arbitrary code.
Only expose this server to agents/clients you trust, and consider running
it inside a sandbox or restricted working directory.