# 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.
* **Warning:** Replace `/home/chubb/...` with your actual home directory path if you copy this file manually.
2. **`mcp-config.local.json`** (For developers)
* Uses local paths (e.g., `/home/your_username/...`).
* Use this if you are developing the project locally.
* **Warning:** Replace `/home/chubb/...` with your actual home directory path.
**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
# Ensure we are in the project directory
cd "$HOME/gitea-mcp" || exit 1
# Load .env explicitly using source
if [ -f .env ]; then
set -a
source .env
set +a
fi
export XDG_RUNTIME_DIR="$HOME/.fnm_runtime"
mkdir -p "$XDG_RUNTIME_DIR"
eval "$(~/.local/share/fnm/fnm env --shell zsh)"
# Run GLOBAL package and redirect stderr to a file for debugging
exec gitea-mcp-proxy "$@" 2> /tmp/mcp-error.log
```
---
## 🛡 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
