@boringstudio_org/gitea-mcp 1.4.1

package/.gitea/workflows/publish.yaml

@@ -0,0 +1,27 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.gitea/workflows/release.yaml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'chore(release)')"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Checkout branch
+        run: |
+          git checkout main
+          git pull origin main
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Configure Git
+        run: |
+          git config user.name "Gitea Actions"
+          git config user.email "sgmakgg@gmail.com"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run standard-version
+        run: npm run release
+
+      - name: Push changes
+        run: git push --follow-tags origin main
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### 1.4.1 (2026-01-14)
+
+### [1.3.6](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.5...v1.3.6) (2026-01-14)
+
+### [1.3.5](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.4...v1.3.5) (2026-01-14)
+
+
+### Bug Fixes
+
+* Update start script to use global package and load env ([#20](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/20)) ([c4598fc](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/c4598fce2bbfcd9acc48599fe0eddde013ecedb5))
+
+### [1.3.4](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.3...v1.3.4) (2026-01-14)
+
+
+### Features
+
+* Native Node.js Google Search implementation ([#19](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/19)) ([555f44a](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/555f44a9bd9017d2cd01351efe19b5b2c766b442))
+
+### [1.3.3](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.2...v1.3.3) (2026-01-14)
+
+
+### Bug Fixes
+
+* Silence npx output, map Google ID, add start script and update docs ([#18](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/18)) ([7c36bdc](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/7c36bdcedd5c29281a1562a7a801c3d0ac6d3256))
+
+### [1.3.2](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.1...v1.3.2) (2026-01-14)
+
+
+### Bug Fixes
+
+* Add ~/.local/bin to PATH for uvx discovery ([#16](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/16)) ([b2a25d5](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/b2a25d5fa5ec6d5d9fface87d48eb431ff9fd175))
+
+### [1.3.1](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.3.0...v1.3.1) (2026-01-14)
+
+
+### Bug Fixes
+
+* Remove hardcoded env from npm config and update docs ([9842c48](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/9842c48e07e91a0d5b79d547782aa0aa9b6d9390))
+
+## [1.3.0](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/compare/v1.2.0...v1.3.0) (2026-01-13)
+
+## 1.2.0 (2026-01-13)
+
+
+### Features
+
+* add create_pull_request and list_branches tools (Closes [#3](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/3)) ([465d4ed](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/465d4ed1738cf7e54d2b67b7a8c5f2df70194cfe))
+* add list_labels and update_issue with labels support (Closes [#2](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/issues/2)) ([9006385](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/9006385ce82cd5adc5f7af9bdbf5e28c89789816))
+* add memory schema docs and update project structure ([841b0d6](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/841b0d6075c9e9b501a7d76a7cfa10a1f228a2bb))
+* add secure shell execution and full Gitea integration ([d22d48c](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/d22d48cb99de046b560313995b08d1c67955fb41))
+* upgrade to v1.4.0 with Resources and Prompts ([1510e9e](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/1510e9e7e1b3d682c011a7fdc56ae2b26435c086))
+
+
+### Bug Fixes
+
+* Add fallback for uvx path ([dba4e21](https://git.boringstudio.by/BoringStudio/mcp-gitea-proxy/commit/dba4e213790c91a8d031c37cac9a0eaf8724664a))

package/README.md

@@ -0,0 +1,55 @@
+# Gitea MCP Server
+
+A Model Context Protocol (MCP) server for interacting with Gitea.
+This package is designed to be used as a standalone server or imported by a gateway.
+
+## 🛠 Capabilities
+
+*   **Issues:** List, search, create, update, comment.
+*   **Repositories:** List repos, branches, labels.
+*   **Files:** Read file content.
+*   **Pull Requests:** Create PRs.
+*   **Analysis:** Analyze issues with AI prompts.
+*   **Shell:** Execute safe git commands in WSL (`run_safe_shell`).
+
+## 📦 Installation
+
+```bash
+npm install @boringstudio_org/gitea-mcp
+```
+
+## 🚀 Usage
+
+### Via NPX (Recommended)
+```bash
+# Configure environment variables
+export GITEA_TOKEN=your_token
+# Optional: Defaults to https://git.boringstudio.by/api/v1
+export GITEA_API_URL=https://git.your-instance.com/api/v1
+
+# Run
+npx @boringstudio_org/gitea-mcp
+```
+
+### Standalone (From Source)
+```bash
+# Install dependencies
+npm install
+
+# Configure .env
+echo "Gitea_TOKEN=..." > .env
+
+# Run
+node index.js
+```
+
+### As a Library
+```javascript
+import { runGiteaServer } from "@boringstudio_org/gitea-mcp";
+// Ensure environment variables are set
+runGiteaServer().catch(console.error);
+```
+
+## 📝 License
+
+MIT

package/index.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import axios from "axios";
+import { z } from "zod";
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from 'url';
+import { spawn } from "child_process";
+
+// Load .env from the current working directory
+dotenv.config({ path: path.join(process.cwd(), ".env"), quiet: true });
+
+export async function runGiteaServer() {
+    const server = new McpServer({
+        name: "gitea-proxy-agent",
+        version: "1.6.0",
+    });
+
+    const GITEA_TOKEN = process.env.GITEA_TOKEN;
+    const BASE_URL = process.env.GITEA_API_URL || "https://git.boringstudio.by/api/v1";
+
+    if (!GITEA_TOKEN) {
+        console.error("❌ Error: GITEA_TOKEN not found.");
+        console.error("Please provide a Gitea Token in a .env file (GITEA_TOKEN=your_token).");
+        process.exit(1);
+    }
+
+    const headers = {
+        "Authorization": `token ${GITEA_TOKEN}`,
+        "Content-Type": "application/json"
+    };
+
+    // For Cloudflare Access, set CF_ID and CF_SECRET in your .env file
+    if (process.env.CF_ID && process.env.CF_SECRET) {
+        headers["CF-Access-Client-Id"] = process.env.CF_ID;
+        headers["CF-Access-Client-Secret"] = process.env.CF_SECRET;
+        console.error("INFO: Running in Cloudflare Proxy mode");
+    }
+
+    const api = axios.create({
+        baseURL: BASE_URL,
+        headers: headers
+    });
+
+    async function giteaApi(method, endpoint, data = null, params = null) {
+        try {
+            const config = { method, url: endpoint };
+            if (data) config.data = data;
+            if (params) config.params = params;
+            
+            const response = await api(config);
+            return response.data;
+        } catch (error) {
+            const msg = error.response?.data?.message || error.message;
+            throw new Error(`Gitea API Error: ${msg}`);
+        }
+    }
+
+    // --- RESOURCES ---
+    server.resource(
+        "issues-list",
+        new ResourceTemplate("gitea://{owner}/{repo}/issues", { list: undefined }),
+        async (uri, { owner, repo }) => {
+            const issues = await giteaApi("GET", `/repos/${owner}/${repo}/issues`, null, { limit: 50 });
+            return {
+                contents: [{
+                    uri: uri.href,
+                    text: JSON.stringify(issues, null, 2),
+                    mimeType: "application/json"
+                }]
+            };
+        }
+    );
+
+    server.resource(
+        "file-content",
+        new ResourceTemplate("gitea://{owner}/{repo}/files/{branch}/{path}", { list: undefined }),
+        async (uri, { owner, repo, branch, path: filePath }) => {
+            const content = await giteaApi("GET", `/repos/${owner}/${repo}/raw/${branch}/${filePath}`);
+            return {
+                contents: [{
+                    uri: uri.href,
+                    text: typeof content === 'string' ? content : JSON.stringify(content),
+                    mimeType: "text/plain"
+                }]
+            };
+        }
+    );
+
+    // --- PROMPTS ---
+    server.prompt(
+        "analyze-issue",
+        {
+            owner: z.string(),
+            repo: z.string(),
+            issue_number: z.string().describe("Issue number (as string)")
+        },
+        async ({ owner, repo, issue_number }) => {
+            const issue = await giteaApi("GET", `/repos/${owner}/${repo}/issues/${issue_number}`);
+            const comments = await giteaApi("GET", `/repos/${owner}/${repo}/issues/${issue_number}/comments`);
+            return {
+                messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Please analyze the following Gitea issue and suggest a solution or next steps.\n\n` +
+                              `Title: ${issue.title}\n` +
+                              `State: ${issue.state}\n` +
+                              `Description:\n${issue.body}\n\n` +
+                              `Comments:\n${comments.map(c => `- ${c.user.username}: ${c.body}`).join("\n")}`
+                    }
+                }]
+            };
+        }
+    );
+
+    // --- TOOLS ---
+    server.tool(
+        "run_safe_shell",
+        "Execute a safe shell command (git only) in a specific directory",
+        {
+            cwd: z.string().describe("The working directory for the command"),
+            command: z.string().describe("The command to execute (must start with 'git')"),
+            args: z.array(z.string()).describe("The arguments for the command")
+        },
+        async ({ cwd, command, args }) => {
+            if (command !== 'git') {
+                return { content: [{ type: "text", text: "Error: Only 'git' commands are allowed." }], isError: true };
+            }
+
+            return new Promise((resolve) => {
+                const child = spawn(command, args, {
+                    cwd: cwd,
+                    env: process.env,
+                    shell: false
+                });
+
+                let stdout = "";
+                let stderr = "";
+
+                child.stdout.on("data", (data) => {
+                    stdout += data.toString();
+                });
+
+                child.stderr.on("data", (data) => {
+                    stderr += data.toString();
+                });
+
+                child.on("close", (code) => {
+                    if (code === 0) {
+                        resolve({
+                            content: [{ type: "text", text: stdout || "Success (no output)" }]
+                        });
+                    } else {
+                        resolve({
+                            content: [{ type: "text", text: `Exit code: ${code}\nStdout: ${stdout}\nStderr: ${stderr}` }],
+                            isError: true
+                        });
+                    }
+                });
+
+                child.on("error", (err) => {
+                    resolve({
+                        content: [{ type: "text", text: `Failed to start command: ${err.message}` }],
+                        isError: true
+                    });
+                });
+            });
+        }
+    );
+
+    server.tool(
+        "list_repos",
+        "Get a list of all user/organization repositories",
+        { org: z.string().optional().describe("Organization name") },
+        async ({ org }) => {
+            const endpoint = org ? `/orgs/${org}/repos` : "/user/repos";
+            const repos = await giteaApi("GET", endpoint, null, { limit: 50 });
+            const formatted = repos.map(r => `${r.full_name} (ID: ${r.id}) - ${r.private ? 'Private' : 'Public'}`).join("\n");
+            return { content: [{ type: "text", text: formatted || "No repositories found." }] };
+        }
+    );
+
+    server.tool(
+        "list_issues",
+        "Get a list of all open issues in the repository",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          page: z.number().optional(),
+          limit: z.number().optional()
+        },
+        async ({ owner, repo, page = 1, limit = 20 }) => {
+            const issues = await giteaApi("GET", `/repos/${owner}/${repo}/issues`, null, { page, limit });
+            const formatted = issues.map(i => `#${i.number}: ${i.title}`).join("\n");
+            return { content: [{ type: "text", text: formatted || "No issues yet." }] };
+        }
+    );
+
+    server.tool(
+        "search_issues",
+        "Search for issues in a repository using keywords",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          query: z.string(),
+          state: z.enum(["open", "closed", "all"]).optional()
+        },
+        async ({ owner, repo, query, state = "open" }) => {
+            const issues = await giteaApi("GET", `/repos/${owner}/${repo}/issues`, null, { q: query, state, limit: 20 });
+            const formatted = issues.map(i => `#${i.number} (${i.state}): ${i.title}`).join("\n");
+            return { content: [{ type: "text", text: formatted || "No matching issues found." }] };
+        }
+    );
+
+    server.tool(
+        "get_issue_details",
+        "Read the full issue description and its status",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          issue_number: z.number()
+        },
+        async ({ owner, repo, issue_number }) => {
+            const i = await giteaApi("GET", `/repos/${owner}/${repo}/issues/${issue_number}`);
+            const result = `ISSUE #${i.number}: ${i.title}\nStatus: ${i.state}\nDescription:\n${i.body || "No description"}`;
+            return { content: [{ type: "text", text: result }] };
+        }
+    );
+
+    server.tool(
+        "add_comment",
+        "Leave a comment on a Gitea issue",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          issue_number: z.number(),
+          body: z.string()
+        },
+        async ({ owner, repo, issue_number, body }) => {
+            await giteaApi("POST", `/repos/${owner}/${repo}/issues/${issue_number}/comments`, { body });
+            return { content: [{ type: "text", text: "Success: Comment added." }] };
+        }
+    );
+
+    server.tool(
+        "create_issue",
+        "Create a new issue in the repository",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          title: z.string(),
+          body: z.string().optional()
+        },
+        async ({ owner, repo, title, body }) => {
+            const response = await giteaApi("POST", `/repos/${owner}/${repo}/issues`, { title, body });
+            return { content: [{ type: "text", text: `Success: Issue #${response.number} created.` }] };
+        }
+    );
+
+    server.tool(
+        "list_labels",
+        "Get a list of all labels in the repository",
+        {
+          owner: z.string(),
+          repo: z.string()
+        },
+        async ({ owner, repo }) => {
+            const labels = await giteaApi("GET", `/repos/${owner}/${repo}/labels`);
+            const formatted = labels.map(l => `${l.name} (ID: ${l.id})`).join("\n");
+            return { content: [{ type: "text", text: formatted || "No labels found." }] };
+        }
+    );
+
+    server.tool(
+        "list_branches",
+        "List branches in the repository",
+        {
+          owner: z.string(),
+          repo: z.string()
+        },
+        async ({ owner, repo }) => {
+            const branches = await giteaApi("GET", `/repos/${owner}/${repo}/branches`);
+            const formatted = branches.map(b => b.name).join("\n");
+            return { content: [{ type: "text", text: formatted || "No branches found." }] };
+        }
+    );
+
+    server.tool(
+        "create_pull_request",
+        "Create a Pull Request",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          head: z.string(),
+          base: z.string().optional(),
+          title: z.string(),
+body: z.string().optional()
+        },
+        async ({ owner, repo, head, base = "main", title, body }) => {
+            const response = await giteaApi("POST", `/repos/${owner}/${repo}/pulls`, { head, base, title, body });
+            return { content: [{ type: "text", text: `Success: PR #${response.number} created: ${response.html_url}` }] };
+        }
+    );
+
+    server.tool(
+        "update_issue",
+        "Update an issue (change state, title, body, or labels)",
+        {
+          owner: z.string(),
+          repo: z.string(),
+          issue_number: z.number(),
+          state: z.enum(["open", "closed"]).optional(),
+          title: z.string().optional(),
+          body: z.string().optional(),
+          labels: z.array(z.string()).optional()
+        },
+        async ({ owner, repo, issue_number, state, title, body, labels }) => {
+            const payload = {};
+            if (state) payload.state = state;
+            if (title) payload.title = title;
+            if (body) payload.body = body;
+
+            if (labels) {
+                const repoLabels = await giteaApi("GET", `/repos/${owner}/${repo}/labels`);
+                const labelIds = labels.map(name => {
+                    const found = repoLabels.find(l => l.name === name);
+                    if (!found) throw new Error(`Label '${name}' not found in repository.`);
+                    return found.id;
+                });
+                payload.labels = labelIds;
+            }
+
+            if (Object.keys(payload).length === 0) {
+                return { content: [{ type: "text", text: "No changes requested." }] };
+            }
+
+            await giteaApi("PATCH", `/repos/${owner}/${repo}/issues/${issue_number}`, payload);
+            return { content: [{ type: "text", text: `Success: Issue #${issue_number} updated.` }] };
+        }
+    );
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+// Only run if executed directly
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runGiteaServer().catch(error => {
+        console.error("FATAL ERROR:", error.message);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@boringstudio_org/gitea-mcp",
+  "version": "1.4.1",
+  "description": "A Gitea MCP Server for interacting with repositories, issues, and more.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "gitea-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "release": "standard-version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "axios": "^1.7.9",
+    "dotenv": "^17.2.3",
+    "zod": "^3.24.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.boringstudio.by/BoringStudio/mcp-gitea.git"
+  },
+  "keywords": [
+    "mcp",
+    "gitea",
+    "ai",
+    "llm",
+    "server"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "standard-version": "^9.5.0"
+  }
+}