@amonstack/gitea-mcp 0.2.1 → 0.3.0

package/README.md

@@ -52,13 +52,50 @@ node dist/cli.js
 
 ## Configuration
 
+All variables are optional — `gitea-mcp` auto-discovers the Gitea instance, repository,
+and token from the project's local git config so a single global install can serve many
+projects. Set them only to override the discovery.
+
 | Variable | Required | Description |
 |----------|:--------:|-------------|
-| `GITEA_BASE_URL` | Yes | Gitea instance URL (e.g. `https://gitea.example.com`) |
-| `GITEA_TOKEN` | Yes | Gitea API access token |
+| `GITEA_BASE_URL` | No | Gitea instance URL (e.g. `https://gitea.example.com`). Auto-detected from the project's git remote when omitted. |
+| `GITEA_TOKEN` | No | Gitea API access token. Resolved from `.git/config`, the git credential store, then this variable (see [Token discovery](#token-discovery)). |
 | `GITEA_DEFAULT_OWNER` | No | Default repository owner — skip passing `owner` on every call |
 | `GITEA_DEFAULT_REPO` | No | Default repository name — skip passing `repo` on every call |
 
+### How auto-discovery works
+
+On start, `gitea-mcp` reads `<cwd>/.git/config` and derives:
+
+- **Instance URL** — from the selected remote's host. SSH remotes (`git@host:owner/repo`)
+  resolve to `https://host`. Override with `GITEA_BASE_URL`.
+- **owner / repo** — from the selected remote's URL. Override with `GITEA_DEFAULT_OWNER` /
+  `GITEA_DEFAULT_REPO`, or detect ad hoc with the `resolve_repo` tool.
+- **Remote selection** — the `upstream` remote is preferred, falling back to `origin`, then
+  any other remote. Both are reported by `resolve_repo` when they differ.
+
+If the current directory has no git remote and `GITEA_BASE_URL` is not set, the server does
+**not** start — it prints a skip reason and exits 0. Run it from inside a cloned Gitea
+repository, or set `GITEA_BASE_URL` / `GITEA_TOKEN` explicitly.
+
+### Token discovery
+
+The token is resolved in this order (first match wins):
+
+1. A `[gitea "<baseUrl>"]` section in `.git/config`:
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   A bare `[gitea]` section with `token = ...` is a host-wide fallback.
+2. The git credential store (`~/.git-credentials`, or `$XDG_CONFIG_HOME/git/credentials`) —
+   a line whose host matches the instance, e.g. `https://oauth2:<token>@gitea.example.com`.
+3. The `GITEA_TOKEN` environment variable.
+
+If none resolves, the server still starts without a token (anonymous). Public repositories
+may be read; private repos and write operations return `401` — use the `gitea-configure`
+skill to guide setup, or set `GITEA_TOKEN`.
+
 When `GITEA_DEFAULT_OWNER` and `GITEA_DEFAULT_REPO` are set, you can omit the
 `owner` and `repo` parameters in tool calls. The `resolve_repo` tool can also
 auto-detect them from a local git repository.
@@ -107,22 +144,38 @@ Add to your opencode MCP configuration:
 
 If you built from source, use `node /path/to/gitea-mcp/dist/cli.js` instead.
 
-opencode also loads native **skills** — one per action (find, create, update,
-label, summarize, plan milestones, resolve repo) — that teach the assistant the
-safest workflow for that action, including pre-use checks and pitfalls. Install
-them once:
+opencode and other AI tools can load native **skills** — one per action (find,
+create, update, label, comment, summarize, plan milestones, resolve repo) — that
+teach the assistant the safest workflow for that action, including pre-use checks
+and pitfalls. Install them once with the `init` command, targeting your tool
+(`--tool`, default `opencode`):
 
 ```bash
-gitea-mcp skills install            # global (~/.config/opencode/skills/)
-gitea-mcp skills install --project  # this project (./.opencode/skills/)
+gitea-mcp init                      # opencode (global ~/.config/opencode/skills/)
+gitea-mcp init --tool claude        # Claude Code (~/.claude/skills/)
+gitea-mcp init --tool cursor        # Cursor (~/.cursor/skills/)
+gitea-mcp init --project            # this project (./.<tool>/skills/)
+gitea-mcp init --dir /exact/path    # custom location
 ```
 
-Then restart opencode. See [AI Guidance & Skills](#ai-guidance--skills) below.
+Supported `--tool` values: `amazon-q`, `antigravity`, `auggie`, `claude`,
+`cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`,
+`factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`,
+`qwen`, `roocode`, `windsurf`. Paths follow each tool's conventional skills
+directory; use `--dir` for an exact location. Then restart your tool. See
+[AI Guidance & Skills](#ai-guidance--skills) below.
 
 ### Other MCP Clients
 
 Any client that supports stdio-based MCP servers can use `gitea-mcp`. After
-installation, set the required environment variables and run:
+installation, run it from inside a cloned Gitea repository (config is auto-discovered):
+
+```bash
+cd /path/to/your/gitea-repo
+gitea-mcp
+```
+
+Or set the variables explicitly if you prefer:
 
 ```bash
 export GITEA_BASE_URL="https://gitea.example.com"
@@ -180,7 +233,7 @@ gitea-mcp
 | Tool | Description |
 |------|-------------|
 | `list_my_repos` | List repositories accessible to the authenticated user |
-| `resolve_repo` | Auto-detect `owner` and `repo` from a local git remote URL |
+| `resolve_repo` | Detect `baseUrl`, `owner`, and `repo` from the project's git remotes (`upstream` preferred, then `origin`) |
 
 ## AI Guidance & Skills
 
@@ -195,12 +248,12 @@ through three channels:
   `summarize_issue`, `audit_labels`, `milestone_report`) and on-demand reference
   docs (field reference, label guide, tool cookbook) for clients that surface them.
 
-### opencode skills
+### Action skills
 
-For opencode, the server ships a set of **action-scoped skills** — one per
-workflow, so the assistant loads only the guidance it needs (and never, say,
-delete instructions while creating). Install them with the
-`gitea-mcp skills install` command shown in the opencode section above.
+For opencode and other tools, the server ships a set of **action-scoped skills**
+— one per workflow, so the assistant loads only the guidance it needs (and never,
+say, delete instructions while creating). Install them with the
+`gitea-mcp init --tool <name>` command shown above.
 
 | Skill | Invoke when |
 |-------|-------------|
@@ -209,14 +262,18 @@ delete instructions while creating). Install them with the
 | `gitea-update-issue` | editing fields, closing, clearing assignee/milestone |
 | `gitea-label-issue` | adding / replacing / removing / clearing labels on an issue |
 | `gitea-manage-labels` | creating or editing label definitions |
+| `gitea-comment-issue` | posting a comment that advances an issue's discussion |
 | `gitea-summarize-issue` | reading and summarizing an issue's discussion |
 | `gitea-plan-milestones` | creating / editing / closing milestones |
 | `gitea-resolve-repo` | resolving owner/repo or listing repositories |
+| `gitea-configure` | fixing the connection — instance URL, token, or 401/403 errors |
 
 Each skill is a short, AI-facing action flow (purpose, when to use, when not to,
-rules, and what to check first). Destructive single-tool actions (delete issue /
-comment / label / milestone) are intentionally left to the tool descriptions so
-they never contaminate a creative workflow.
+rules, and what to check first). The create, comment, and milestone skills also
+embed **body templates** (bug / feature / performance issue, comment, milestone)
+that standardize the format of what the assistant writes. Destructive
+single-tool actions (delete issue / comment / label / milestone) are intentionally
+left to the tool descriptions so they never contaminate a creative workflow.
 
 ## Development
 

package/README.zh-CN.md

@@ -50,13 +50,47 @@ node dist/cli.js
 
 ## 配置
 
+所有变量都是可选的——`gitea-mcp` 会从项目本地 git 配置自动发现 Gitea 实例、仓库和令牌，
+因此一次全局安装即可服务多个项目。仅在需要覆盖自动发现结果时才设置它们。
+
 | 变量 | 必填 | 说明 |
 |------|:----:|------|
-| `GITEA_BASE_URL` | 是 | Gitea 实例地址（如 `https://gitea.example.com`） |
-| `GITEA_TOKEN` | 是 | Gitea API 访问令牌 |
+| `GITEA_BASE_URL` | 否 | Gitea 实例地址（如 `https://gitea.example.com`）。未设置时从项目 git 远程地址自动推导。 |
+| `GITEA_TOKEN` | 否 | Gitea API 访问令牌。依次从 `.git/config`、git 凭据存储、本变量解析（见[令牌发现](#令牌发现)）。 |
 | `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者，免去每次传入 `owner` 参数 |
 | `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称，免去每次传入 `repo` 参数 |
 
+### 自动发现的工作方式
+
+启动时，`gitea-mcp` 读取 `<cwd>/.git/config` 并推导：
+
+- **实例地址** —— 取自选中远程地址的 host。SSH 远程（`git@host:owner/repo`）会被推导为
+  `https://host`。可用 `GITEA_BASE_URL` 覆盖。
+- **owner / repo** —— 取自选中远程地址。可用 `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO`
+  覆盖，或随时用 `resolve_repo` 工具检测。
+- **远程选择** —— 优先 `upstream`，回退 `origin`，再回退其它远程。两者不同时 `resolve_repo`
+  会同时返回。
+
+若当前目录没有 git 远程、且未设置 `GITEA_BASE_URL`，服务器**不会启动**——它会打印跳过原因并
+以 exit 0 退出。请在克隆的 Gitea 仓库内运行，或显式设置 `GITEA_BASE_URL` / `GITEA_TOKEN`。
+
+### 令牌发现
+
+令牌按以下顺序解析（先匹配者胜出）：
+
+1. `.git/config` 中的 `[gitea "<baseUrl>"]` 段：
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   不带地址的 `[gitea]` 段中的 `token = ...` 作为全局兜底。
+2. git 凭据存储（`~/.git-credentials`，或 `$XDG_CONFIG_HOME/git/credentials`）——host 匹配实例
+   的那一行，如 `https://oauth2:<token>@gitea.example.com`。
+3. `GITEA_TOKEN` 环境变量。
+
+若都未解析到，服务器仍会以匿名方式启动。公开仓库可读；私有仓库和写操作返回 `401`——此时使用
+`gitea-configure` 技能引导配置，或设置 `GITEA_TOKEN`。
+
 设置 `GITEA_DEFAULT_OWNER` 和 `GITEA_DEFAULT_REPO` 后，调用工具时可以省略
 `owner` 和 `repo` 参数。也可以使用 `resolve_repo` 工具自动从本地 git 仓库
 检测这两个值。
@@ -105,21 +139,36 @@ node dist/cli.js
 
 如果从源码构建，将 `command` 改为 `node /path/to/gitea-mcp/dist/cli.js`。
 
-opencode 还会加载原生**技能（skills）**——按动作拆分（查找、创建、更新、打
-标签、总结、规划里程碑、解析仓库等），教会助手针对该动作的最安全工作流，含
-使用前检查与各类陷阱。一次性安装：
+opencode 及其它 AI 工具可加载原生**技能（skills）**——按动作拆分（查找、创建、
+更新、打标签、评论、总结、规划里程碑、解析仓库等），教会助手针对该动作的最安全
+工作流，含使用前检查与各类陷阱。用 `init` 命令一次性安装，并通过 `--tool` 指定
+目标工具（默认 `opencode`）：
 
 ```bash
-gitea-mcp skills install            # 全局（~/.config/opencode/skills/）
-gitea-mcp skills install --project  # 仅当前项目（./.opencode/skills/）
+gitea-mcp init                      # opencode（全局 ~/.config/opencode/skills/）
+gitea-mcp init --tool claude        # Claude Code（~/.claude/skills/）
+gitea-mcp init --tool cursor        # Cursor（~/.cursor/skills/）
+gitea-mcp init --project            # 仅当前项目（./.<tool>/skills/）
+gitea-mcp init --dir /exact/path    # 自定义路径
 ```
 
-然后重启 opencode。详见下方 [AI 引导与技能](#ai-引导与技能)。
+支持的 `--tool` 取值：`amazon-q`、`antigravity`、`auggie`、`claude`、`cline`、
+`codex`、`codebuddy`、`continue`、`costrict`、`crush`、`cursor`、`factory`、
+`gemini`、`github-copilot`、`iflow`、`kilocode`、`opencode`、`qoder`、`qwen`、
+`roocode`、`windsurf`。路径遵循各工具约定的 skills 目录；如需精确位置请用 `--dir`。
+随后重启对应工具。详见下方 [AI 引导与技能](#ai-引导与技能)。
 
 ### 其他 MCP 客户端
 
-任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后设置环境
-变量并启动：
+ 任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后，在克隆的 Gitea 仓库内
+ 吏动即可（配置会自动发现）：
+
+```bash
+cd /path/to/your/gitea-repo
+gitea-mcp
+```
+
+也可显式设置环境变量：
 
 ```bash
 export GITEA_BASE_URL="https://gitea.example.com"
@@ -177,7 +226,7 @@ gitea-mcp
 | 工具 | 说明 |
 |------|------|
 | `list_my_repos` | 列出当前用户可访问的仓库 |
-| `resolve_repo` | 从本地 git 仓库的远程地址自动检测 `owner` 和 `repo` |
+| `resolve_repo` | 从项目 git 远程地址检测 `baseUrl`、`owner`、`repo`（优先 `upstream`，回退 `origin`） |
 
 ## AI 引导与技能
 
@@ -191,11 +240,11 @@ gitea-mcp
   `audit_labels`、`milestone_report`）与按需参考文档（字段参考、标签指南、工具
   食谱），供支持的客户端使用。
 
-### opencode 技能
+### 动作技能
 
-对 opencode，服务端内置了一组**按动作划分的技能**——每个工作流一个，助手只
-加载所需指引（避免例如创建时把删除说明一并带入造成幻觉）。用上面 opencode
-小节展示的 `gitea-mcp skills install` 命令安装。
+对 opencode 及其它工具，服务端内置了一组**按动作划分的技能**——每个工作流一
+个，助手只加载所需指引（避免例如创建时把删除说明一并带入造成幻觉）。用上方展示的
+`gitea-mcp init --tool <name>` 命令安装。
 
 | 技能 | 何时触发 |
 |------|----------|
@@ -204,13 +253,16 @@ gitea-mcp
 | `gitea-update-issue` | 编辑字段、关闭、清空负责人/里程碑 |
 | `gitea-label-issue` | 为 issue 增加 / 替换 / 移除 / 清空标签 |
 | `gitea-manage-labels` | 创建或编辑标签定义 |
+| `gitea-comment-issue` | 在 issue 下发表推动讨论的评论 |
 | `gitea-summarize-issue` | 读取并总结某 issue 的讨论 |
 | `gitea-plan-milestones` | 创建 / 编辑 / 关闭里程碑 |
 | `gitea-resolve-repo` | 解析 owner/repo 或列出仓库 |
+| `gitea-configure` | 修复连接——实例地址、令牌或 401/403 报错 |
 
 每个技能都是面向 AI 的简短动作流程（目的、何时用、何时不用、规则、先检查什么）。
-破坏性的单工具操作（删除 issue / 评论 / 标签 / 里程碑）有意仅保留在工具描述里，
-不会污染创建类工作流。
+创建、评论、里程碑三类技能还内嵌**正文模板**（bug / 新功能 / 性能 issue、评论、
+里程碑），用以规范助手所写内容的格式。破坏性的单工具操作（删除 issue / 评论 /
+标签 / 里程碑）有意仅保留在工具描述里，不会污染创建类工作流。
 
 ## 二次开发
 

package/dist/assets/instructions.md

@@ -4,18 +4,29 @@ You manage Gitea issues, comments, labels, and milestones through this MCP serve
 Every tool returns Gitea's JSON verbatim as text. Follow these rules to use them
 correctly.
 
+## Config is auto-discovered from git (env vars optional)
+
+On start the server reads `<cwd>/.git/config` and derives `baseUrl`, `owner`, `repo`,
+and `token` so one global install can serve many projects. The `GITEA_BASE_URL` /
+`GITEA_TOKEN` / `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars are OPTIONAL
+overrides; when set they take precedence over git discovery. The remote is chosen
+`upstream` first, then `origin`. If the cwd has no git remote and `GITEA_BASE_URL` is
+unset, the server does not start (it prints a skip reason and exits 0). If you hit a
+401/403 or the connection looks unset, use the **gitea-configure** skill.
+
 ## Resolve owner/repo FIRST (most common failure)
 
 Most tools target one repository and need both `owner` and `repo`. They resolve in
 this order:
 
 1. The `owner` / `repo` arguments you pass to the call.
-2. `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars (set at server start).
-3. The `resolve_repo` tool (detects owner/repo from a local git remote).
+2. `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars (or the git-discovered defaults
+   captured at server start).
+3. The `resolve_repo` tool (re-reads `.git/config` and returns `baseUrl`, `owner`, `repo`,
+   the selected `remote`, and every parsed remote under `remotes`).
 
-If neither argument nor env var is set, the call errors. Before a batch of work on a
-repo you have not used this session, call `resolve_repo` (or confirm the env defaults)
-once and reuse the result — do not guess.
+If none resolve, the call errors. Before a batch of work on a repo you have not used this
+session, call `resolve_repo` once and reuse the result — do not guess.
 
 ## Labels: IDs vs names (critical gotcha)
 
@@ -59,5 +70,6 @@ Confirm the target id/index and scope with the user before calling. For labels,
 ## Error format
 
 Failed calls throw `Gitea API error (<status>): <body>`. Read the status: 401/403 →
-token scope/expiry; 404 → wrong owner/repo or no permission; 409 → conflict;
-422 → validation. Do not retry blindly on 4xx.
+token missing, wrong, or lacks scope — run the **gitea-configure** skill to fix the
+connection; 404 → wrong owner/repo or no permission; 409 → conflict; 422 → validation.
+Do not retry blindly on 4xx.

package/dist/assets/skills/gitea-comment-issue/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: gitea-comment-issue
+description: Invoke to POST a new comment on a Gitea issue or pull request. The flow confirms the issue exists first, then posts. Do NOT invoke to edit or delete a comment (author/admin only, partly destructive — no skill), read or summarize the thread (gitea-summarize-issue), or create/edit the issue itself (gitea-create-issue / gitea-update-issue).
+---
+
+# gitea-comment-issue
+
+Post one new comment that advances an issue's discussion. Tools: `get_issue`, `create_comment`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo). Never guess — wrong values post to the wrong place.
+- `index` = the issue `number` (URL #N → N), never the internal `id`.
+
+## Flow
+1. CONFIRM TARGET: `get_issue({ index })` — verify the issue exists and is the one you mean. Do NOT post blind.
+2. POST: `create_comment({ index, body })`.
+
+## create_comment
+- RULES: `body` required, Markdown. The comment APPENDS to the thread — it never edits or replaces prior content. The response carries the comment `id`; retain it only if a follow-up `update_comment` / `delete_comment` is planned.
+- CHECK FIRST: re-read the latest thread (gitea-summarize-issue) so your comment is not redundant or contradicting a newer message.
+- CHECK AFTER: the comment appears with the returned `id`.
+
+## Body template — standardize what you write into `body`
+A useful comment is contextual, evidence-backed, and proposes a next step. Structure `body` with this template; drop sections that add nothing.
+
+```markdown
+**Context:** <the point you are responding to>
+
+**Finding / proposal:** <what you discovered or suggest>
+
+**Evidence:** <log excerpt, link, reproduction, or metric>
+
+**Suggested next step:** <the concrete action you propose>
+```

package/dist/assets/skills/gitea-configure/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gitea-configure
+description: Invoke to CONFIGURE / SET UP / FIX the Gitea connection — instance URL, token, or owner/repo discovery. Use when a tool fails with 401/403 (bad or missing token), when the user asks how to wire up gitea-mcp, or when baseUrl/owner/repo could not be auto-detected. Do NOT invoke for normal issue/label/milestone work once the connection works.
+---
+
+# gitea-configure
+
+Diagnose and fix the Gitea connection. The server auto-discovers its config from the
+project's git remotes; this skill is the fallback when that fails or the token is wrong.
+
+## How gitea-mcp discovers config (no env vars required)
+
+On start, the server reads `<cwd>/.git/config` and resolves in this order:
+
+1. **baseUrl** — `GITEA_BASE_URL` env var, else derived from the selected remote's host.
+   SSH remotes (`git@host:owner/repo`) resolve to `https://host`.
+2. **owner / repo** — `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars, else from the
+   selected remote's URL.
+3. **Remote selection** — `upstream` remote first, falling back to `origin`, then any
+   other remote. Both are surfaced in `resolve_repo` output.
+
+If the working directory has NO git remote and `GITEA_BASE_URL` is unset, the server does
+NOT start (it prints a skip reason and exits 0). That is intentional, not a crash.
+
+## Token discovery chain (tried in order)
+
+1. `.git/config` — a `[gitea "<baseUrl>"]` section, e.g.
+   ```ini
+   [gitea "https://gitea.example.com"]
+       token = <your-token>
+   ```
+   A bare `[gitea]` section with `token = ...` is a host-wide fallback.
+2. The git credential store (`~/.git-credentials`, or `$XDG_CONFIG_HOME/git/credentials`)
+   — a line whose host matches the instance, e.g.
+   `https://oauth2:<token>@gitea.example.com`.
+3. `GITEA_TOKEN` env var.
+4. If none of the above yield a token, the server starts WITHOUT a token (anonymous). Public
+   repos may be read; writes and private repos return 401 — that is the signal to help the
+   user add a token via one of the sources above.
+
+## Fix flow — when a tool returns 401 / 403
+
+1. Confirm the instance: run `resolve_repo` (no args) and read its `baseUrl` and `remote`.
+   If it throws, the cwd has no usable git remote — tell the user to run gitea-mcp from a
+   cloned repo, or set `GITEA_BASE_URL` + `GITEA_TOKEN`.
+2. Ask the user to create a token at `<baseUrl>/user/settings/applications` (Gitea → Settings
+   → Applications → Access Tokens). Capture the scopes they need: `issue`, `comment`,
+   `label`, `milestone` (read+write). NEVER have the user paste a token into chat unless they
+   explicitly choose to — prefer having them run a git command themselves.
+3. Have the user store it so discovery finds it. Recommend, in priority order:
+   - `git config --file=.git/config gitea."<baseUrl>".token "<token>"` (project-scoped), or
+   - add to the credential store, or
+   - export `GITEA_TOKEN` (and `GITEA_BASE_URL`) in their MCP client config.
+   `<baseUrl>` is the EXACT value `resolve_repo` reported (scheme + host, with port if any).
+4. The server must be restarted for new config to take effect — discovery runs once at start.
+
+## Never log the token
+
+Tokens are secret. Do not echo, paste into notes, or include in issue/comment bodies. Pass
+configuration values to the user as commands to run themselves; never print a token back.

package/dist/assets/skills/gitea-create-issue/SKILL.md

@@ -11,7 +11,7 @@ Open one new issue after ruling out a duplicate. Tools: `search_issues`, `create
 - Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo). Never guess — wrong values create the issue in the wrong repo.
 
 ## Flow
-1. DUPLICATE CHECK (always first): `search_issues({ query: "<title keywords>", type: "issues" })`. If a match exists, comment on it (gitea-summarize-issue, then `create_comment`) instead of creating a duplicate. Do NOT skip this — creation does not de-duplicate.
+1. DUPLICATE CHECK (always first): `search_issues({ query: "<title keywords>", type: "issues" })`. If a match exists, comment on it (gitea-comment-issue) instead of creating a duplicate. Do NOT skip this — creation does not de-duplicate.
 2. CREATE: `create_issue({ title, body?, assignees? })`.
 
 ## create_issue
@@ -19,3 +19,46 @@ Open one new issue after ruling out a duplicate. Tools: `search_issues`, `create
 - Do NOT pass `labels` or `milestone` here: `labels` expect IDs (error-prone) and milestone needs an id. Create WITHOUT them, then attach labels by name via `add_issue_labels` (gitea-label-issue) and set the milestone via `update_issue` (gitea-update-issue).
 - CHECK FIRST: confirm no duplicate (step 1) and that `owner`/`repo` are correct before writing.
 - CHECK AFTER: the returned object's `number` is the new issue index.
+
+## Body templates — standardize what you write into `body`
+Always structure `body` with the template matching the issue type. Ask the user which type if it is not obvious. Drop a section only when it is genuinely empty; never invent data. These are GitHub-OSS conventions adapted for the Markdown body that `create_issue` accepts.
+
+### Bug report
+```markdown
+**Summary:** <one-line description of what is wrong>
+
+**Steps to reproduce**
+1. <step>
+2. <step>
+
+**Expected:** <what should happen>
+**Actual:** <what happens instead>
+
+**Environment**
+- gitea-mcp version:
+- Gitea version:
+- Node / runtime:
+- OS:
+```
+
+### Feature request
+```markdown
+**Motivation:** <the problem or need this addresses>
+
+**Proposal:** <what to add or change>
+
+**Alternatives considered:** <other approaches and why they fall short>
+```
+
+### Performance issue
+```markdown
+**Symptom:** <what is slow, or which metric regressed>
+
+**How to reproduce:** <scenario + data size / load>
+
+**Measurements**
+- Before: <baseline metric>
+- After / target: <current or goal metric>
+
+**Suspected bottleneck:** <where the cost seems to come from>
+```

package/dist/assets/skills/gitea-plan-milestones/SKILL.md

@@ -22,3 +22,20 @@ Create / edit / close milestones. Tools: `list_milestones`, `get_milestone`, `cr
 
 ## get_milestone
 - Read one milestone by `id`: includes `open_issues` / `closed_issues` counts for progress (progress = closed / (open + closed)).
+
+## Description template — standardize what you write into `description`
+Milestones succeed when scope is explicit. When creating or editing, structure `description` with this template; keep it short and drop empty sections.
+
+```markdown
+**Goal:** <the single outcome this milestone delivers>
+
+**Scope**
+- In: <what this milestone covers>
+- Out: <what is explicitly deferred>
+
+**Acceptance criteria**
+- <observable, checkable condition>
+- <observable, checkable condition>
+
+**Owners:** <who is accountable>
+```

package/dist/assets/skills/gitea-resolve-repo/SKILL.md

@@ -1,18 +1,29 @@
 ---
 name: gitea-resolve-repo
-description: Invoke to RESOLVE which owner/repo the other gitea tools should target (auto-detect from a git remote) or to LIST repositories the token can access. Run FIRST when the target repository is unknown. Do NOT invoke for issue/comment/label/milestone work once owner/repo are known.
+description: Invoke to RESOLVE which owner/repo (and baseUrl) the other gitea tools should target (auto-detect from a git remote) or to LIST repositories the token can access. Run FIRST when the target repository is unknown. Do NOT invoke for issue/comment/label/milestone work once owner/repo are known.
 ---
 
 # gitea-resolve-repo
 
-Discover the target repository. Tools: `resolve_repo`, `list_my_repos`.
+Discover the target repository and instance. Tools: `resolve_repo`, `list_my_repos`.
 
 ## resolve_repo
-- Reads the `origin` remote of the git repo at `path` (default: current directory) and parses owner/repo from SSH (`git@gitea.example:owner/repo.git`) or HTTPS (`https://gitea.example/owner/repo.git`) URLs.
-- Throws if there is no `origin` remote or the URL is unparseable. Do NOT guess owner/repo from context — call this, or ask the user.
+- Reads `.git/config` of the git repo at `path` (default: current directory) and parses
+  EVERY remote from SSH (`git@gitea.example:owner/repo.git`) or HTTPS
+  (`https://gitea.example/owner/repo.git`) URLs.
+- Selects the remote to target in this priority: `upstream` → `origin` → any other.
+  SSH remotes resolve to `baseUrl = https://<host>` (the API is assumed HTTPS).
+- Returns `{ baseUrl, owner, repo, remote, remote_url, remotes: { <name>: {baseUrl, owner, repo, url} } }`.
+  Read `baseUrl` to know which instance a token must be valid for; read `remotes` to see
+  upstream vs origin when they differ.
+- Throws `No parseable git remotes found` if the cwd has no git remote or none parse. Do
+  NOT guess owner/repo from context — call this, or ask the user.
 
 ## list_my_repos
-- Lists repositories the token can access. GLOBAL. Returns large objects — paginate (`limit` ≤ 100) and read only the fields you need (name, full_name, owner.login).
+- Lists repositories the token can access. GLOBAL. Returns large objects — paginate (`limit` ≤ 100) and read only the fields you need (name, full_name, owner.login). If this returns
+  401/403 there is no usable token — switch to the **gitea-configure** skill.
 
 ## Resolution order (every repo-scoped tool)
-explicit `owner`/`repo` args → `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` → `resolve_repo`. If none resolve, the tool throws `owner and repo are required`. Wrong values 404 or silently target the wrong repo — never guess.
+explicit `owner`/`repo` args → `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` (or git-discovered
+defaults) → `resolve_repo`. If none resolve, the tool throws `owner and repo are required`.
+Wrong values 404 or silently target the wrong repo — never guess.

package/dist/assets/skills/gitea-summarize-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gitea-summarize-issue
-description: Invoke to READ and SUMMARIZE an issue's discussion — the issue body plus its comment thread. Do NOT invoke to create/edit an issue (gitea-create-issue / gitea-update-issue), post or edit a comment (no skill — single tool), or manage labels/milestones.
+description: Invoke to READ and SUMMARIZE an issue's discussion — the issue body plus its comment thread. Do NOT invoke to create/edit an issue (gitea-create-issue / gitea-update-issue), post a comment (gitea-comment-issue), or manage labels/milestones.
 ---
 
 # gitea-summarize-issue

package/dist/cli.js

@@ -1,25 +1,31 @@
 #!/usr/bin/env node
 import { runServer } from "./server.js";
+import { discoverConfig } from "./git-config.js";
 const argv = process.argv.slice(2);
-if (argv[0] === "skills") {
-    // `gitea-mcp skills ...` manages the bundled opencode skill. It needs no Gitea
-    // credentials, so it is dispatched before the env-var guard below.
-    const { runSkillsCommand } = await import("./skills.js");
-    runSkillsCommand(argv.slice(1)).catch((err) => {
+if (argv[0] === "init") {
+    // `gitea-mcp init [--tool <name>]` installs the bundled skills into a target
+    // AI tool's skills directory. It needs no Gitea credentials, so it is
+    // dispatched before the config-discovery logic below.
+    const { runInitCommand } = await import("./skills.js");
+    runInitCommand(argv.slice(1)).catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
     });
 }
 else {
-    const baseUrl = process.env.GITEA_BASE_URL;
-    const token = process.env.GITEA_TOKEN;
-    const defaultOwner = process.env.GITEA_DEFAULT_OWNER;
-    const defaultRepo = process.env.GITEA_DEFAULT_REPO;
-    if (!baseUrl || !token) {
-        console.error("GITEA_BASE_URL and GITEA_TOKEN environment variables are required");
+    // Resolve baseUrl/owner/repo/token from env first, then the local git context
+    // (`.git/config` remotes + credential store). When neither env nor any git
+    // remote provides a baseUrl, the server is intentionally skipped: a single
+    // global install should stay dormant outside of git projects.
+    const discovered = await discoverConfig().catch((err) => {
+        console.error("Fatal error:", err);
         process.exit(1);
+    });
+    if (!discovered) {
+        console.error(`gitea-mcp: no git remote found in ${process.cwd()} and GITEA_BASE_URL is not set; skipping server start.`);
+        process.exit(0);
     }
-    runServer(baseUrl, token, defaultOwner, defaultRepo).catch((err) => {
+    runServer(discovered.baseUrl, discovered.token, discovered.defaultOwner, discovered.defaultRepo).catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
     });

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;IACzB,+EAA+E;IAC/E,mEAAmE;IACnE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACzD,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5C,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAEnD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjE,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACvD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,UAAU,GAAG,MAAM,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC/D,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACX,qCAAqC,OAAO,CAAC,GAAG,EAAE,wDAAwD,CAC3G,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CACP,UAAU,CAAC,OAAO,EAClB,UAAU,CAAC,KAAK,EAChB,UAAU,CAAC,YAAY,EACvB,UAAU,CAAC,WAAW,CACvB,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}