@amonstack/gitea-mcp 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amonstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# gitea-mcp
+
+[中文文档](https://github.com/amonstack/gitea_mcp/blob/master/README.zh-CN.md)
+
+> MCP server that lets AI assistants manage Gitea repositories — issues, labels,
+> milestones, comments, and more via the Gitea API.
+
+## What is gitea-mcp?
+
+`gitea-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+server that exposes Gitea repository operations as tools. Once connected to an
+MCP client (Claude Desktop, opencode, Cursor, etc.), an AI assistant can list,
+create, update, and delete issues, labels, milestones, and comments on your
+Gitea instance — all through natural language.
+
+The server communicates over stdio and wraps the [Gitea REST API
+(`/api/v1`)](https://docs.gitea.com/api/1.22/).
+
+## Installation
+
+### From GitHub Packages
+
+```bash
+npm set @amonstack:registry https://npm.pkg.github.com
+npm set //npm.pkg.github.com/:_authToken YOUR_GITHUB_PAT
+npm install -g @amonstack/gitea-mcp
+```
+
+Your GitHub PAT needs the `read:packages` scope.
+
+### Build from source
+
+```bash
+git clone https://github.com/amonstack/gitea-mcp.git
+cd gitea-mcp
+npm ci
+npm run build
+node dist/cli.js
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|:--------:|-------------|
+| `GITEA_BASE_URL` | Yes | Gitea instance URL (e.g. `https://gitea.example.com`) |
+| `GITEA_TOKEN` | Yes | Gitea API access token |
+| `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 |
+
+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.
+
+## MCP Client Setup
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "command": "gitea-mcp",
+      "env": {
+        "GITEA_BASE_URL": "https://gitea.example.com",
+        "GITEA_TOKEN": "your-token-here",
+        "GITEA_DEFAULT_OWNER": "my-org",
+        "GITEA_DEFAULT_REPO": "my-repo"
+      }
+    }
+  }
+}
+```
+
+If you built from source, use `node /path/to/gitea-mcp/dist/cli.js` instead.
+
+### opencode
+
+Add to your opencode MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "command": "gitea-mcp",
+      "env": {
+        "GITEA_BASE_URL": "https://gitea.example.com",
+        "GITEA_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+If you built from source, use `node /path/to/gitea-mcp/dist/cli.js` instead.
+
+### Other MCP Clients
+
+Any client that supports stdio-based MCP servers can use `gitea-mcp`. After
+installation, set the required environment variables and run:
+
+```bash
+export GITEA_BASE_URL="https://gitea.example.com"
+export GITEA_TOKEN="your-access-token"
+gitea-mcp
+```
+
+## Available Tools
+
+### Issues
+
+| Tool | Description |
+|------|-------------|
+| `list_issues` | List issues (filter by `state`, `labels`, page/limit) |
+| `get_issue` | Get a single issue by `index` (issue number) |
+| `create_issue` | Create an issue with `title`, `body`, `assignee`, `labels`, `milestone` |
+| `update_issue` | Update issue fields or `state` |
+| `delete_issue` | Delete an issue by `index` |
+| `search_issues` | Search across repositories by `query`, `type`, `state`, `labels` |
+
+### Comments
+
+| Tool | Description |
+|------|-------------|
+| `list_comments` | List comments on an issue |
+| `create_comment` | Add a comment to an issue |
+| `update_comment` | Update a comment by `id` |
+| `delete_comment` | Delete a comment by `id` |
+
+### Labels
+
+| Tool | Description |
+|------|-------------|
+| `list_labels` | List repository labels |
+| `create_label` | Create a label (`name`, `color`, `description`) |
+| `update_label` | Update a label by `id` |
+| `delete_label` | Delete a label by `id` |
+| `add_issue_labels` | Add labels to an issue by name |
+| `remove_issue_label` | Remove a label from an issue by label `id` |
+| `replace_issue_labels` | Replace all labels on an issue |
+| `clear_issue_labels` | Remove all labels from an issue |
+
+### Milestones
+
+| Tool | Description |
+|------|-------------|
+| `list_milestones` | List milestones (filter by `state`) |
+| `get_milestone` | Get a milestone by `id` |
+| `create_milestone` | Create a milestone with `title`, `description`, `due_on` |
+| `update_milestone` | Update milestone fields or `state` |
+| `delete_milestone` | Delete a milestone by `id` |
+
+### Repository Helpers
+
+| 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 |
+
+## Development
+
+```bash
+git clone https://github.com/amonstack/gitea-mcp.git
+cd gitea-mcp
+npm ci
+```
+
+| Command | Description |
+|---------|-------------|
+| `make lint` | Type-check only |
+| `make build` | Compile `src/` to `dist/` |
+| `make test` | Run unit tests |
+| `make test-watch` | Run tests in watch mode |
+| `make test-integration` | Run integration tests (needs live Gitea instance) |
+| `make dev` | Run directly with tsx |
+
+### Project layout
+
+```
+src/
+  cli.ts           # Entry point
+  server.ts        # MCP server setup and tool registration
+  tools.ts         # Zod input schemas for all tools
+  gitea-client.ts  # REST client wrapping Gitea /api/v1 endpoints
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,189 @@
+# gitea-mcp
+
+[English](https://github.com/amonstack/gitea_mcp/blob/master/README.md)
+
+> 让 AI 助手通过 MCP 协议管理 Gitea 仓库 —— 议题、标签、里程碑、评论等功能，
+> 全部通过 Gitea API 实现。
+
+## 这是什么？
+
+`gitea-mcp` 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+服务端，将 Gitea 仓库操作暴露为 MCP 工具。连接到 MCP 客户端（Claude Desktop、
+opencode、Cursor 等）后，AI 助手即可通过自然语言在 Gitea 实例上创建、查询、
+更新和删除议题、标签、里程碑和评论。
+
+服务端通过 stdio 通信，封装了 [Gitea REST API
+(`/api/v1`)](https://docs.gitea.com/api/1.22/)。
+
+## 安装
+
+### 从 GitHub Packages 安装
+
+```bash
+npm set @amonstack:registry https://npm.pkg.github.com
+npm set //npm.pkg.github.com/:_authToken <你的 GitHub PAT>
+npm install -g @amonstack/gitea-mcp
+```
+
+GitHub PAT 需要 `read:packages` 权限。
+
+### 从源码构建
+
+```bash
+git clone https://github.com/amonstack/gitea-mcp.git
+cd gitea-mcp
+npm ci
+npm run build
+node dist/cli.js
+```
+
+## 配置
+
+| 变量 | 必填 | 说明 |
+|------|:----:|------|
+| `GITEA_BASE_URL` | 是 | Gitea 实例地址（如 `https://gitea.example.com`） |
+| `GITEA_TOKEN` | 是 | Gitea API 访问令牌 |
+| `GITEA_DEFAULT_OWNER` | 否 | 默认仓库所有者，免去每次传入 `owner` 参数 |
+| `GITEA_DEFAULT_REPO` | 否 | 默认仓库名称，免去每次传入 `repo` 参数 |
+
+设置 `GITEA_DEFAULT_OWNER` 和 `GITEA_DEFAULT_REPO` 后，调用工具时可以省略
+`owner` 和 `repo` 参数。也可以使用 `resolve_repo` 工具自动从本地 git 仓库
+检测这两个值。
+
+## MCP 客户端配置
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "command": "gitea-mcp",
+      "env": {
+        "GITEA_BASE_URL": "https://gitea.example.com",
+        "GITEA_TOKEN": "your-token-here",
+        "GITEA_DEFAULT_OWNER": "my-org",
+        "GITEA_DEFAULT_REPO": "my-repo"
+      }
+    }
+  }
+}
+```
+
+如果从源码构建，将 `command` 改为 `node /path/to/gitea-mcp/dist/cli.js`。
+
+### opencode
+
+在 opencode 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "command": "gitea-mcp",
+      "env": {
+        "GITEA_BASE_URL": "https://gitea.example.com",
+        "GITEA_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+如果从源码构建，将 `command` 改为 `node /path/to/gitea-mcp/dist/cli.js`。
+
+### 其他 MCP 客户端
+
+任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后设置环境
+变量并启动：
+
+```bash
+export GITEA_BASE_URL="https://gitea.example.com"
+export GITEA_TOKEN="your-access-token"
+gitea-mcp
+```
+
+## 可用工具
+
+### 议题 (Issues)
+
+| 工具 | 说明 |
+|------|------|
+| `list_issues` | 列出议题（可按 `state`、`labels` 筛选及分页） |
+| `get_issue` | 按 `index`（议题编号）获取单个议题 |
+| `create_issue` | 创建议题，支持 `title`、`body`、`assignee`、`labels`、`milestone` |
+| `update_issue` | 更新议题字段或 `state` |
+| `delete_issue` | 按 `index` 删除议题 |
+| `search_issues` | 跨仓库搜索议题，支持 `query`、`type`、`state`、`labels` |
+
+### 评论 (Comments)
+
+| 工具 | 说明 |
+|------|------|
+| `list_comments` | 列出某个议题的评论 |
+| `create_comment` | 为议题添加评论 |
+| `update_comment` | 按 `id` 更新评论 |
+| `delete_comment` | 按 `id` 删除评论 |
+
+### 标签 (Labels)
+
+| 工具 | 说明 |
+|------|------|
+| `list_labels` | 列出仓库标签 |
+| `create_label` | 创建标签（`name`、`color`、`description`） |
+| `update_label` | 按 `id` 更新标签 |
+| `delete_label` | 按 `id` 删除标签 |
+| `add_issue_labels` | 按名称给议题添加标签 |
+| `remove_issue_label` | 按标签 `id` 从议题移除标签 |
+| `replace_issue_labels` | 替换议题上的所有标签 |
+| `clear_issue_labels` | 清除议题上的所有标签 |
+
+### 里程碑 (Milestones)
+
+| 工具 | 说明 |
+|------|------|
+| `list_milestones` | 列出里程碑（可按 `state` 筛选） |
+| `get_milestone` | 按 `id` 获取里程碑 |
+| `create_milestone` | 创建里程碑，支持 `title`、`description`、`due_on` |
+| `update_milestone` | 更新里程碑字段或 `state` |
+| `delete_milestone` | 按 `id` 删除里程碑 |
+
+### 仓库辅助 (Repository Helpers)
+
+| 工具 | 说明 |
+|------|------|
+| `list_my_repos` | 列出当前用户可访问的仓库 |
+| `resolve_repo` | 从本地 git 仓库的远程地址自动检测 `owner` 和 `repo` |
+
+## 二次开发
+
+```bash
+git clone https://github.com/amonstack/gitea-mcp.git
+cd gitea-mcp
+npm ci
+```
+
+| 命令 | 说明 |
+|------|------|
+| `make lint` | 仅类型检查 |
+| `make build` | 将 `src/` 编译到 `dist/` |
+| `make test` | 运行单元测试 |
+| `make test-watch` | 监听模式运行测试 |
+| `make test-integration` | 运行集成测试（需要可用的 Gitea 实例） |
+| `make dev` | 通过 tsx 直接运行 |
+
+### 项目结构
+
+```
+src/
+  cli.ts           # 入口文件
+  server.ts        # MCP 服务端搭建与工具注册
+  tools.ts         # 所有工具的 Zod 输入模式定义
+  gitea-client.ts  # 封装 Gitea /api/v1 端点的 REST 客户端
+```
+
+## 许可证
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runServer } from "./server.js";
+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");
+    process.exit(1);
+}
+runServer(baseUrl, token, defaultOwner, defaultRepo).catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;AACtC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AACrD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;AAEnD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjE,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/gitea-client.d.ts

@@ -0,0 +1,170 @@
+export interface GiteaConfig {
+    baseUrl: string;
+    token: string;
+}
+export interface Issue {
+    id: number;
+    number: number;
+    title: string;
+    state: string;
+    body?: string;
+    html_url: string;
+    url: string;
+    comments: number;
+    created_at: string;
+    updated_at: string;
+    closed_at?: string;
+    labels: Label[];
+    assignee?: User;
+    assignees?: User[];
+    milestone?: Milestone;
+    repository: Repository;
+}
+export interface Label {
+    id: number;
+    name: string;
+    color: string;
+    description?: string;
+}
+export interface User {
+    id: number;
+    login: string;
+    full_name?: string;
+    avatar_url: string;
+    email?: string;
+}
+export interface Milestone {
+    id: number;
+    title: string;
+    description?: string;
+    state: string;
+    open_issues: number;
+    closed_issues: number;
+    due_on?: string;
+}
+export interface Repository {
+    id: number;
+    full_name: string;
+    name: string;
+    owner: {
+        login: string;
+    };
+}
+export interface Comment {
+    id: number;
+    body: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    user: User;
+}
+export interface Repo {
+    id: number;
+    full_name: string;
+    name: string;
+    owner: User;
+    description?: string;
+    html_url: string;
+    default_branch?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateIssueParams {
+    owner: string;
+    repo: string;
+    title: string;
+    body?: string;
+    assignee?: string;
+    assignees?: string[];
+    labels?: number[];
+    milestone?: number;
+}
+export interface UpdateIssueParams {
+    owner: string;
+    repo: string;
+    index: number;
+    title?: string;
+    body?: string;
+    assignee?: string;
+    assignees?: string[];
+    labels?: number[];
+    milestone?: number;
+    state?: string;
+}
+export interface ListIssuesParams {
+    owner: string;
+    repo: string;
+    state?: "open" | "closed" | "all";
+    labels?: string;
+    page?: number;
+    limit?: number;
+}
+export interface SearchIssuesParams {
+    query?: string;
+    type?: "issues" | "pulls";
+    state?: "open" | "closed" | "all";
+    labels?: string;
+    page?: number;
+    limit?: number;
+}
+export interface CreateLabelParams {
+    owner: string;
+    repo: string;
+    name: string;
+    color: string;
+    description?: string;
+}
+export interface UpdateLabelParams {
+    owner: string;
+    repo: string;
+    id: number;
+    name?: string;
+    color?: string;
+    description?: string;
+}
+export interface CreateMilestoneParams {
+    owner: string;
+    repo: string;
+    title: string;
+    description?: string;
+    due_on?: string;
+}
+export interface UpdateMilestoneParams {
+    owner: string;
+    repo: string;
+    id: number;
+    title?: string;
+    description?: string;
+    due_on?: string;
+    state?: string;
+}
+export declare class GiteaClient {
+    private baseUrl;
+    private token;
+    constructor(config: GiteaConfig);
+    private request;
+    listIssues(params: ListIssuesParams): Promise<Issue[]>;
+    getIssue(owner: string, repo: string, index: number): Promise<Issue>;
+    createIssue(params: CreateIssueParams): Promise<Issue>;
+    updateIssue(params: UpdateIssueParams): Promise<Issue>;
+    deleteIssue(owner: string, repo: string, index: number): Promise<void>;
+    searchIssues(params: SearchIssuesParams): Promise<Issue[]>;
+    listComments(owner: string, repo: string, index: number): Promise<Comment[]>;
+    createComment(owner: string, repo: string, index: number, body: string): Promise<Comment>;
+    updateComment(owner: string, repo: string, id: number, body: string): Promise<Comment>;
+    deleteComment(owner: string, repo: string, id: number): Promise<void>;
+    listLabels(owner: string, repo: string, page?: number, limit?: number): Promise<Label[]>;
+    createLabel(params: CreateLabelParams): Promise<Label>;
+    updateLabel(params: UpdateLabelParams): Promise<Label>;
+    deleteLabel(owner: string, repo: string, id: number): Promise<void>;
+    addIssueLabels(owner: string, repo: string, index: number, labels: string[]): Promise<Label[]>;
+    removeIssueLabel(owner: string, repo: string, index: number, id: number): Promise<void>;
+    replaceIssueLabels(owner: string, repo: string, index: number, labels: string[]): Promise<Label[]>;
+    clearIssueLabels(owner: string, repo: string, index: number): Promise<void>;
+    listMilestones(owner: string, repo: string, state?: string, page?: number, limit?: number): Promise<Milestone[]>;
+    getMilestone(owner: string, repo: string, id: number): Promise<Milestone>;
+    createMilestone(params: CreateMilestoneParams): Promise<Milestone>;
+    updateMilestone(params: UpdateMilestoneParams): Promise<Milestone>;
+    deleteMilestone(owner: string, repo: string, id: number): Promise<void>;
+    listMyRepos(page?: number, limit?: number): Promise<Repo[]>;
+}