# LLM-Wiki_MCP

A local knowledge base built from PDF lecture slides on Agentic Coding, exposed
through a browser viewer and an MCP server. No cloud services are required to
run the wiki or the viewer.

---

## What this project does

1. **Compiles** a folder of PDFs into an interlinked Markdown wiki using
   `compile_wiki.py` and `pypdf`.
2. **Serves** the wiki as a browser-readable site via `viewer/server.py`.
3. **Exposes** the wiki as an MCP server (`os_wiki_mcp_server.py`) so that
   Claude Desktop and Claude Code can access the wiki through the MCP server.

The wiki covers nine lectures on Agentic Coding Basics:
vibe coding, agentic coding, SDLC pipelines, agent specifications,
subprocess calling, planning mode, orchestration, MCP, loops and hooks.

---

## Repository structure

```
os-wiki-mcp/
├── os_wiki_mcp_server.py   MCP server — 4 registered tools
├── compile_wiki.py         PDF → Markdown compilation pipeline
├── wiki_tool.py            CLI: lint, search, query
├── requirements.txt        Python dependencies
├── .gitignore
│
├── viewer/
│   └── server.py           Local HTTP wiki browser (port 8000)
│
├── skills/
│   ├── ingest_source.md        Step-by-step ingest procedure
│   ├── lint_and_repair.md      Step-by-step lint and repair procedure
│   └── query_and_writeback.md  Step-by-step query and write-back procedure
│
├── wiki/
│   ├── sources/            9 compiled source summaries
│   ├── concepts/           8 concept pages
│   ├── entities/           4 entity profiles
│   ├── analyses/           2 synthesis reports
│   ├── templates/          Page scaffolds (source, concept, entity, analysis)
│   ├── index.md            Master table of contents
│   └── log.md              Append-only change log
│
├── raw/                    9 original PDF files (immutable)
├── docs/                   Design documents
├── demo/
│   └── screenshot.png
│
├── AGENTS.md               Agent persona and SOPs
├── SCHEME.md               YAML frontmatter schema
├── TASK.md                 Task contract (Task 1 complete)
├── CLAUDE.md               Environment-level rules
└── journal.md              Append-only operation log
```

---

## Installation

Python 3.10 or higher is required.

```bash
pip install -r requirements.txt
```

`requirements.txt` installs:

- `mcp>=1.0.0` — MCP Python SDK (provides `mcp.server.fastmcp.FastMCP`)
- `pypdf>=4.0.0` — PDF text extraction used by `compile_wiki.py`

The viewer also uses the `markdown` package for richer rendering:

```bash
pip install markdown
```

No Anthropic API key is needed. The current implementation uses local
rule-based synthesis only.

---

## Generating the wiki

```bash
python compile_wiki.py
```

This reads every PDF in `raw/`, extracts text with `pypdf`, derives concepts
and entities using keyword matching, writes Markdown pages into `wiki/`, and
updates `wiki/index.md` and `wiki/log.md`. Existing pages in `wiki/sources/`,
`wiki/concepts/`, and `wiki/entities/` are cleared and rewritten on each run.

To verify the result:

```bash
python wiki_tool.py lint     # checks for dead links and orphan pages
python wiki_tool.py search "mcp"
```

---

## Running the viewer

```bash
python viewer/server.py
```

Open **http://localhost:8000** in a browser.

```
Options:
  --port  PORT    Port to listen on (default: 8000)
  --host  HOST    Host to bind    (default: 127.0.0.1)
```

The viewer provides:

- Sidebar listing all pages grouped by type (Sources, Concepts, Entities, Analyses)
- Client-side sidebar filter by slug text
- Page type filter buttons (All / Source / Concept / Entity / Analysis)
- Markdown rendering with fenced code blocks and tables
- `[[wikilink]]` converted to clickable navigation links
- Frontmatter shown as a metadata card at the top of each page
- Dark / light mode toggle, persisted in `localStorage`
- No JavaScript framework, no external CDN, no API calls

---

## Running the MCP server

```bash
python os_wiki_mcp_server.py
```

The server runs as a **stdio MCP process** and prints its status to stderr:

```
[OS Wiki MCP] Server starting...
[OS Wiki MCP] Wiki root : /path/to/wiki
[OS Wiki MCP] Tools     : search_wiki, get_page, list_pages, query_wiki
[OS Wiki MCP] Transport : stdio
[OS Wiki MCP] Ready.
```

### Claude Desktop configuration

Add the following to your Claude Desktop config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "os-wiki": {
      "command": "python",
      "args": ["/absolute/path/to/os_wiki_mcp_server.py"]
    }
  }
}
```

Restart Claude Desktop. The **os-wiki** server appears in the tools list.

---

## Available MCP tools

### `search_wiki`

Searches all wiki pages (title, tags, body text) for a keyword.
Returns up to 5 matching line snippets per page.

```
search_wiki(query="agentic")
search_wiki(query="mcp", page_type="concept")
```

`page_type` is optional and accepts: `source`, `concept`, `entity`,
`analysis`, `meta`.

Response fields: `query`, `total`, `results` (list of `slug`, `title`,
`type`, `rel_path`, `snippets`).

---

### `get_page`

Fetches a single wiki page by its slug and returns its full content.

```
get_page(slug="mcp")
get_page(slug="andrej-karpathy")
```

Response fields: `found`, `slug`, `title`, `type`, `rel_path`,
`frontmatter`, `body`, `outgoing_links`.

If the slug does not exist, `found` is `false` and an `error` message
is returned.

---

### `list_pages`

Lists all non-template wiki pages, optionally filtered by type.

```
list_pages()
list_pages(page_type="source")
```

Response fields: `total`, `page_type`, `pages` (list of `slug`, `title`,
`type`, `rel_path`). Pages are sorted by type then slug.

---

### `query_wiki`

Answers a natural language question using local rule-based synthesis.
Matches the question against known topic areas (vibe coding, agentic coding,
MCP, harness, hooks) and returns a pre-composed cross-linked Markdown report.

```
query_wiki(question="What is the difference between vibe and agentic coding?")
query_wiki(question="How does MCP work?")
```

Response fields: `question`, `title`, `slug`, `answer` (full Markdown),
`note` (phase notice).

This tool does not call any external API. LLM-powered synthesis is not
yet implemented.

---

## Harness

Five files govern how agents and the compiler behave:

| File | Purpose |
|:---|:---|
| `AGENTS.md` | Defines the LLM Wiki Librarian persona, three SOPs (Ingest, Query & Write-Back, Lint), and forbidden actions |
| `SCHEME.md` | Canonical directory layout, slug conventions, and required YAML frontmatter fields for each page type |
| `TASK.md` | Project task contract and completion checklist (status: complete) |
| `CLAUDE.md` | Environment-level rules: CLI commands, Markdown-only constraint, harness compliance requirement |
| `journal.md` | Append-only log of operations; one line added after each successful task cycle |

The `skills/` directory provides step-by-step checklists for the three
SOPs defined in `AGENTS.md`: ingesting a new source, running lint and
repairing errors, and querying with optional write-back.

---

## Demo

![Viewer screenshot](demo/screenshot.png)
This screenshot demonstrates the wiki viewer rendering the generated knowledge base.