offzen/gitea-search-mcp ↗★ 8

gitea-search-mcp

通用 Gitea / Forgejo / 本地 Git 裸镜像混合检索 MCP Server(git grep + SQLite FTS5 + Jieba)

Package
gitea-search-mcp
Compatibility
Unverified
Version
2.0.1
License
Apache-2.0
Last updated
Nov 22, 2026

Install

This plugin has no verified bundle, or compatibility checks failed. Read the repository notes first. Read the full README ↗

gitea-search-mcp

License CI Windows CI Version Archive Platform Node

面向任意 MCP 宿主的 Gitea / Forgejo / 本地 Git 裸镜像混合检索服务(支持 Claude Desktop、Cursor、Cline、Windsurf、Codex、DSH 等)。基于本地 //.git 裸镜像提供毫秒级定位与按需切片读取,免逐仓 clone、防大文件撑爆上下文。

从 v1.2.x(dsh-gitea-search)升级请看 UPGRADING.md(完整保留旧工具名别名与配置回退)。npm / PyPI 无官方包,请从本仓库源码或 Release 签名制品安装。

核心能力

  • 双层混合检索:git grep 检索全仓全部分支代码、路径与提交;SQLite FTS5 + jieba 检索默认分支中英文文档、会话与配置。
  • 上下文防爆窗护栏:默认返回 Top 5 命中,单行 ≤ 2000B、单次 ≤ 128 KiB 安全截断,read_file 默认 400 行 / 60 KB 分片读取。
  • 任意 Git 源接入:除 Gitea/Forgejo 定时同步外,任意 git clone --mirror 到 //.git 的仓库均可直接建库检索。
  • 静态 Schema 导出:node bin/mcp-server --dump-schema [--compact] 离线导出 Function Calling JSON Schema(不读镜像、不启子进程)。

快速安装

环境要求:Node.js ≥ 20.11、Python ≥ 3.10(含 SQLite FTS5 与 jieba,必备依赖)、Git ≥ 2.25;原生支持 Linux / macOS / Windows。

# Linux / macOS
git clone https://github.com/offzen/gitea-search-mcp.git && cd gitea-search-mcp
npm ci --no-audit --no-fund && python3 -m pip install '.[fts]'
# 可选一键脚本:GITEA_OWNERS=my-org bash scripts/setup.sh       # macOS 用 scripts/setup-macos.sh

# Windows(PowerShell,无需管理员权限与 WSL)
git clone https://github.com/offzen/gitea-search-mcp.git; cd gitea-search-mcp
powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1 -Owners my-org -WhatIf

# Zero-Gitea 本地快速体验(无需远端 Gitea,参数为专用演示输出目录)
bash scripts/quickstart-local.sh /tmp/gitea-search-mcp-demo

quickstart-local.sh 仅在指定输出目录生成合成演示仓,不会扫描或导入已有本地仓库;生成 config.json 时,已有不同配置、软链接或非普通文件会被拒绝且保持不动。安装后闭环核验见 docs/POST-INSTALL.md。

主流 MCP 客户端接入

Claude Desktop / Cursor / Cline / Windsurf / Codex(标准 MCP JSON)

{
  "mcpServers": {
    "gitea-search": {
      "command": "node",
      "args": ["/path/to/gitea-search-mcp/bin/mcp-server"],
      "env": {
        "GITEA_MIRROR_ROOT": "/srv/gitea-mirror",
        "GITEA_OWNERS": "my-org,my-team"
      }
    }
  }
}

DeepSeek Harness (DSH cordis.patch.yml)

- insert:
    - id: mcp-gitea-search
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: gitea-search
        transport: stdio                # 必填:缺失会静默不连接
        command: node
        args: ["/opt/gitea-search-mcp/bin/mcp-server"]
        cwd: /opt/gitea-search-mcp
        env:
          GITEA_MIRROR_ROOT: "/srv/gitea-mirror"
          GITEA_OWNERS: "my-org,my-team"

也可将 mirror_root 与 owners 写入 ~/.config/gitea-search-mcp/config.json 共享使用;宿主侧工具前缀规则见 docs/TOOL-NAMING.md。

MCP 工具一览

tools/list 仅暴露 4 个中性标准名,tools/call 同时透明兼容两族历史别名(保留至 v3.0.0 前):

标准工具名兼容旧名(tools/call)用途
search_codesearch_gitea / search_gitorca跨全仓全部分支检索代码内容、文件路径、提交信息
search_docssearch_gitea_docs / search_gitorca_docs默认分支 SQLite FTS5 + jieba 文档、会话、配置、脚本检索
read_fileread_gitea_file / read_gitorca_file按 owner/repo、路径和可选 ref 按需切片精读
list_repositorieslist_gitea_repos / list_gitorca_repos列出本地已镜像仓库(owner/repo)

文档导航

文档内容
docs/POST-INSTALL.md安装后闭环验收:配置核验、首次同步、MCP 探针与宿主调用确认
docs/USAGE.md四工具与 gts CLI 参数速查及“先定位、再精读”范例
docs/OPERATIONS.mdLinux / macOS / Windows 部署、定时同步、环境变量全表与排障
UPGRADING.mdv1.2.x 老用户平滑升级、索引兼容与回滚指南
docs/BOUNDARIES.md / docs/TOOL-NAMING.md能力边界说明 / 三层工具命名与兼容别名模型
CHANGELOG.md / CONTRIBUTING.md版本变更记录 / 本地测试与贡献指南
docs/dev/RELEASE.md / docs/dev/ENGINEERING-NOTES.md维护者三步发版流 / 跨平台底层架构红线

许可证

SPDX-License-Identifier: Apache-2.0(详见 LICENSE)。