# Gitea Development Environment Setup Guide for Windows & Cursor

**Objective:** This document details the complete process for configuring a local development environment on a Windows PC to work with a Gitea-hosted source code repository. It covers connecting the Cursor IDE using the Model Context Protocol (MCP) and cloning a project repository to begin work.

## Core Components

*   **Gitea:** The remote Git server where the project's code is stored.

*   **Gitea MCP Server:** A command-line application that acts as a bridge between Cursor and Gitea.

*   **Cursor IDE:** The code editor used for development.

*   **Git for Windows:** The underlying version control software used for all `git` commands.

---

## Phase 1: Environment Setup and Configuration

### Step 1: Download and Prepare the Gitea MCP Server

The first step is to get the bridge application that allows Cursor to communicate with Gitea.

1.  **Download the Binary:**

    *   Navigate to the official Gitea MCP releases page: [https://gitea.com/gitea/gitea-mcp/releases](https://gitea.com/gitea/gitea-mcp/releases)

    *   From the latest release, download the zip archive for Windows, named `gitea-mcp_Windows_x86_64.zip`.

2.  **Create a Permanent Location:**

    *   Create a dedicated folder on your computer where this tool will live permanently. For this guide, we used: `D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64`

3.  **Extract the Files:**

    *   Extract the contents of the downloaded `.zip` file into the folder you just created. The most important file is `gitea-mcp.exe`.

### Step 2: Generate a Gitea Access Token

Cursor needs a secure "password" to access your Gitea account. This is called an Access Token.

1.  **Navigate to Gitea Settings:** Go to your Gitea instance's Applications page: [https://git.parkingmeter.info/user/settings/applications](https://git.parkingmeter.info/user/settings/applications)

2.  **Generate a New Token:**

    *   Give the token a descriptive name (e.g., "Cursor on Windows PC").

    *   Set the following permissions to **Read and Write**:

        *   `issue`

        *   `repository`

        *   `user`

    *   Click **"Generate Token"**.

3.  **Copy and Save the Token:**

    *   **CRITICAL:** Gitea will display the token only once. Copy it immediately and save it in a secure place (like a password manager or a temporary text file). You will need it in the next steps.

### Step 3: Create the Server Startup Script (`run-gitea.bat`)

To ensure the Gitea MCP Server starts reliably every time, we will create a simple startup script.

1.  **Create the File:**

    *   In the same folder where you extracted `gitea-mcp.exe`, create a new file named `run-gitea.bat`.

2.  **Edit the Script:**

    *   Open `run-gitea.bat` with a text editor (like Notepad) and paste the following content:

    ```batch
    @echo off
    echo Starting Gitea MCP server in HTTP mode...
    echo Do not close this window!
    D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64\gitea-mcp.exe -t http --host https://git.parkingmeter.info --token YOUR_GITEA_TOKEN_HERE
    ```

3.  **Add Your Token:**

    *   In the script, **replace `YOUR_GITEA_TOKEN_HERE` with the actual Gitea token** you copied in Step 2.

    *   Save and close the file.

### Step 4: Configure Cursor's MCP Tools

This is the most important step. We need to tell Cursor how to find and use your new Gitea server.

1.  **Open Cursor's MCP Settings:**

    *   In Cursor, navigate to the settings UI.

    *   Go to the **"Tools & MCP"** section.

    *   You will see a file named **`mcp.json`**. Open this file.

2.  **Add the Gitea Server Configuration:**

    *   Inside the `"mcpServers": { ... }` object, add the following configuration block. Be sure to add a comma `,` after the preceding entry.

    ```json
        "gitea-local": {
          "url": "http://localhost:8080/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_GITEA_TOKEN_HERE"
          }
        }
    ```

3.  **Add Your Token:**

    *   Again, **replace `YOUR_GITEA_TOKEN_HERE` with your actual Gitea token**.

    *   **IMPORTANT:** The word `Bearer` followed by a space must be kept in front of the token.

4.  **Save the `mcp.json` file.**

### Step 5: Test the Connection Workflow

This is the process you will follow each time you want to use the Gitea integration.

1.  **Manually Start the Server:**

    *   Using File Explorer, navigate to your `gitea-mcp_Windows_x86_64` folder.

    *   **Double-click the `run-gitea.bat` script.**

    *   A black command prompt window will appear and stay open. This is your server. **You must keep this window running** while you use the integration in Cursor.

2.  **Restart and Test in Cursor:**

    *   Completely close and reopen the Cursor application to ensure it loads the new configuration.

    *   Open the AI Chat panel (`Ctrl + L`).

    *   Send the command: `@gitea-local list my repositories`.

    *   The AI may initially be confused. **Confirm that it should make a direct API call** to your Gitea instance, providing the URL (`https://git.parkingmeter.info`) when prompted.

    *   **Success is confirmed when the AI returns a formatted list of your Gitea repositories.**

### Step 6: Clone the Project Repository

The final setup step is to download the project's source code to your machine.

1.  **Open a Terminal in Cursor:**

    *   Go to the top menu and select **Terminal -> New Terminal**.

2.  **Navigate to Your Projects Directory:**

    *   In the terminal, change to the folder where you want to store your projects. We used:

        ```bash
        cd /d/OneDrive/GIT_Parkingmeter
        ```

3.  **Clone the Repository:**

    *   Run the `git clone` command with the project's URL:

        ```bash
        git clone https://git.parkingmeter.info/Mycelium/tendril.git
        ```

---

## Phase One Complete

At this point, your environment is fully configured. You have successfully linked Cursor to your Gitea account and downloaded a local copy of the project code. You are now ready to move on to Phase Two: The Development Workflow (editing, pushing, and pulling code).