mcp-wiki

Wiki Explorer MCP Server

A generic MCP (Model Context Protocol) server that exposes any project wiki to AI assistants, enabling contextual wiki lookups during development sessions.

Features

• Lazy loading — indexes headings once, loads content on-demand via byte positions
• Auto-reload — watches the wiki file or markdown directory for changes with debouncing
• Fuzzy search — handles typos and partial matches via levenshtein distance
• Content search — searches within section content, not just headings
• Custom anchors — use {#anchor} syntax in headings for stable TOC links
• Directory mode — index entire markdown directory trees with file-prefixed keys
• Legacy key support — backward-compatible lookup of heading-only keys
• Heading hierarchy — tracks full breadcrumb path for nested sections
• Batch fetch — retrieve multiple sections in one call (max 20)
• Smart suggestions — returns similar keys when a section isn't found
• Path safety — validates markdown sources and safe path resolution
• Graceful shutdown — handles SIGINT/SIGTERM, cleans up watchers
• Structured logging — configurable log levels for debugging

Setup

# 1. Install dependencies
npm install

# 2. Configure wiki path
cp .env.example .env

# 3. Run tests
npm test

.env

WIKI_PATH=path/to/your/wiki-source  # file (.md/.markdown) or directory
LOG_LEVEL=info  # debug, info, warn, error

MCP Tools

| Tool | Description | Parameters | |---|---|---| | list_wiki | List all available wiki sections | none | | browse_wiki | Browse sections by topic/parent | topic (string, optional) | | search_wiki | Search sections by keyword | query (string), fuzzy (boolean) | | get_wiki_section | Get a single section's content | key (string), offset (number), limit (number) | | get_wiki_sections | Get multiple sections at once | keys (string[], max 20) |

Connecting to AI Assistants

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "wiki-explorer": {
      "command": "node",
      "args": ["/path/to/wiki-explorer/index.js"],
      "env": {
        "WIKI_PATH": "/path/to/your/docs/wiki"
      }
      }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "wiki-explorer": {
      "command": "node",
      "args": ["/path/to/wiki-explorer/index.js"],
      "env": {
        "WIKI_PATH": "/path/to/your/docs/wiki"
      }
      }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "wiki-explorer": {
      "command": "node",
      "args": ["/path/to/wiki-explorer/index.js"],
      "env": {
        "WIKI_PATH": "/path/to/your/docs/wiki"
      }
      }
  }
}

Running

# Start MCP server (stdio transport)
npm start

# Debug mode
LOG_LEVEL=debug npm start

Architecture

index.js          → MCP server + tool registration + signal handlers
utils.js          → WikiParser class (indexing, search, content extraction)
logger.js         → Structured logging with configurable levels
test.js           → 67 assertions covering all functionality
.env              → WIKI_PATH, LOG_LEVEL configuration

WikiParser Class

• Constructor — validates file/directory source, loads markdown docs, builds heading index with byte positions
• search(query, { fuzzy, limit }) — find sections by keyword
• findSimilar(key) — get similar keys via levenshtein distance
• getSection(key) — retrieve content for a single section
• getSections(keys) — batch retrieve multiple sections
• reload() — re-read file and rebuild index
• close() — stop file watcher

Key Compatibility

• Canonical keys in directory mode are prefixed by file slug (e.g. user-wiki-approval-workflow-deep-dive)
• Legacy heading-only keys are still accepted in getMeta/getSection for backward compatibility
• Ambiguous legacy keys require suffixed form (-1, -2) to resolve deterministically
• Search accepts legacy key queries but returns canonical keys

Custom Anchors

Headings can include a custom anchor using {#anchor-name} syntax at the end of the heading text:

## Backend Architecture {#portage-backend-architecture}

This creates a stable anchor that can be used in table of contents or direct links. The anchor is stripped from the displayed title but registered as a legacy alias for lookup.

Content Search

Search matches both heading text and section content. Results are prioritized:

1. Header matches — exact or fuzzy match in heading text
2. Content matches — keyword found within section body

This ensures the most relevant sections appear first.

Security

• Source validation (.md/.markdown file or directory)
• Safe path resolution via path.resolve + fs stat checks
• File size cap (50MB default)
• Key format validation (lowercase alphanumeric + hyphens)
• Batch request limits (max 20 keys)

Graceful Shutdown

Handles SIGINT, SIGTERM, uncaughtException, and unhandledRejection. Cleans up file watchers and exits cleanly.

Testing

npm test

Covers: initialization, path validation, directory mode, search (headers + content), fuzzy search, findSimilar, meta, sections, batch fetch, boundaries, reload, file watcher, key format validation, custom anchors, legacy key resolution, and cleanup.

CI/CD

GitHub Actions runs tests on Node 20 and 22 for every push/PR to main. See .github/workflows/ci.yml.