cursor_Setup
Deploy Development / deploy (push) Successful in 44s
Build Test / lint-backend (push) Successful in 0s
Build Test / build-frontend (push) Successful in 13s

This commit is contained in:
Lars committed 2026-04-04 14:05:50 +02:00
1 parent c607cd1833
commit dc87e7f3b8
13 files changed
+1328

No files matched your search

+64
View File
@@ -0,0 +1,64 @@
# Gitea MCP-Server für Cursor
Damit der Agent **strukturierte Tools** nutzen kann (`gitea_list_issues`, `gitea_close_issue`, …), registrierst du diesen MCP-S **lokal** in Cursor.
## 1. Abhängigkeit
```powershell
pip install -r scripts/gitea/requirements-mcp.txt
```
Oder: `pip install "mcp>=1.2.0"`
## 2. Secrets
Wie beim CLI: **`GITEA_*` in der Repo-Root `.env`** (wird von `gitea_lib` geladen), **oder** dieselben Variablen in der MCP-`env` (siehe unten).
**Niemals** Tokens in Git committen.
## 3. Cursor MCP konfigurieren
**Variante A – UI:** Einstellungen → **MCP** / Tools → Server hinzufügen → Typ „Command“:
- **Command:** `python` (oder voller Pfad zu `python.exe`)
- **Args:** vollständiger Pfad zu `mcp_server_gitea.py`, z. B.
`C:\Dev\mitai-jinkendo\scripts\gitea\mcp_server_gitea.py`
- **Working directory (optional):** `C:\Dev\mitai-jinkendo\scripts\gitea`
- **Env:** nur nötig, wenn du **keine** `.env` im Repo nutzt:
```text
GITEA_BASE_URL=http://192.168.2.144:3000
GITEA_OWNER=Lars
GITEA_REPO=mitai-jinkendo
GITEA_TOKEN=…
```
**Variante B – JSON:** Datei `~/.cursor/mcp.json` (Benutzer) oder projektbezogen laut Cursor-Doku. Beispielinhalt siehe **`.cursor/mcp.json.example`** im Repo (Platzhalter, ohne echtes Token).
Cursor nach Änderung **vollständig neu starten**.
## 4. Netzwerk
Die Gitea-URL muss von deinem Rechner erreichbar sein (z. B. `192.168.2.144:3000` im LAN).
## 5. Repo-Zugriff
- **API:** Tool `gitea_get_repo_file` (Dateiinhalt / Metadaten).
- **Git (lokal):** unverändert `git pull` / Agent liest Workspace-Dateien – dafür brauchst du kein MCP.
## Bereitgestellte Tools (Kurzüberblick)
| Tool | Zweck |
|------|--------|
| `gitea_list_issues` | Issues listen, optional alle Seiten |
| `gitea_get_issue` | Ein Issue mit Body |
| `gitea_comment_issue` | Kommentar |
| `gitea_create_issue` | Neu anlegen |
| `gitea_close_issue` / `gitea_reopen_issue` | Status |
| `gitea_get_repo_file` | Datei remote via API |
## Issue-Triage durch den Agent
Sinnvoller Ablauf: Issues listen → je Issue **Code/Commits prüfen** → bei eindeutig erledigt: kurzer Kommentar + **close**; bei teilweise: Kommentar mit Checkboxen; bei unklar: nur Kommentar, **nicht** schließen.
Autonom alles schließen ist fehleranfällig; klare Regeln oder manuelle Freigabe für `close` empfohlen.
+68
View File
@@ -0,0 +1,68 @@
# Gitea API – lokales CLI
Dient dazu, **Issues** auf deiner Gitea-Instanz zu lesen und anzulegen – mit den in **`.env`** gesetzten Variablen (nicht committen).
## Umgebungsvariablen (Root `.env`)
| Variable | Beispiel |
|----------|----------|
| `GITEA_BASE_URL` | `http://192.168.2.144:3000` |
| `GITEA_TOKEN` | Personal Access Token (nur Scope **repo** + **issue** nötig) |
| `GITEA_OWNER` | `Lars` |
| `GITEA_REPO` | `mitai-jinkendo` |
## Voraussetzung
Python 3.10+ (nur Standardbibliothek).
## Aufruf (im Repo-Root)
```powershell
# Issues auflisten (offen)
python scripts/gitea/gitea_api.py issues list
# Issues mit State
python scripts/gitea/gitea_api.py issues list --state all
# Ein Issue lesen
python scripts/gitea/gitea_api.py issues get 42
# Issue anlegen (Titel + Body aus Datei oder direkt)
python scripts/gitea/gitea_api.py issues create --title "Fix: …" --body "…"
python scripts/gitea/gitea_api.py issues create --title "Fix: …" --body-file path/to/body.md
# Kommentar
python scripts/gitea/gitea_api.py issues comment 42 --body "…"
# Schließen / wieder öffnen
python scripts/gitea/gitea_api.py issues close 42
python scripts/gitea/gitea_api.py issues reopen 42
# Alle Issues (alle Seiten, Vorsicht bei großen Repos)
python scripts/gitea/gitea_api.py issues list --all-pages --state open
# Markdown-Datei (z. B. Audit-Template) als Issue-Body
python scripts/gitea/gitea_api.py issues create --title "…" --body-file .claude/docs/audit/.../gitea/TEMPLATE_P0-....md
```
## Repository-Inhalt (read-only)
```powershell
# Datei über Gitea-API (bei Dateien: Text-Inhalt; bei Verzeichnissen: JSON-Listing)
python scripts/gitea/gitea_api.py repo file README.md
python scripts/gitea/gitea_api.py repo file backend/main.py --ref develop
# Clone/Push: normales `git remote` – Token nicht dauerhaft in der Remote-URL; SSH oder Credential Helper.
```
## Sicherheit
- **Niemals** `GITEA_TOKEN` ins Git oder in Issues/Pastebins.
- Token, das in Chat oder Logs gelandet ist, in Gitea **widerrufen** und **neu erzeugen**.
- Cursor-Agenten können das CLI über das Terminal nutzen, wenn `.env` gesetzt und Netzwerk zu `GITEA_BASE_URL` erreichbar ist.
## MCP (Tools direkt im Agent)
Siehe [`MCP_SETUP.md`](./MCP_SETUP.md) und [`../.cursor/mcp.json.example`](../../.cursor/mcp.json.example).
+183
View File
@@ -0,0 +1,183 @@
#!/usr/bin/env python3
"""
Minimal Gitea API client. Reads GITEA_* from environment or .env in repo root.
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
from gitea_lib import (
issues_comment,
issues_create,
issues_get,
issues_list_all,
issues_list_page,
issues_patch,
load_dotenv,
repo_file_content,
repo_root,
require_config,
)
def cmd_issues_list(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
if args.all_pages:
items = issues_list_all(
base, token, owner, repo, state=args.state, limit=args.limit
)
else:
_, items = issues_list_page(
base,
token,
owner,
repo,
state=args.state,
page=args.page,
limit=args.limit,
)
for it in items:
num = it.get("number")
title = it.get("title")
st = it.get("state")
print(f"#{num} [{st}] {title}")
def cmd_issues_get(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
status, payload = issues_get(base, token, owner, repo, args.number)
print(json.dumps(payload, indent=2, ensure_ascii=False))
if status >= 400:
sys.exit(1)
def cmd_issues_create(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
body = args.body or ""
if args.body_file:
body = Path(args.body_file).read_text(encoding="utf-8")
status, payload = issues_create(
base,
token,
owner,
repo,
title=args.title,
body=body,
labels=args.labels or [],
)
print(json.dumps(payload, indent=2, ensure_ascii=False))
if status >= 400:
sys.exit(1)
def cmd_issues_comment(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
status, payload = issues_comment(
base, token, owner, repo, args.number, args.body
)
print(json.dumps(payload, indent=2, ensure_ascii=False))
if status >= 400:
sys.exit(1)
def cmd_issues_close(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
status, payload = issues_patch(
base, token, owner, repo, args.number, {"state": "closed"}
)
print(json.dumps(payload, indent=2, ensure_ascii=False))
if status >= 400:
sys.exit(1)
def cmd_issues_reopen(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
status, payload = issues_patch(
base, token, owner, repo, args.number, {"state": "open"}
)
print(json.dumps(payload, indent=2, ensure_ascii=False))
if status >= 400:
sys.exit(1)
def cmd_repo_contents(args: argparse.Namespace, base: str, token: str, owner: str, repo: str) -> None:
status, payload = repo_file_content(
base, token, owner, repo, args.path, ref=args.ref or ""
)
if status >= 400:
print(json.dumps(payload, indent=2, ensure_ascii=False))
sys.exit(1)
if isinstance(payload, dict) and payload.get("encoding") == "text":
print(payload.get("content", ""))
else:
print(json.dumps(payload, indent=2, ensure_ascii=False))
def main() -> None:
if hasattr(sys.stdout, "reconfigure"):
try:
sys.stdout.reconfigure(encoding="utf-8")
except Exception:
pass
root = repo_root()
load_dotenv(root)
parser = argparse.ArgumentParser(description="Gitea API helper")
sub = parser.add_subparsers(dest="domain", required=True)
p_issues = sub.add_parser("issues", help="Issues")
i_sub = p_issues.add_subparsers(dest="issues_cmd", required=True)
p_il = i_sub.add_parser("list", help="List issues")
p_il.add_argument("--state", default="open", choices=["open", "closed", "all"])
p_il.add_argument("--limit", type=int, default=50)
p_il.add_argument("--page", type=int, default=1)
p_il.add_argument(
"--all-pages",
action="store_true",
help="Alle Seiten abfragen (Vorsicht bei sehr vielen Issues)",
)
p_il.set_defaults(_handler=cmd_issues_list)
p_ig = i_sub.add_parser("get", help="Get one issue")
p_ig.add_argument("number", type=int)
p_ig.set_defaults(_handler=cmd_issues_get)
p_ic = i_sub.add_parser("create", help="Create issue")
p_ic.add_argument("--title", required=True)
p_ic.add_argument("--body", default="")
p_ic.add_argument("--body-file")
p_ic.add_argument("--labels", nargs="*", default=[])
p_ic.set_defaults(_handler=cmd_issues_create)
p_co = i_sub.add_parser("comment", help="Add comment")
p_co.add_argument("number", type=int)
p_co.add_argument("--body", required=True)
p_co.set_defaults(_handler=cmd_issues_comment)
p_cl = i_sub.add_parser("close", help="Close issue")
p_cl.add_argument("number", type=int)
p_cl.set_defaults(_handler=cmd_issues_close)
p_ro = i_sub.add_parser("reopen", help="Reopen issue")
p_ro.add_argument("number", type=int)
p_ro.set_defaults(_handler=cmd_issues_reopen)
p_repo = sub.add_parser("repo", help="Repository (API)")
r_sub = p_repo.add_subparsers(dest="repo_cmd", required=True)
p_rc = r_sub.add_parser("file", help="Get file or directory metadata/content")
p_rc.add_argument("path")
p_rc.add_argument("--ref", default="", help="branch/tag/commit")
p_rc.set_defaults(_handler=cmd_repo_contents)
args = parser.parse_args()
try:
base, token, owner, reponame = require_config()
except RuntimeError as e:
sys.stderr.write(str(e) + "\n")
sys.exit(1)
handler = args._handler
handler(args, base, token, owner, reponame)
if __name__ == "__main__":
main()
+226
View File
@@ -0,0 +1,226 @@
"""
Shared Gitea REST helpers (stdlib). Used by gitea_api.py CLI and mcp_server_gitea.py.
"""
from __future__ import annotations
import json
import os
import urllib.error
import urllib.request
from pathlib import Path
from typing import Any
def load_dotenv(repo_root: Path) -> None:
env_path = repo_root / ".env"
if not env_path.is_file():
return
for line in env_path.read_text(encoding="utf-8", errors="replace").splitlines():
line = line.strip()
if not line or line.startswith("#"):
continue
if "=" not in line:
continue
k, _, v = line.partition("=")
k, v = k.strip(), v.strip().strip('"').strip("'")
if k and k not in os.environ:
os.environ[k] = v
def repo_root() -> Path:
return Path(__file__).resolve().parents[2]
def get_config() -> tuple[str, str, str, str]:
base = os.getenv("GITEA_BASE_URL", "").rstrip("/")
token = os.getenv("GITEA_TOKEN", "")
owner = os.getenv("GITEA_OWNER", "")
reponame = os.getenv("GITEA_REPO", "")
return base, token, owner, reponame
def require_config() -> tuple[str, str, str, str]:
base, token, owner, reponame = get_config()
missing = [n for n, v in (
("GITEA_BASE_URL", base),
("GITEA_TOKEN", token),
("GITEA_OWNER", owner),
("GITEA_REPO", reponame),
) if not v]
if missing:
raise RuntimeError(
"Fehlende Umgebungsvariablen: " + ", ".join(missing)
+ " — setze sie in .env im Repo-Root oder in der MCP-env."
)
return base, token, owner, reponame
def request_json(
method: str,
url: str,
token: str,
data: dict | None = None,
) -> tuple[int, Any]:
body = None if data is None else json.dumps(data).encode("utf-8")
req = urllib.request.Request(url, data=body, method=method)
req.add_header("Authorization", f"token {token}")
req.add_header("Accept", "application/json")
if body is not None:
req.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(req, timeout=120) as resp:
raw = resp.read().decode("utf-8", errors="replace")
status = resp.status
except urllib.error.HTTPError as e:
raw = e.read().decode("utf-8", errors="replace")
try:
return e.code, json.loads(raw) if raw else {}
except json.JSONDecodeError:
return e.code, {"message": raw or str(e)}
if not raw:
return status, {}
try:
return status, json.loads(raw)
except json.JSONDecodeError:
return status, raw
def issues_list_page(
base: str,
token: str,
owner: str,
repo: str,
*,
state: str = "open",
page: int = 1,
limit: int = 50,
) -> tuple[int, list]:
if state == "all":
open_st, open_i = issues_list_page(
base, token, owner, repo, state="open", page=page, limit=limit
)
closed_st, closed_i = issues_list_page(
base, token, owner, repo, state="closed", page=page, limit=limit
)
merged = (open_i or []) + (closed_i or [])
st = max(open_st, closed_st) if open_st >= 400 or closed_st >= 400 else 200
return st, merged[:limit]
q = f"?state={state}&page={page}&limit={limit}"
url = f"{base}/api/v1/repos/{owner}/{repo}/issues{q}"
status, payload = request_json("GET", url, token)
if status >= 400:
return status, []
if not isinstance(payload, list):
return status, []
return status, payload
def issues_list_all(
base: str,
token: str,
owner: str,
repo: str,
*,
state: str = "open",
limit: int = 50,
) -> list[dict]:
if state == "all":
o = issues_list_all(
base, token, owner, repo, state="open", limit=limit
)
c = issues_list_all(
base, token, owner, repo, state="closed", limit=limit
)
return o + c
out: list[dict] = []
page = 1
while True:
_, batch = issues_list_page(
base, token, owner, repo, state=state, page=page, limit=limit
)
if not batch:
break
out.extend(batch)
if len(batch) < limit:
break
page += 1
return out
def issues_get(
base: str, token: str, owner: str, repo: str, number: int
) -> tuple[int, Any]:
url = f"{base}/api/v1/repos/{owner}/{repo}/issues/{number}"
return request_json("GET", url, token)
def issues_create(
base: str,
token: str,
owner: str,
repo: str,
*,
title: str,
body: str = "",
labels: list[str] | None = None,
) -> tuple[int, Any]:
url = f"{base}/api/v1/repos/{owner}/{repo}/issues"
return request_json(
"POST",
url,
token,
{"title": title, "body": body, "labels": labels or []},
)
def issues_comment(
base: str,
token: str,
owner: str,
repo: str,
number: int,
body: str,
) -> tuple[int, Any]:
url = f"{base}/api/v1/repos/{owner}/{repo}/issues/{number}/comments"
return request_json("POST", url, token, {"body": body})
def issues_patch(
base: str,
token: str,
owner: str,
repo: str,
number: int,
fields: dict,
) -> tuple[int, Any]:
"""Gitea: PATCH issue (state, title, body, …)."""
url = f"{base}/api/v1/repos/{owner}/{repo}/issues/{number}"
return request_json("PATCH", url, token, fields)
def repo_file_content(
base: str,
token: str,
owner: str,
repo: str,
path: str,
ref: str = "",
) -> tuple[int, Any]:
from urllib.parse import quote
from base64 import b64decode
p = quote(path, safe="/")
r = f"?ref={ref}" if ref else ""
url = f"{base}/api/v1/repos/{owner}/{repo}/contents/{p}{r}"
st, payload = request_json("GET", url, token)
if st >= 400:
return st, payload
if isinstance(payload, dict) and payload.get("type") == "file" and payload.get(
"content"
):
try:
text = b64decode(payload["content"]).decode("utf-8", errors="replace")
return st, {"path": path, "encoding": "text", "content": text}
except Exception:
return st, payload
return st, payload
+127
View File
@@ -0,0 +1,127 @@
#!/usr/bin/env python3
"""
MCP-Server für Gitea (Issues + Datei-Inhalt via API).
Cursor: in den MCP-Einstellungen dieses Skript starten (siehe MCP_SETUP.md).
Transport: stdio (Standard FastMCP).
Abhängigkeit: pip install "mcp>=1.2.0" (siehe requirements-mcp.txt)
"""
from __future__ import annotations
import json
import sys
from gitea_lib import (
issues_comment,
issues_create,
issues_get,
issues_list_all,
issues_list_page,
issues_patch,
load_dotenv,
repo_file_content,
repo_root,
require_config,
)
from mcp.server.fastmcp import FastMCP # noqa: E402
mcp = FastMCP(
"mitai-gitea",
instructions=(
"Gitea-Tools für das Repo aus GITEA_OWNER/GITEA_REPO. "
"Schließe Issues nur nach klarer Code-Verifikation; sonst Kommentar mit offenen Punkten."
),
)
def _cfg():
load_dotenv(repo_root())
return require_config()
def _json(obj) -> str:
return json.dumps(obj, indent=2, ensure_ascii=False)
@mcp.tool()
def gitea_list_issues(
state: str = "open",
limit_per_page: int = 50,
fetch_all_pages: bool = False,
) -> str:
"""Listet Issues. state: open | closed | all. fetch_all_pages=true holt alle Seiten (kann langsam sein)."""
base, token, owner, repo = _cfg()
if fetch_all_pages:
items = issues_list_all(
base, token, owner, repo, state=state, limit=limit_per_page
)
return _json(
[{"number": i.get("number"), "title": i.get("title"), "state": i.get("state")} for i in items]
)
_, items = issues_list_page(
base, token, owner, repo, state=state, page=1, limit=limit_per_page
)
return _json(
[{"number": i.get("number"), "title": i.get("title"), "state": i.get("state")} for i in items]
)
@mcp.tool()
def gitea_get_issue(issue_number: int) -> str:
"""Holt ein Issue inkl. Body, Labels, State (JSON)."""
base, token, owner, repo = _cfg()
st, payload = issues_get(base, token, owner, repo, issue_number)
return _json({"http_status": st, "issue": payload})
@mcp.tool()
def gitea_create_issue(title: str, body: str = "", labels: str = "") -> str:
"""Legt ein Issue an. labels: kommagetrennte Namen, z.B. \"bug,backend\"."""
base, token, owner, repo = _cfg()
lab = [x.strip() for x in labels.split(",") if x.strip()]
st, payload = issues_create(
base, token, owner, repo, title=title, body=body, labels=lab
)
return _json({"http_status": st, "result": payload})
@mcp.tool()
def gitea_comment_issue(issue_number: int, body: str) -> str:
"""Kommentar an ein Issue anhängen."""
base, token, owner, repo = _cfg()
st, payload = issues_comment(base, token, owner, repo, issue_number, body)
return _json({"http_status": st, "result": payload})
@mcp.tool()
def gitea_close_issue(issue_number: int) -> str:
"""Issue schließen (state=closed)."""
base, token, owner, repo = _cfg()
st, payload = issues_patch(
base, token, owner, repo, issue_number, {"state": "closed"}
)
return _json({"http_status": st, "result": payload})
@mcp.tool()
def gitea_reopen_issue(issue_number: int) -> str:
"""Geschlossenes Issue wieder öffnen."""
base, token, owner, repo = _cfg()
st, payload = issues_patch(
base, token, owner, repo, issue_number, {"state": "open"}
)
return _json({"http_status": st, "result": payload})
@mcp.tool()
def gitea_get_repo_file(path: str, git_ref: str = "") -> str:
"""Liest eine Datei aus dem Repo über die Gitea-API (Standard: Default-Branch)."""
base, token, owner, repo = _cfg()
st, payload = repo_file_content(base, token, owner, repo, path, ref=git_ref)
return _json({"http_status": st, "payload": payload})
if __name__ == "__main__":
mcp.run()
+2
View File
@@ -0,0 +1,2 @@
# Nur für MCP-Server (nicht im Backend-Container nötig)
mcp>=1.2.0