From 7e49d8c8d4f692ddb8a100cee7ffc295040718b0 Mon Sep 17 00:00:00 2001 From: Data Warrior Date: Tue, 11 Nov 2025 10:33:54 -0700 Subject: [PATCH] Docs: Add Windows Cursor development environment setup guide --- CONTRIBUTING.md | 10 +++ CURSOR_WINDOWS_SETUP.md | 172 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 CURSOR_WINDOWS_SETUP.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11e65be..1cc0408 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,16 @@ Before you begin, ensure you have: 4. **Access to the repository** (fork or direct access) +### Development Environment Setup + +**Windows Users with Cursor IDE:** + +If you're setting up a Windows development environment with Cursor IDE, see [CURSOR_WINDOWS_SETUP.md](CURSOR_WINDOWS_SETUP.md) for detailed step-by-step instructions on: +- Installing and configuring the Gitea MCP Server +- Setting up Cursor IDE to work with Gitea +- Configuring authentication tokens +- Testing the connection + ### Repository Setup 1. **Fork the repository** (if you don't have direct write access): diff --git a/CURSOR_WINDOWS_SETUP.md b/CURSOR_WINDOWS_SETUP.md new file mode 100644 index 0000000..55ca53a --- /dev/null +++ b/CURSOR_WINDOWS_SETUP.md @@ -0,0 +1,172 @@ +# 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). +