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.

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:

npx @boringstudio_org/gitea-mcp-proxy

2. Clone Repository

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):

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:

#!/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