# Gitea MCP Proxy Agent & Tools 🚀

> **Note:** This repository is a read-only mirror. Please submit issues and PRs to the main repository at [git.boringstudio.by](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy).

A comprehensive solution based on **Model Context Protocol (MCP)**, providing AI (e.g., Gemini in WebStorm) access to development tools, memory, search, and infrastructure management. The project combines Gitea task management, secure command execution, long-term memory, Google search, and Docker operations.

## 📦 System Components

The project includes a set of MCP servers ensuring a full development cycle:

### 1. Core Tools
*   **Gitea Proxy Agent** (`index.js`)
    *   Interaction with Gitea (API) and local environment (Shell).
    *   Optional proxying via Cloudflare Zero Trust.
    *   Secure command execution.
*   **Memory Server**
    *   Long-term memory for preserving context and project knowledge (`memory.json`).
*   **Sequential Thinking**
    *   Tool for deep step-by-step analysis of complex tasks and solution self-correction.

### 2. Data & Files
*   **Filesystem**
    *   Secure access to the file system.
    *   Restricted to directories: `/home/your_username/gitea-mcp` and `/home/your_username/boring_studio`.
*   **Fetch**
    *   Fetching web pages and converting their content to Markdown for AI reading.
*   **Google Search**
    *   Searching for up-to-date information on the internet.

### 3. Infrastructure
*   **Docker (Read-Only)**
    *   View container lists, logs, and images.
    *   Runs in "read-only" mode for security.

---

## 🛠 Capabilities

### Gitea Proxy
*   **Tools:**
    *   `list_issues` — Get a list of open issues (supports pagination).
    *   `search_issues` — Search issues by keywords and status.
    *   `get_issue_details` — Read full issue description and status.
    *   `create_issue` — Create a new issue.
    *   `update_issue` — Update an issue (status, title, description, labels).
    *   `add_comment` — Add a comment to an issue.
    *   `list_labels` — List repository labels.
    *   `list_branches` — List repository branches.
    *   `create_pull_request` — Create a Pull Request.
    *   `run_safe_shell` — Secure execution of console commands in WSL.
*   **Resources:** View repository issues and files.
*   **Prompts:** `analyze-issue`, `create-bug-report`.

### Docker
*   `list_containers` — List containers.
*   `fetch_container_logs` — Read logs.
*   `list_images` — List images.

### Filesystem
*   `read_file`, `list_directory`, `search_files` — Full control over files in allowed zones.

### Fetch
*   `fetch` — Get content by URL (optimized for LLM).

---

## ⚙️ Requirements

*   **WSL2** (Ubuntu)
*   **Node.js** (managed via `fnm`)
*   **Python** (with `uv` or `pip`)
*   **Docker Desktop** (WSL integration)
*   **Gitea Token**
*   **Cloudflare Service Token** (Optional)
*   **Google Custom Search API Key**

---

## 🚀 Installation and Setup

### 1. Quick Start (npx)

If the package is published to npm:
```bash
npx @boringstudio_org/gitea-mcp-proxy
```

### 2. Clone Repository
```bash
cd ~
git clone https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy.git
cd gitea-mcp
npm install
```

### 3. Environment Variables Setup
Create `.env` file in the project root (where you run the server).

**.env** (Gitea & Cloudflare):
```env
CF_ID=your_cf_client_id (optional)
CF_SECRET=your_cf_client_secret (optional)
GITEA_TOKEN=your_gitea_token
GOOGLE_API_KEY=your_api_key
GOOGLE_SEARCH_ENGINE_ID=your_engine_id (or GOOGLE_CSE_ID)
```

### 4. IDE Connection (WebStorm / IntelliJ)

There are two configuration files available:

1.  **`mcp-config.npm.json`** (Recommended for users)
    *   Uses `npx` (or `gitea-mcp-proxy` global binary) to run the tools.
    *   Requires `Node.js` and `uv` installed.
    *   **Important:** You must create a `.env` file in the directory where you run the IDE/server.

2.  **`mcp-config.local.json`** (For developers)
    *   Uses local paths (e.g., `/home/your_username/...`).
    *   Use this if you are developing the project locally.

**Note for WSL users:**
If you use `fnm` or `nvm` in WSL, ensure `npx` and `node` are available in the PATH when running via `wsl.exe`.
You might need to use a wrapper script or explicit initialization in the config.
Example `start-mcp.sh`:
```bash
#!/bin/zsh
export XDG_RUNTIME_DIR="$HOME/.fnm_runtime"
mkdir -p "$XDG_RUNTIME_DIR"
eval "$(~/.local/share/fnm/fnm env --shell zsh)"
exec gitea-mcp-proxy "$@"
```

---

## 🛡 Security

*   **Gitea Proxy:** ENV cleaning, dangerous command prohibition.
*   **Docker:** `--read-only` mode prevents accidental deletion or stopping of containers.
*   **Filesystem:** Access strictly limited to specified directories.
*   **Isolation:** All processes run inside WSL.

## 📝 License

MIT