Metadata-Version: 2.4
Name: gemini-cli-mcp
Version: 0.1.0
Summary: Gemini CLI MCP Server
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.116.0
Requires-Dist: mcp[cli]>=1.10.1
Requires-Dist: pytest>=8.4.1
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: uv>=0.7.20
Requires-Dist: uvicorn>=0.35.0

# `gemini-cli-mcp` Python Server

This directory contains the Python implementation of the `gemini-cli-mcp` server. It uses FastAPI to expose `gemini-cli` functionalities as MCP-compliant tools.

## 1. Features

This server exposes the following `gemini-cli` commands as MCP Tools:

*   `gemini_ask`: Ask a question to the Gemini model.
*   `gemini_agent`: Run a complex prompt with Gemini Agent in auto-execution (`--yolo`) mode.
*   `gemini_git_commit`: Generate a conventional commit message from staged changes and perform a `git commit`.
*   `gemini_git_pr`: Automatically commit, push, and create a Pull Request.
*   `gemini_git_diff`: Summarize code changes using Gemini AI.

## 2. Technology Stack

| Category         | Technology           |
| :--------------- | :------------------- |
| **Language**     | Python 3.12+         |
| **Web Framework**| FastAPI              |
| **Process Exec** | `asyncio.subprocess` |
| **CLI Framework**| Typer (via `mcp-cli`)|
| **Packaging**    | Poetry / `pyproject.toml` |

## 3. Setup

### Prerequisites

*   Python 3.12 or higher.
*   `gemini-cli` installed globally and accessible in your system's PATH.
*   `git` installed and configured.

### Installation

1.  Navigate to the `server_py` directory:
    ```bash
    cd server_py
    ```
2.  Install dependencies using `uv` (recommended) or `pip`:
    ```bash
    uv pip install -r requirements.txt
    # or
    pip install -r requirements.txt
    ```

### Environment Variables

The server uses environment variables for configuration. You can set these in a `.env` file in the project root (`/Users/hackme/workspace/ai/mcp-server/gemini-cli-mcp/.env`) or directly in your environment.

*   `GEMINI_MODEL`: Specifies the Gemini model to use (e.g., `gemini-2.5-flash`).
*   `GEMINI_ALL_FILES`: Set to `true` to include all files in context (`--all-files`).
*   `GEMINI_SANDBOX`: Set to `true` to enable sandbox mode (`--sandbox`).
*   `GEMINI_API_KEY`: Your Gemini API key (required for Docker/server environments).
*   `PROJECT_ROOT`: The root directory of your project (important for `gemini-cli` operations).
*   `QUERY_TIMEOUT`: Timeout for `gemini-cli` commands in seconds.
*   `USE_SHELL`: Set to `true` to execute `gemini-cli` commands via shell (defaults to `false`).
*   `DEBUG`: Set to `true` to enable detailed logging to `log/{date}.log`.

## 4. Running the Server

The user can select the execution mode via a CLI flag.

*   **STDIO Mode**: `python main.py` (for direct CLI interaction)
*   **HTTP Mode**: `uvicorn main:app --host 0.0.0.0 --port 8000` (for AI agent integration)

### Docker

A `Dockerfile` is provided to build and run the server in a container.

1.  **Build the Image:** From the project root, run:
    ```bash
    docker build -t gemini-cli-mcp-python -f server_py/Dockerfile .
    ```

2.  **Run the Container:**
    ```bash
    # Using an .env file
    docker run --env-file ../.env -p 8000:8000 gemini-cli-mcp-python

    # Passing environment variables directly
    docker run -e GEMINI_API_KEY=your_api_key -p 8000:8000 gemini-cli-mcp-python
    ```

## 5. Packaging & Distribution

The package will be distributed on PyPI. The `pyproject.toml` file defines a script entry point for the `gemini-cli-mcp` command, which will be deployed using `poetry build` and `twine`.

### CLI Usage

After installing the package via pip, you can use the CLI entry point:

```bash
$ gemini-cli-mcp
```

This will launch the server in STDIO mode. To run in HTTP mode, use:

```bash
$ gemini-cli-mcp --http
```

## 6. Tool Usage

The server acts as a smart wrapper around `gemini-cli`. It constructs and executes the appropriate `gemini-cli` command based on the MCP tool invocation.

For example:
*   `gemini_ask(question="What is AI?")` translates to `gemini ask --model {model} --all-files --sandbox --prompt "What is AI?"`
*   `gemini_agent(prompt="Do something complex.")` translates to `gemini agent --model {model} --all-files --sandbox --yolo --prompt "Do something complex."`

## 7. Logging

Set the `DEBUG` environment variable to `true` to enable detailed logging to `server_py/log/{YYYY-MM-DD}.log`.
