Skip to main content
Glama

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

Related MCP server: WikiJS MCP Server

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.

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.

Available Tools

6 tools
browse_wikiA
Read-only

Browse wiki sections by topic/parent. Returns section keys and titles without full content. Use this to discover relevant sections before fetching content.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicNoFilter by parent topic (e.g., "Portage Backend", "Approval Workflow Deep Dive")

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYesTotal number of matching sections
errorNoError message if request failed
groupsYesSections grouped by parent topic

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint: true, and the description adds valuable behavioral details beyond that: it returns only keys and titles, excludes full content, and is intended for discovery. This gives the agent a clear picture of the tool's behavior and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences: the first states purpose, the second defines return scope, and the third gives usage guidance. Every sentence earns its place, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (1 optional param with schema description, readOnly annotation, output schema exists). The description covers purpose, return content, and usage timing. The only minor gap is not explicitly clarifying that 'topic' is optional, though the schema already indicates this. Overall, it is adequately complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter, so the baseline is 3. The description's phrase 'by topic/parent' essentially repeats the schema's 'Filter by parent topic' without adding additional semantics like whether the parameter is optional or what happens when omitted. No extra value is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Browse') and resource ('wiki sections') and clearly distinguishes from siblings by stating it returns only 'section keys and titles without full content', positioning it as a lightweight discovery tool versus content-fetching tools like get_wiki_section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance: 'Use this to discover relevant sections before fetching content.' This implies when to use it and hints that other tools fetch full content, but it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_wiki_infoA
Read-only

Get metadata about the connected wiki instance — path, mode (file/directory), and section count.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
modeYesHow the wiki is loaded — single file or directory of .md files
uptimeYesServer uptime in seconds
wikiPathYesAbsolute path to the wiki source
sectionCountYesTotal number of indexed sections
documentCountYesNumber of markdown files loaded (1 in file mode, N in directory mode)

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With the readOnlyHint annotation already declaring the tool's safety profile, the description adds useful behavioral context by specifying what metadata is returned (path, mode, section count). It does not contradict annotations and clarifies the tool's scope without going beyond what's needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and key outputs. No filler words or redundant details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no params), has an output schema, and has a readOnly annotation. The description provides all necessary context: what it does, what it returns, and how it differs from siblings. Nothing substantive is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

This tool requires zero parameters, so the description carries no parameter burden. The baseline for 0-param tools is 4, and the description appropriately focuses on outputs rather than inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: 'Get metadata about the connected wiki instance' and lists the specific metadata fields (path, mode, section count). This clearly distinguishes it from sibling tools that list, browse, search, or get sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for obtaining instance-level metadata, but it does not explicitly state when to use this over siblings or when not to use it. No alternatives are mentioned, so the usage context is only partially clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_wiki_sectionA
Read-only

Retrieve markdown content of a wiki section. Defaults to 8000 chars to save tokens. Set limit higher or use offset to read the full section.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesThe unique slug key of the section (e.g., 'portage-backend-architecture')
limitNoMax characters to return. Default is 8000 but you can set it higher to get the full content in one call.
offsetNoCharacter offset to start from. Use to paginate through large sections.

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoError message if section not found or key invalid
limitNoApplied character limit
titleNoSection display title
offsetNoCurrent character offset
parentNoParent topic name
sourceNoSource file path
contentNoSection markdown content
hasMoreNoWhether more content exists beyond this page
nextOffsetNoOffset for the next page, if hasMore is true
breadcrumbsNoHeading hierarchy from root to parent
suggestionsNoSimilar keys when section not found
totalLengthNoTotal content length in characters
relatedSectionsNoRelated sections by key prefix

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool defaults to 8000 characters to save tokens and that limit/offset can be used to retrieve the full section. This adds behavioral context beyond the readOnlyHint annotation, which already signals safety. No contradiction with the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, with the primary action stated first and supporting details about pagination in the second. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core retrieval behavior and pagination effectively. Since an output schema exists, return format is already defined, and the annotations cover read-only status. The tool is simple enough that this description is sufficient, though it could reference how to discover section keys via sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with descriptions for key, limit, and offset. The description's mention of defaulting to 8000 chars and using offset essentially restates schema information, but adds the rationale of saving tokens. This minor extra context slightly elevates it above baseline, but the schema carries most of the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves markdown content of a wiki section, which is a specific verb and resource. However, it does not explicitly distinguish itself from sibling tools like get_wiki_sections or browse_wiki, though the mention of 'markdown content' implies content retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to choose this tool over alternatives. It only discusses limit and offset parameters, which are usage details for the tool itself, not comparisons with siblings. No when-to-use or exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_wiki_sectionsA
Read-only

Retrieve multiple wiki sections at once. Each section is truncated to save tokens.

ParametersJSON Schema
NameRequiredDescriptionDefault
keysYesArray of section slug keys to retrieve (max 20)

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoError message if request failed
sectionsYesRetrieved sections; error field present if section not found
errorCountYesNumber of sections that failed
successCountYesNumber of successfully retrieved sections

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond the readOnlyHint annotation by disclosing that each section is truncated to save tokens. This is a non-obvious behavioral trait that affects the returned data, and it is not derivable from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the primary action. It avoids repetition and every word adds value, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one parameter, output schema present, readOnly annotation), the description is complete enough to understand the tool's behavior. It covers the core purpose, the batch capability, and the truncation behavior, making it fully contextual.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the single parameter 'keys' with a clear description of being an array of section slug keys. The description adds no additional parameter-specific details beyond what the schema already documents, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb and resource: 'Retrieve multiple wiki sections at once.' It explicitly distinguishes itself from the sibling tool 'get_wiki_section' by emphasizing batch retrieval, which differentiates the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool versus the singular sibling 'get_wiki_section'—for retrieving multiple sections at once. However, it does not explicitly state when not to use it or mention other alternatives, so it stops short of full usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_wikiA
Read-only

List all available wiki section keys. Use browse_wiki instead for topic-filtered results.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYesTotal number of sections
errorNoError message if request failed
sectionsYesAll wiki sections

TDQS

A4.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the behavioral detail that it lists ALL section keys without filtering, which is useful but limited. Given the annotation coverage, a 3 is appropriate as the description adds some value but not rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences: the first states the primary function, the second provides an alternative. There is no wasted text, and it is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list-all tool with no parameters and an existing output schema, the description is complete. It specifies what is listed and points to the alternative for filtered results, covering all necessary guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema description coverage is 100% (vacuous). Per baseline for 0 params, this scores 4. The description correctly does not attempt to document parameters that do not exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool 'List all available wiki section keys', using a specific verb and resource. It also distinguishes from sibling browse_wiki by noting it provides topic-filtered results, making the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description directly instructs to 'Use browse_wiki instead for topic-filtered results', thereby specifying when not to use this tool and naming the alternative for that case. This provides explicit usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_wikiA
Read-only

Search wiki section titles and content by keyword. Returns matching section keys with snippets. Header matches are prioritized over content matches.

ParametersJSON Schema
NameRequiredDescriptionDefault
fuzzyNoEnable fuzzy matching for typos
limitNoMaximum number of results to return
queryYesKeyword to search

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYesNumber of results
errorNoError message if request failed
resultsYesMatching sections, header matches first
suggestionsNoSimilar keys when no results found

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral context beyond that: it specifies that header matches are prioritized over content matches and that results include snippets. This gives the agent insight into result ordering and content, which annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences, front-loaded with the core purpose and followed by a relevant behavioral detail. Every word earns its place; there is no redundant repetition of schema information or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and full param descriptions, the description covers the essential behavioral aspects (search scope, prioritization, snippet return). It is sufficiently complete for a search tool, and the sibling tools provide additional context for disambiguation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, with all three parameters (query, fuzzy, limit) described in the schema itself. The description does not add parameter-specific semantics beyond what the schema says, though it reinforces overall search behavior. This matches the baseline 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and resource ('wiki') and adds detail about what's searched ('section titles and content') and the return format ('matching section keys with snippets'). This clearly distinguishes it from sibling tools like list_wiki and get_wiki_section, which are non-search operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when you need to search by keyword, but it does not explicitly state when to use this over alternatives, nor does it mention exclusions. The purpose is clear from context, yet there is no direct comparison to sibling list/browse/get tools, so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observedbrowse_wiki
    • First observedget_wiki_info
    • First observedget_wiki_section
    • First observedget_wiki_sections
    • First observedlist_wiki
    • First observedsearch_wiki

TDQS

A4.1/5.0

Scored across 6 tools

Disambiguation4/5

Most tools have clear distinct purposes: search, browse, get single, get multiple, and info are unambiguous. However, list_wiki and browse_wiki overlap significantly since both return section keys, though browse offers topic filtering.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: list_, browse_, search_, get_wiki_section(s), get_wiki_info. The verbs are descriptive and predictable.

Tool Count5/5

Six tools is well-scoped for a wiki server. Each tool covers a distinct aspect of reading wiki content, and the count feels neither sparse nor bloated.

Completeness4/5

The surface covers all read-related workflows: discovery (list/browse/search), retrieval (single/multiple sections), and metadata. Missing write operations (create/update/delete) but likely outside the apparent read-only scope.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers