# SecureOps MCP: Modular File Operations & Code Review Server

**SecureOps MCP** is a secure, modular **Model Context Protocol (MCP)** implementation built using the FastMCP Python framework. The project exposes secure file manipulation tools, directory/file resources, and code-analysis prompt templates. It includes a decoupled client CLI orchestrating a **Gemini 2.5 Flash** agent capable of performing autonomous tool-use loops.

---

## Key Features

1. **Autonomous Tools**:
   * `write_file`: Dynamically creates parent folders and writes files using `utf-8` encoding (with real-time progress logging).
   * `delete_file`: Safely deletes files from the project directory, with explicit type checking.
2. **Local Resources**:
   * `dir://.`: Lists the entire workspace structure along with file metadata (size, last modified).
   * `file:///{file_name}`: Directly reads file contents via the standard URI scheme.
3. **Prompt Templates**:
   * `code_review`: Automatically extracts and packages source code files into structured prompts for comprehensive quality reviews.
   * `documentation_generator`: Generates technical documentation prompts for target source files.
4. **Path Traversal Security**:
   * Every file operation is validated through a secure path resolver that restricts reads, writes, and deletions to the base workspace directory.
5. **Decoupled Architecture**:
   * Separates the technical stdio communication layer (`MCPClient`) from the LLM cognitive layer (`GeminiAgent`), enabling clean modular testing.

---

## Installation & Setup

1. **Create and Activate Virtual Environment**:
   ```bash
   python -m venv .venv
   .venv\Scripts\activate
   ```
2. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```
3. **Configure API Key**:
   Create a file named `.env` in the root folder and add your Gemini API key:
   ```env
   GEMINI_API_KEY=your_actual_gemini_api_key_here
   ```

---

## 1. Running via the Interactive CLI Client (With LLM Logic)

To converse with the model, perform code reviews, or generate documentation using the actual **Gemini 2.5 Flash** model, you must run the client CLI.

### Run Command:
```bash
.venv\Scripts\python.exe -m mcp_client.main mcp_server/main.py
```

### Menu Options & Example Testing Inputs:

#### Option 1: Generate Documentation
* **Selection**: `1`
* **Input (`file_path`)**: `mcp_server/utils.py`
* **Input (`doc_name`)**: `utils_docs.md`
* **What happens**: The server packages `utils.py` into a template. Gemini generates a markdown documentation file and writes it to disk.
* **Progress Screenshot**:
  ![File Writing Progress](docs/images/create_file.png)

#### Option 2: Review Code
* **Selection**: `2`
* **Input (`file_path`)**: `mcp_server/utils.py`
* **What happens**: Gemini performs a deep code-review of the path security helper and lists findings directly in your terminal.
* **Code Review Output Screenshots**:
  ![Code Review Part 1](docs/images/code_review_1.png)
  ![Code Review Part 2](docs/images/code_review_2.png)

#### Option 3: Read File
* **Selection**: `3`
* **Input (`file_path`)**: `requirements.txt`
* **What happens**: The client directly queries the server's resource handler to load and print the file.

#### Option 4: Read Current Directory
* **Selection**: `4`
* **What happens**: Prints a formatted terminal table showing all directories and files in your workspace.

#### Option 5: Converse with Agent (Autonomous Tool Use)
* **Selection**: `5`
* **Input Query**: `Delete utils_docs.md please`
* **What happens**: Gemini reads your text, identifies that it needs to run a tool, calls `delete_file` on the MCP server, and prints the result.
* **Tool Execution Screenshot**:
  ![Dynamic File Deletion](docs/images/delete_file.png)

---

## 2. Running via the FastMCP Web Inspector (Interface Testing)

The **MCP Inspector** is a browser-based developer dashboard used to test and validate your server's exposed tools, resources, and prompts in isolation. 

> [!IMPORTANT]
> **No LLM Responses in the Inspector**: The web interface only tests that the MCP server's schemas are correct and compiles prompts successfully. To see the actual AI-generated responses, you must run it via the CLI client (Method 1).

### Run Command:
```bash
.venv\Scripts\fastmcp dev mcp_server/main.py
```
This command starts the local dev server and prints a URL (e.g., `http://localhost:5173`).

### Configuration in the Browser:
In the left pane, set up the connection parameters:
1. **Command**: `.venv\Scripts\fastmcp.exe` *(or your absolute path to the executable)*
2. **Arguments**: `run mcp_server/main.py --no-banner`
3. Click the **Connect** button.

### How to Test Features in the Web UI:
* **Tools Tab**: Select `write_file`, enter a path (e.g., `test.txt`) and content, then click **Run** to execute the local file write.
* **Resources Tab**: Click `list_files_resource` (`dir://.`) or `read_file_resource` to view raw JSON listings and text from the local folder.
* **Prompts Tab**: Select `code_review`, enter a path (e.g., `mcp_server/utils.py`), and click **Run** to see the fully compiled prompt template including your source code.

* **Interface Screenshot**:
  ![MCP Inspector Interface](docs/images/mcp_inspector.png)