173 lines
6.0 KiB
Markdown
173 lines
6.0 KiB
Markdown
# 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).
|
|
|