mcp-wiki
Enables contextual wiki lookups for GitHub Copilot within VS Code during development.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-wikisearch wiki for deployment guide"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 linksDirectory 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, errorMCP Tools
Tool | Description | Parameters |
| List all available wiki sections | none |
| Browse sections by topic/parent |
|
| Search sections by keyword |
|
| Get a single section's content |
|
| Get multiple sections at once |
|
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 startArchitecture
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 configurationWikiParser Class
Constructor — validates file/directory source, loads markdown docs, builds heading index with byte positions
search(query, { fuzzy, limit })— find sections by keywordfindSimilar(key)— get similar keys via levenshtein distancegetSection(key)— retrieve content for a single sectiongetSections(keys)— batch retrieve multiple sectionsreload()— re-read file and rebuild indexclose()— 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/getSectionfor backward compatibilityAmbiguous legacy keys require suffixed form (
-1,-2) to resolve deterministicallySearch 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:
Header matches — exact or fuzzy match in heading text
Content matches — keyword found within section body
This ensures the most relevant sections appear first.
Security
Source validation (
.md/.markdownfile or directory)Safe path resolution via
path.resolve+ fs stat checksFile 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 testCovers: 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 toolsbrowse_wikiARead-only
Browse wiki sections by topic/parent. Returns section keys and titles without full content. Use this to discover relevant sections before fetching content.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Filter by parent topic (e.g., "Portage Backend", "Approval Workflow Deep Dive") |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | Total number of matching sections |
| error | No | Error message if request failed |
| groups | Yes | Sections grouped by parent topic |
TDQS
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.
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.
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.
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.
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.
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_infoARead-only
Get metadata about the connected wiki instance — path, mode (file/directory), and section count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| mode | Yes | How the wiki is loaded — single file or directory of .md files |
| uptime | Yes | Server uptime in seconds |
| wikiPath | Yes | Absolute path to the wiki source |
| sectionCount | Yes | Total number of indexed sections |
| documentCount | Yes | Number of markdown files loaded (1 in file mode, N in directory mode) |
TDQS
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.
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.
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.
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.
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.
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_sectionARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The unique slug key of the section (e.g., 'portage-backend-architecture') | |
| limit | No | Max characters to return. Default is 8000 but you can set it higher to get the full content in one call. | |
| offset | No | Character offset to start from. Use to paginate through large sections. |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Error message if section not found or key invalid |
| limit | No | Applied character limit |
| title | No | Section display title |
| offset | No | Current character offset |
| parent | No | Parent topic name |
| source | No | Source file path |
| content | No | Section markdown content |
| hasMore | No | Whether more content exists beyond this page |
| nextOffset | No | Offset for the next page, if hasMore is true |
| breadcrumbs | No | Heading hierarchy from root to parent |
| suggestions | No | Similar keys when section not found |
| totalLength | No | Total content length in characters |
| relatedSections | No | Related sections by key prefix |
TDQS
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.
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.
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.
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.
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.
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_sectionsARead-only
Retrieve multiple wiki sections at once. Each section is truncated to save tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | Array of section slug keys to retrieve (max 20) |
Output Schema
| Name | Required | Description |
|---|---|---|
| error | No | Error message if request failed |
| sections | Yes | Retrieved sections; error field present if section not found |
| errorCount | Yes | Number of sections that failed |
| successCount | Yes | Number of successfully retrieved sections |
TDQS
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.
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.
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.
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.
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.
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_wikiARead-only
List all available wiki section keys. Use browse_wiki instead for topic-filtered results.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | Total number of sections |
| error | No | Error message if request failed |
| sections | Yes | All wiki sections |
TDQS
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.
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.
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.
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.
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.
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_wikiARead-only
Search wiki section titles and content by keyword. Returns matching section keys with snippets. Header matches are prioritized over content matches.
| Name | Required | Description | Default |
|---|---|---|---|
| fuzzy | No | Enable fuzzy matching for typos | |
| limit | No | Maximum number of results to return | |
| query | Yes | Keyword to search |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of results |
| error | No | Error message if request failed |
| results | Yes | Matching sections, header matches first |
| suggestions | No | Similar keys when no results found |
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v1.0.0- First observed
browse_wiki - First observed
get_wiki_info - First observed
get_wiki_section - First observed
get_wiki_sections - First observed
list_wiki - First observed
search_wiki
TDQS
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Hosted markdown project wikis your team's AI assistants read, search, and update over MCP.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
A cited wiki of your GitHub repo: search, read pages, find symbols and ask, with line citations.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to search and retrieve content from WikiJS knowledge bases, allowing integration with your Wiki through simple search and retrieval tools.418 npm6MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search, retrieve, and optionally edit pages in a WikiJS knowledge base via the Model Context Protocol.29 npm1MIT

@growi/mcp-serverofficial
AlicenseBqualityAmaintenanceConnects AI models to GROWI wikis for search and retrieval, enabling context-aware responses from an organization's knowledge base.3197 npm19MIT- FlicenseAqualityDmaintenanceEnables natural language query and ingestion of wiki knowledge bases built from documents, powered by Claude Agent SDK skills.2-