# wiki-explore

A dependency-free local CLI and stdio MCP server for searching, reading, and inspecting a
Git-backed Markdown wiki. It is a reader, not a hosted knowledge service.

`wiki-explore` never uploads wiki content, starts a network listener, creates credentials, or
writes wiki pages. Query commands are read-only. `sync` is explicit and only fast-forwards a
clean checkout on `main`; `install --yes` only writes an owned local MCP configuration entry.

## Install

Requires Python 3.11+.

```bash
python3 -m pip install --user --no-deps "git+https://github.com/halaprix/wiki-explore.git"
```

For development:

```bash
python3 -m pip install --user --no-deps .
python3 -m unittest discover -s tests -v
```

## Wiki contract

The selected checkout must contain `SCHEMA.md` and `index.md`. Pages exposed by search and read
must live directly in one of these directories:

- `entities/`
- `concepts/`
- `comparisons/`
- `queries/`

Other files, nested files, and symlinked pages are not exposed. This deliberately keeps the tool
small and prevents an MCP client from traversing outside the curated page surface.

## CLI

```bash
wiki-explore status --repo /path/to/wiki
wiki-explore search --repo /path/to/wiki "rate limits"
wiki-explore read --repo /path/to/wiki concepts/rate-limits.md

# An explicit, safe Git update: clean checkout, main branch, origin remote, fast-forward only.
wiki-explore sync --repo /path/to/wiki
```

Search returns JSON. Read returns the original Markdown for one canonical page. Status reports the
local revision and worktree state.

## MCP

The stdio server exposes exactly three read-only tools:

- `wiki_search(query, limit?)`
- `wiki_read(path)`
- `wiki_status()`

Run it directly:

```bash
wiki-explore serve --mcp --repo /path/to/wiki
```

Or install an owned MCP entry for supported local clients. Installation is a dry-run unless
`--yes` is supplied. It refuses to replace a conflicting `wiki-explore` entry and backs up an
existing configuration before changing it.

```bash
wiki-explore install --targets claude,codex --repo /path/to/wiki
wiki-explore install --targets claude,codex --repo /path/to/wiki --yes
```

Supported installer targets: `agy`, `claude`, `codex`, and `grok`.

## Security model and non-goals

This project is intentionally local-first:

- no hosted API, proxy, index, telemetry, or background synchronization;
- no content editing, candidate submission, authentication, or secrets;
- no recursive filesystem browsing; only canonical Markdown pages are queryable;
- no implicit Git writes; synchronization is user-invoked and uses `git pull --ff-only`.

It is not a replacement for a wiki's review process or source control. The Git remote remains the
shared source of truth; this tool only reads a local checkout.

## Development

```bash
python3 -m unittest discover -s tests -v
python3 scripts/check_public_safety.py
python3 -m build
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).