gitcode-mcp

Cache-first GitCode tooling for agents and humans.

gitcode-mcp keeps GitCode issues, pull requests, wiki pages, comments, and links available through a durable local cache. It exposes that cache through a CLI and an MCP server so agents can search, read, plan, and perform explicit live writes even when network access is slow or unreliable.

The project is self-contained and public-safe. Source repositories, trackers, and wikis are external inputs; examples use placeholders and sanitized fixtures. See Sanitization Rules for the full safety contract.

What It Does

• Binds GitCode repositories to local cache identities and aliases.
• Syncs issues, pull requests, comments, wiki pages, labels, and milestones into SQLite.
• Searches cached sources with hybrid lexical/semantic retrieval by default and keeps deterministic full-text mode available.
• Runs optional local RAG semantic/hybrid retrieval over cached chunks with model-scoped embeddings.
• Searches versioned repository documentation directly from exact local Git revisions while persisting metadata and vectors—not document copies.
• Maintains multiple enrolled caches with daemon-owned recent refresh, historical backfill, and content-generation-aware RAG repair.
• Resolves stable local ids and remote aliases for links, snippets, backlinks, and exports.
• Runs an MCP server over cached data for agent workflows.
• Performs live writes only through explicit commands with idempotency keys and audit evidence.
• Turns agent or human dogfood friction into structured, redacted, deduplicated feedback issues through an opt-in sink.
• Supports issue, wiki, comment, and pull request workflows from the same cache-first service layer.
• Inspects repository push mirrors through the official v5 API while stripping destination credentials before cache, CLI, or MCP output.

Quick Start

go test ./...
go run ./cmd/gitcode-mcp --help
go run ./cmd/gitcode-mcp repo add --repo YOUR_OWNER/YOUR_REPO --owner YOUR_OWNER --name YOUR_REPO --scopes issues,wiki
go run ./cmd/gitcode-mcp sync --repo YOUR_OWNER/YOUR_REPO --issues --wiki --pulls --pr-comments
go run ./cmd/gitcode-mcp search --repo YOUR_OWNER/YOUR_REPO "cache-first"
go run ./cmd/gitcode-mcp maintenance plan --repo YOUR_OWNER/YOUR_REPO
go run ./cmd/gitcode-mcp maintenance enable --repo YOUR_OWNER/YOUR_REPO --yes --idempotency-key setup-1

search and search_sources request hybrid retrieval by default: full text always runs, and a ready local RAG namespace contributes semantic candidates. Results are grouped by source and carry citations plus lexical/semantic rank provenance. If RAG is unavailable, the response returns full-text results with an explicit fallback reason. Use --mode full_text for deterministic exact/token retrieval without calling the embedding provider.

For MCP usage, start with MCP Setup. For live credentials, start with Secrets and Config Reference. For semantic retrieval, start with RAG Setup and Operation. For README/docs/ retrieval across Git revisions, start with Repository documentation RAG.

Common Workflows

• Read from cache: Read Walkthrough
• Perform explicit writes: Write Walkthrough
• Work with PR/MR flow: PR/MR Workflow
• Install or publish releases: Install, Release Process
• Review component boundaries: Component Architecture
• Place tests and fixtures: Test Architecture
• Configure repositories: Repository Binding
• Understand sync behavior: Cache and Sync Model
• Operate daemon maintenance: Daemon Cache and RAG Maintenance
• Open the embedded local operator console: Admin UI
• Set up semantic retrieval: RAG Setup and Operation
• Search versioned repository docs: Repository documentation RAG
• Review live API findings: GitCode API Discovery
• List, trigger, and monitor repository mirrors safely: Push Mirror Operations
• Prepare and submit public-safe dogfood reports: Structured Feedback

Repository Layout

• cmd/gitcode-mcp/: CLI entrypoint.
• internal/: cache, service, provider, CLI, MCP, sync, diagnostics, and tests.
• docs/: durable product, architecture, operations, and API documentation.
• testdata/: sanitized reusable fixture inputs.

Active planning belongs in GitCode issues and pull requests. Historical research or dogfood evidence that is still useful belongs in the GitCode wiki, not in main.