# bugswiki — MCP server setup for AI agents

This wiki is served by bugswiki, a lightweight local-first wiki with an
MCP server. Follow this page to give an AI client (OpenCode, Claude Desktop,
Cursor, ...) read/write access to this wiki.

## 1. Prerequisites

- Python 3.12+ (uv will auto-install a managed one if missing)
- git, to obtain the source

## 2. Install

```bash
git clone {your-git-repo-url} bugswiki
cd bugswiki
uv sync
uv run bugswiki list   # verify: should print the notes of this wiki
```

## 3. Register with your MCP client

### Option A — remote mode (wiki stays on THIS server)

The vault, RAG indexes and git repo live on this server. Your machine only
runs the MCP client; every tool call travels over HTTP to:

    https://dev-wiki.bugscoder.com

Config (OpenCode / opencode.json, or equivalent for other clients):

```json
{
  "mcp": {
    "servers": {
      "wiki": {
        "type": "local",
        "command": "uv",
        "args": ["run", "--directory", "/path/to/bugswiki", "bugswiki-mcp"],
        "environment": { "BUGSWIKI_API_URL": "https://dev-wiki.bugscoder.com" }
      }
    }
  }
}
```

### Option B — local mode (wiki on your machine)

Unset BUGSWIKI_API_URL (or omit it). The MCP server uses its own vault at
~/.bugswiki/vault and downloads the embedding model (~90MB) on first
wiki_search. Same config without the environment block.

## 4. Available tools

Retrieve (pull knowledge OUT of the wiki):
- wiki_search(query, top_k)  — RAG search; compact excerpts, token-cheap.
  Call at the START of any question answerable from stored knowledge.
- wiki_read(path)            — full note markdown (when excerpts aren't enough)
- wiki_graph(path?, depth?)  — link graph (full vault, or local to a note)
- wiki_tags()                — tag -> note count
- wiki_notes_by_tag(tag)     — notes scoped to a tag
- wiki_backlinks(path)       — notes linking TO a note
- wiki_recent(limit)         — recently modified notes

Store (put knowledge INTO the wiki):
- wiki_remember(content, tags?, merge_threshold?) — SMART store. Embeds the
  content, finds similar notes; if close enough it APPENDS to that note
  (dated section), else creates knowledge/<slug>.md. Use this whenever the
  user shares durable knowledge (facts, decisions, gotchas, procedures).
- wiki_write(path, content)  — low-level create/overwrite at an exact path;
  prefer wiki_remember unless the user names a target path.
- wiki_delete(path)          — remove a note
- wiki_list()                — all notes (path, title, tags)
- wiki_sync()                — pull + push vault with GitHub

## 5. Rules of engagement for agents

- RETRIEVE: start questions with wiki_search; wiki_read only when needed.
- STORE: use wiki_remember — it auto-decides update vs create and avoids
  duplicates. Pass tags so knowledge stays organized.
- Always wiki_write with a folder path, e.g. "knowledge/rag-pipelines.md".
- Tag notes (frontmatter tags: [topic]) so they appear in the tag index.
- Link related notes with [[wikilinks]] so the graph and backlinks stay useful.
- Call wiki_sync after a batch of writes to publish to GitHub.
- Never delete notes you did not create in this session without asking.

## 6. Verify

Ask the AI: "list the wiki notes" — it should see the same notes as this UI.