gitea-server-mcp 1.0.0

package/README.md

@@ -0,0 +1,210 @@
+# gitea-server-mcp
+
+Gitea MCP 服务器 — 让 AI 编程助手直接操作 Gitea 仓库、Issues、Pull Requests 等。
+
+## 安装
+
+```bash
+npm install -g gitea-server-mcp
+```
+
+## 前置条件
+
+在 Gitea 上生成一个 Access Token：
+1. 打开 Gitea → 右上角头像 → **设置** → **应用**
+2. 在 **管理 Access Token** 区域，输入 Token 名称（如 `mcp`）
+3. 勾选需要的权限（建议：`read:repository`, `write:repository`, `read:issue`, `write:issue`, `read:user`）
+4. 生成并复制 token
+
+## 配置
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio --scope user gitea \
+  --env GITEA_URL=https://你的gitea域名 \
+  --env GITEA_TOKEN=你的token \
+  -- npx -y gitea-server-mcp
+```
+
+### Cursor / 其他 MCP 客户端
+
+在 `.cursor/mcp.json` 或对应配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "npx",
+      "args": ["-y", "gitea-server-mcp"],
+      "env": {
+        "GITEA_URL": "https://你的gitea域名",
+        "GITEA_TOKEN": "你的token"
+      }
+    }
+  }
+}
+```
+
+### 本地开发
+
+```bash
+git clone <your-repo>
+cd gitea-server-mcp
+npm install
+node index.js
+```
+
+## 可用工具
+
+| 工具 | 说明 |
+|---|---|
+| **仓库** | |
+| `gitea_list_repos` | 搜索/列出可访问的仓库 |
+| `gitea_get_repo` | 获取仓库详情 |
+| `gitea_create_repo` | 创建新仓库 |
+| `gitea_search_repos` | 搜索仓库 |
+| `gitea_list_my_repos` | 列出当前用户的仓库 |
+| **Issue** | |
+| `gitea_list_issues` | 列出仓库 Issues |
+| `gitea_get_issue` | 获取单个 Issue 详情 |
+| `gitea_create_issue` | 创建 Issue |
+| `gitea_update_issue` | 更新 Issue |
+| **Pull Request** | |
+| `gitea_list_pull_requests` | 列出仓库 PRs |
+| `gitea_get_pull_request` | 获取单个 PR 详情 |
+| `gitea_create_pull_request` | 创建 PR |
+| **文件** | |
+| `gitea_get_file` | 获取仓库文件内容 |
+| `gitea_create_file` | 创建或更新仓库文件 |
+| **其他** | |
+| `gitea_list_branches` | 列出分支 |
+| `gitea_list_commits` | 查看提交历史 |
+| `gitea_list_releases` | 列出 Releases |
+| `gitea_get_user` | 获取当前用户信息 |
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `GITEA_URL` | 是 | Gitea 实例地址，如 `https://gitea.example.com` |
+| `GITEA_TOKEN` | 是 | Gitea Access Token |
+
+## 安全性
+
+- Token 仅通过环境变量传入，不会写入日志或配置文件
+- 所有请求通过 Gitea REST API 进行，Token 作为 HTTP Header 传递
+- 代码完全开源，可自行审计
+- 依赖仅 `@modelcontextprotocol/sdk` 一个核心库
+
+## 技术栈
+
+- Node.js 18+
+- @modelcontextprotocol/sdk
+- Gitea REST API v1
+
+## License
+
+ISC
+
+---
+
+# gitea-server-mcp (English)
+
+Gitea MCP Server — let AI coding assistants interact with Gitea repos, issues, pull requests, and more.
+
+## Installation
+
+```bash
+npm install -g gitea-server-mcp
+```
+
+## Prerequisites
+
+Generate an Access Token on your Gitea instance:
+1. Gitea → Avatar → Settings → Applications
+2. Under "Manage Access Tokens", enter a name (e.g. `mcp`)
+3. Select required scopes (recommend: `read:repository`, `write:repository`, `read:issue`, `write:issue`, `read:user`)
+4. Generate and copy the token
+
+## Configuration
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio --scope user gitea \
+  --env GITEA_URL=https://your-gitea-domain \
+  --env GITEA_TOKEN=your-token \
+  -- npx -y gitea-server-mcp
+```
+
+### Cursor / Other MCP Clients
+
+Add to `.cursor/mcp.json` or equivalent:
+
+```json
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "npx",
+      "args": ["-y", "gitea-server-mcp"],
+      "env": {
+        "GITEA_URL": "https://your-gitea-domain",
+        "GITEA_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| **Repos** | |
+| `gitea_list_repos` | Search/list accessible repos |
+| `gitea_get_repo` | Get repo details |
+| `gitea_create_repo` | Create a new repo |
+| `gitea_search_repos` | Search repos |
+| `gitea_list_my_repos` | List current user's repos |
+| **Issues** | |
+| `gitea_list_issues` | List repo issues |
+| `gitea_get_issue` | Get a single issue |
+| `gitea_create_issue` | Create an issue |
+| `gitea_update_issue` | Update an issue |
+| **Pull Requests** | |
+| `gitea_list_pull_requests` | List repo PRs |
+| `gitea_get_pull_request` | Get a single PR |
+| `gitea_create_pull_request` | Create a PR |
+| **Files** | |
+| `gitea_get_file` | Get file content |
+| `gitea_create_file` | Create or update a file |
+| **Others** | |
+| `gitea_list_branches` | List branches |
+| `gitea_list_commits` | View commit history |
+| `gitea_list_releases` | List releases |
+| `gitea_get_user` | Get current user info |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITEA_URL` | Yes | Gitea instance URL, e.g. `https://gitea.example.com` |
+| `GITEA_TOKEN` | Yes | Gitea Access Token |
+
+## Security
+
+- Token is passed via environment variables only, never logged or saved to config files
+- All requests use Gitea REST API with token as HTTP header
+- Fully open source — audit the code yourself
+- Only one core dependency: `@modelcontextprotocol/sdk`
+
+## Tech Stack
+
+- Node.js 18+
+- @modelcontextprotocol/sdk
+- Gitea REST API v1
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,408 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const GITEA_URL = (process.env.GITEA_URL || "").replace(/\/+$/, "");
+const GITEA_TOKEN = process.env.GITEA_TOKEN || "";
+
+if (!GITEA_URL || !GITEA_TOKEN) {
+  console.error("Missing GITEA_URL or GITEA_TOKEN environment variable");
+  process.exit(1);
+}
+
+async function api(method, path, body) {
+  const url = `${GITEA_URL}/api/v1${path}`;
+  const opts = {
+    method,
+    headers: {
+      Authorization: `token ${GITEA_TOKEN}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(url, opts);
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Gitea API error ${res.status}: ${text}`);
+  }
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+// ---- Tools ----
+
+const TOOLS = [
+  {
+    name: "gitea_list_repos",
+    description: "列出当前用户可访问的仓库",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "搜索关键词" },
+        limit: { type: "number", description: "返回数量，默认20" },
+        page: { type: "number", description: "页码，默认1" },
+      },
+    },
+  },
+  {
+    name: "gitea_get_repo",
+    description: "获取仓库详情",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+  {
+    name: "gitea_create_repo",
+    description: "创建新仓库",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "仓库名称" },
+        description: { type: "string", description: "仓库描述" },
+        private: { type: "boolean", description: "是否私有，默认false" },
+        auto_init: { type: "boolean", description: "是否初始化README，默认false" },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "gitea_list_issues",
+    description: "列出仓库的 Issues",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        state: { type: "string", enum: ["open", "closed", "all"], description: "状态过滤，默认open" },
+        limit: { type: "number", description: "返回数量，默认20" },
+        page: { type: "number", description: "页码，默认1" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+  {
+    name: "gitea_get_issue",
+    description: "获取单个 Issue 详情",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        index: { type: "number", description: "Issue 编号" },
+      },
+      required: ["owner", "repo", "index"],
+    },
+  },
+  {
+    name: "gitea_create_issue",
+    description: "创建 Issue",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        title: { type: "string", description: "Issue 标题" },
+        body: { type: "string", description: "Issue 内容" },
+        labels: { type: "array", items: { type: "string" }, description: "标签列表" },
+        assignees: { type: "array", items: { type: "string" }, description: "指派用户列表" },
+      },
+      required: ["owner", "repo", "title"],
+    },
+  },
+  {
+    name: "gitea_update_issue",
+    description: "更新 Issue",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        index: { type: "number", description: "Issue 编号" },
+        title: { type: "string", description: "新标题" },
+        body: { type: "string", description: "新内容" },
+        state: { type: "string", enum: ["open", "closed"], description: "状态" },
+      },
+      required: ["owner", "repo", "index"],
+    },
+  },
+  {
+    name: "gitea_list_pull_requests",
+    description: "列出仓库的 Pull Requests",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        state: { type: "string", enum: ["open", "closed", "all"], description: "状态过滤，默认open" },
+        limit: { type: "number", description: "返回数量，默认20" },
+        page: { type: "number", description: "页码，默认1" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+  {
+    name: "gitea_get_pull_request",
+    description: "获取单个 PR 详情",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        index: { type: "number", description: "PR 编号" },
+      },
+      required: ["owner", "repo", "index"],
+    },
+  },
+  {
+    name: "gitea_create_pull_request",
+    description: "创建 Pull Request",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        title: { type: "string", description: "PR 标题" },
+        body: { type: "string", description: "PR 内容" },
+        head: { type: "string", description: "源分支" },
+        base: { type: "string", description: "目标分支" },
+      },
+      required: ["owner", "repo", "title", "head", "base"],
+    },
+  },
+  {
+    name: "gitea_list_branches",
+    description: "列出仓库的分支",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+  {
+    name: "gitea_list_commits",
+    description: "查看仓库提交历史",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        sha: { type: "string", description: "分支名或commit sha，默认默认分支" },
+        limit: { type: "number", description: "返回数量，默认20" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+  {
+    name: "gitea_get_file",
+    description: "获取仓库文件内容",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        path: { type: "string", description: "文件路径" },
+        ref: { type: "string", description: "分支名，默认默认分支" },
+      },
+      required: ["owner", "repo", "path"],
+    },
+  },
+  {
+    name: "gitea_create_file",
+    description: "创建或更新仓库文件",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        path: { type: "string", description: "文件路径" },
+        content: { type: "string", description: "Base64编码的文件内容" },
+        message: { type: "string", description: "提交信息" },
+        branch: { type: "string", description: "分支名" },
+        sha: { type: "string", description: "更新时必填：旧文件的sha，用于冲突检测" },
+      },
+      required: ["owner", "repo", "path", "content", "message", "branch"],
+    },
+  },
+  {
+    name: "gitea_search_repos",
+    description: "搜索仓库",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "搜索关键词" },
+        limit: { type: "number", description: "返回数量，默认20" },
+      },
+      required: ["q"],
+    },
+  },
+  {
+    name: "gitea_get_user",
+    description: "获取当前用户信息",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "gitea_list_my_repos",
+    description: "列出当前登录用户拥有的仓库",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "返回数量，默认20" },
+      },
+    },
+  },
+  {
+    name: "gitea_list_releases",
+    description: "列出仓库的 Releases",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", description: "仓库所有者" },
+        repo: { type: "string", description: "仓库名称" },
+        limit: { type: "number", description: "返回数量，默认20" },
+      },
+      required: ["owner", "repo"],
+    },
+  },
+];
+
+// ---- Handler map ----
+
+const handlers = {
+  gitea_list_repos: (args) => {
+    const params = new URLSearchParams();
+    if (args.q) params.set("q", args.q);
+    if (args.limit) params.set("limit", args.limit);
+    if (args.page) params.set("page", args.page);
+    return api("GET", `/repos/search?${params}`);
+  },
+  gitea_get_repo: (args) => api("GET", `/repos/${args.owner}/${args.repo}`),
+  gitea_create_repo: (args) =>
+    api("POST", `/user/repos`, {
+      name: args.name,
+      description: args.description,
+      private: args.private || false,
+      auto_init: args.auto_init || false,
+    }),
+  gitea_list_issues: (args) => {
+    const params = new URLSearchParams();
+    if (args.state) params.set("state", args.state);
+    if (args.limit) params.set("limit", args.limit);
+    if (args.page) params.set("page", args.page);
+    return api("GET", `/repos/${args.owner}/${args.repo}/issues?${params}`);
+  },
+  gitea_get_issue: (args) =>
+    api("GET", `/repos/${args.owner}/${args.repo}/issues/${args.index}`),
+  gitea_create_issue: (args) =>
+    api("POST", `/repos/${args.owner}/${args.repo}/issues`, {
+      title: args.title,
+      body: args.body,
+      labels: args.labels,
+      assignees: args.assignees,
+    }),
+  gitea_update_issue: (args) => {
+    const body = {};
+    if (args.title !== undefined) body.title = args.title;
+    if (args.body !== undefined) body.body = args.body;
+    if (args.state !== undefined) body.state = args.state;
+    return api("PATCH", `/repos/${args.owner}/${args.repo}/issues/${args.index}`, body);
+  },
+  gitea_list_pull_requests: (args) => {
+    const params = new URLSearchParams();
+    if (args.state) params.set("state", args.state);
+    if (args.limit) params.set("limit", args.limit);
+    if (args.page) params.set("page", args.page);
+    return api("GET", `/repos/${args.owner}/${args.repo}/pulls?${params}`);
+  },
+  gitea_get_pull_request: (args) =>
+    api("GET", `/repos/${args.owner}/${args.repo}/pulls/${args.index}`),
+  gitea_create_pull_request: (args) =>
+    api("POST", `/repos/${args.owner}/${args.repo}/pulls`, {
+      title: args.title,
+      body: args.body,
+      head: args.head,
+      base: args.base,
+    }),
+  gitea_list_branches: (args) =>
+    api("GET", `/repos/${args.owner}/${args.repo}/branches`),
+  gitea_list_commits: (args) => {
+    const params = new URLSearchParams();
+    if (args.sha) params.set("sha", args.sha);
+    if (args.limit) params.set("limit", args.limit);
+    return api("GET", `/repos/${args.owner}/${args.repo}/commits?${params}`);
+  },
+  gitea_get_file: (args) => {
+    const ref = args.ref ? `?ref=${args.ref}` : "";
+    return api("GET", `/repos/${args.owner}/${args.repo}/contents/${args.path}${ref}`);
+  },
+  gitea_create_file: (args) => {
+    const body = {
+      content: args.content,
+      message: args.message,
+      branch: args.branch,
+    };
+    if (args.sha) body.sha = args.sha;
+    return api("POST", `/repos/${args.owner}/${args.repo}/contents/${args.path}`, body);
+  },
+  gitea_search_repos: (args) => {
+    const params = new URLSearchParams();
+    params.set("q", args.q);
+    if (args.limit) params.set("limit", args.limit);
+    return api("GET", `/repos/search?${params}`);
+  },
+  gitea_get_user: () => api("GET", "/user"),
+  gitea_list_my_repos: (args) => {
+    const params = new URLSearchParams();
+    if (args.limit) params.set("limit", args.limit);
+    return api("GET", `/user/repos?${params}`);
+  },
+  gitea_list_releases: (args) => {
+    const params = new URLSearchParams();
+    if (args.limit) params.set("limit", args.limit);
+    return api("GET", `/repos/${args.owner}/${args.repo}/releases?${params}`);
+  },
+};
+
+// ---- Server ----
+
+const server = new Server(
+  { name: "gitea-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const handler = handlers[name];
+  if (!handler) throw new Error(`Unknown tool: ${name}`);
+  const result = await handler(args || {});
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`Gitea MCP Server connected to ${GITEA_URL}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "gitea-server-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": { "gitea-mcp": "index.js" },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": ["gitea", "mcp"],
+  "author": "",
+  "license": "ISC",
+  "description": "Custom MCP server for Gitea operations",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}