mirror of
https://github.com/MAKS-IT-COM/maksit-gitea-cursor.git
synced 2026-09-29 20:48:10 +02:00
135 lines
4.3 KiB
Markdown
135 lines
4.3 KiB
Markdown
# 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
|