Read Walkthrough

This walkthrough covers the offline, cache-first CLI read flow after repository binding and fixture sync.

Prerequisites

• gitcode-mcp installed (Install)
• Repository configured (Repository Binding)
• Fixtures synced and indexed (see below)

Setup for walkthrough

# Add the example repository
gitcode-mcp repo add \
  --repo example-owner/example-repo \
  --owner example-owner \
  --name example-repo \
  --scopes issues,wiki

# Sync from the sanitized fixture adapter and build the index
gitcode-mcp sync --offline --repo example-owner/example-repo --issues --wiki --index

All subsequent commands work offline from the local cache.

List sources

gitcode-mcp list --repo example-owner/example-repo

Expected: lists all cached sources (issues, wiki pages) with ids and titles.

Filter by kind:

gitcode-mcp list --repo example-owner/example-repo --kind issue
gitcode-mcp list --repo example-owner/example-repo --kind wiki

Filter by provenance when separating live sync results from deterministic fixtures or local projections:

gitcode-mcp list --repo example-owner/example-repo --provenance live
gitcode-mcp list --repo example-owner/example-repo --provenance fixture

Get a specific source

gitcode-mcp get --repo example-owner/example-repo issue:42

Expected: displays the cached issue body and metadata.

gitcode-mcp get --repo example-owner/example-repo wiki:Home

Expected: displays the cached wiki page body and metadata.

Search sources

gitcode-mcp search --repo example-owner/example-repo "remote issue body"

Expected: returns sources containing the query text in title or body.

Source search is hybrid by default: cache full-text candidates are always included, and a ready local RAG namespace adds semantic candidates. Semantic chunks are grouped back into source results with bounded citations. Responses distinguish requested_mode from effective_mode and report coverage plus any typed lexical fallback. Use --mode full_text when exact/token-only behavior is required; that mode never calls the embedding provider.

Search accepts the same provenance filter:

gitcode-mcp search --repo example-owner/example-repo --provenance live "remote issue body"

Get a snippet

gitcode-mcp get-snippet --repo example-owner/example-repo \
  issue:42 \
  --line-start 1 --line-end 3

Expected: returns lines 1-3 of the issue body.

gitcode-mcp snippet --repo example-owner/example-repo \
  wiki:Home \
  --line-start 1 --line-end 3

Expected: returns lines 1-3 of the wiki page body.

List index chunks

gitcode-mcp list-chunks --repo example-owner/example-repo

Expected: lists all indexed chunks with chunk ids, source references, and offsets.

Backlinks

gitcode-mcp backlinks --repo example-owner/example-repo ISSUE-42

Expected: lists sources that reference ISSUE-42.

Link check

gitcode-mcp link-check --repo example-owner/example-repo

Expected: reports unresolved link targets in cached sources.

Stale index

gitcode-mcp stale-index --repo example-owner/example-repo

Expected: reports sources whose index is missing or out of date.

Recent changes

gitcode-mcp recent --repo example-owner/example-repo --limit 5

Expected: lists the 5 most recently updated sources.

Cache status

gitcode-mcp cache-status --repo example-owner/example-repo

Expected: reports cache statistics including record count, index coverage, WAL status, and storage size.

Sync status

gitcode-mcp sync-status --repo example-owner/example-repo

Expected: reports sync status per source: synced, stale, or missing.

Export snapshot

gitcode-mcp export-snapshot --repo example-owner/example-repo --format json

Expected: emits a deterministic JSON snapshot of cached records and chunks.

gitcode-mcp export-snapshot --repo example-owner/example-repo --format markdown

Expected: emits a deterministic Markdown export.

Diff snapshots

gitcode-mcp diff-snapshot --base-id <snapshot-id-1> --head-id <snapshot-id-2>

Expected: reports differences between two snapshots.

MCP read parity

All CLI read commands have equivalent MCP tools. See MCP Setup for tool names and usage.

The MCP tool response for a given query is byte-identical to the CLI output for the same cache state and parameters.