# MaksIT Gitea for Cursor

Cursor plugin (`maksit-gitea-cursor`) for self-hosted Gitea: repositories, issues, pull requests, code review, Actions, releases, packages, and organizations.

Source: [MAKS-IT-COM/maksit-gitea-cursor](https://github.com/MAKS-IT-COM/maksit-gitea-cursor).

Each user points the plugin at **their own Gitea instance**. Example:

```text
https://git.example.com
```

The plugin never assumes gitea.com. All API calls go to the URL you configure.

The MCP server inside the plugin is still named `gitea`, so tools stay `gitea_whoami`, `gitea_issue`, and so on.

Requires **Node 18+** on the machine running Cursor (the MCP server is a local stdio process).

## What you get

| Piece | Role |
| --- | --- |
| **MCP server** | Talks to the Gitea REST API (`/api/v1`) |
| **Semantic tools** | Repos, issues, PRs, git, Actions, releases, wiki, packages, orgs, users, notifications |
| **Catalog** | `gitea_catalog` + `gitea_call` for extra REST operations (admin/secrets/raw stay off by default) |
| **Skills / agents / commands** | Review PRs, create issues and PRs, triage, Actions status, ship releases |

The server only talks to `{GITEA_URL}/api/v1`. Destructive site-admin, token, and secret tools are **opt-in**.

## Configure

Create a token in Gitea: **Settings → Applications → Generate New Token**. Grant the minimum scopes you need (repo, issue, write). Do not grant site-admin unless you also enable admin tools below.

### In the Cursor plugin

Set:

- **Gitea URL** — `https://git.example.com` (no trailing slash; HTTPS required except localhost)
- **Gitea access token** — the personal access token

These map to `GITEA_URL` and `GITEA_TOKEN`.

Optional flags (plugin variables or env):

| Variable | Default | Effect |
| --- | --- | --- |
| `GITEA_READ_ONLY` | off | Block POST/PUT/PATCH/DELETE |
| `GITEA_ENABLE_ADMIN` | off | Register `gitea_admin` and allow `/admin` operations |
| `GITEA_ENABLE_RAW` | off | Register `gitea_request` (raw path + method) |
| `GITEA_ENABLE_SECRETS` | off | Allow Actions secrets, runner tokens, and PAT create/list/delete |
| `GITEA_ALLOW_HTTP` | off | Allow `http://` for a trusted private network (tokens go in cleartext) |

### Local MCP (without installing the plugin)

Build once (`cd server && npm install && npm run build`), then add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gitea": {
      "command": "node",
      "args": ["${userHome}/path/to/maksit-gitea-cursor/server/dist/index.js"],
      "env": {
        "GITEA_URL": "https://git.example.com",
        "GITEA_TOKEN": "your-token"
      }
    }
  }
}
```

Self-signed certificates must be trusted by the OS. The plugin does not disable TLS verification.

## Develop

```bash
cd server
npm install
npm test
npm run build
node ../scripts/validate-plugin.mjs
```

Smoke-check the process (needs Node 18+):

```bash
# prints a config error without env; with env, waits on stdio
node dist/index.js
```

Load the plugin locally:

1. Copy or symlink this repo to `~/.cursor/plugins/local/maksit-gitea-cursor`
2. Reload Cursor
3. Set `GITEA_URL` and `GITEA_TOKEN` on the plugin

On Windows PowerShell:

```powershell
New-Item -ItemType Junction -Path "$env:USERPROFILE\.cursor\plugins\local\maksit-gitea-cursor" -Target "<path-to-this-repo>"
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the publish checklist.

## Tools

Preferred for everyday work:

- `gitea_whoami` — instance + current user
- `gitea_repo`, `gitea_contents`, `gitea_git`
- `gitea_issue`, `gitea_pull`, `gitea_release`
- `gitea_actions`, `gitea_org`, `gitea_user`
- `gitea_wiki`, `gitea_package`, `gitea_notification`

For anything else:

1. `gitea_catalog` — search by keyword or tag (filtered by the flags above)
2. `gitea_call` — invoke the `operationId`
3. `gitea_request` — only if `GITEA_ENABLE_RAW=true`

## Security

- Tokens stay in Cursor plugin variables / your env. They are not stored in this repo.
- Paths reject absolute URLs and `..` segments. Redirects that leave `{GITEA_URL}/api/v1` are refused.
- HTTPS is required except localhost.
- See [SECURITY.md](SECURITY.md) to report issues.

## Publish

Install from GitHub, or submit updates at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish). Official listing is curated; [cursor.directory](https://cursor.directory) is the community catalog.

## License

Apache-2.0