mcp-wms-wiki/CLAUDE.md

# CLAUDE.md — MCP Wiki Server for EasyWMS

## Project Overview

Build an MCP (Model Context Protocol) server that serves a compiled wiki about EasyWMS (Mecalux WMS) to Claude. The wiki contains ~65-70 dense, cross-referenced Markdown pages covering every aspect of the WMS: core entities, operational flows, modules, architecture, troubleshooting.

This MCP server is **read-only** — it serves knowledge. It is designed to work alongside a separate MCP API server (already built) that queries live WMS data. Together:
- **MCP Wiki** (this project) = "how the WMS is supposed to work" (theory, logic, configuration)
- **MCP API** (separate project) = "what the WMS actually contains right now" (live data, logs, workflows)

## Target Environment

- **Runtime:** Node.js (v18+)
- **OS:** Windows Server (same VM as the WMS) or any machine with Node.js
- **Transport:** stdio (launched by Claude Desktop or Claude Code)
- **Dependencies:** `@modelcontextprotocol/sdk`, `dotenv`, and minimal others — keep it lightweight
- **No network required:** all data is local (wiki/ folder)

## Project Structure

```
mcp-wiki-server/
├── CLAUDE.md              ← This file
├── package.json
├── .env                   ← Wiki path configuration
├── wiki/                  ← Compiled wiki pages (copied from mcp-wiki project)
│   ├── _index.md
│   ├── _log.md
│   ├── _lint_report.md
│   ├── glossary.md
│   ├── concepts/          ← ~30 concept pages
│   ├── modules/           ← ~23 module pages
│   ├── architecture/      ← ~4 pages
│   └── operations/        ← ~2 pages
└── src/
    ├── index.js            ← Main MCP server entry point
    ├── config/
    │   └── constants.js    ← Paths, cache settings
    ├── services/
    │   ├── wiki-index.js   ← Loads and parses _index.md + frontmatter from all pages
    │   ├── search.js       ← Full-text + tag search across wiki pages
    │   └── page.js         ← Read individual wiki pages
    ├── tools/
    │   ├── search-tool.js  ← search_wiki tool
    │   ├── page-tool.js    ← get_wiki_page tool
    │   ├── browse-tool.js  ← list_wiki_sections tool
    │   ├── glossary-tool.js← get_glossary_term tool
    │   └── related-tool.js ← get_related_pages tool
    └── resources/
        ├── overview.js     ← wiki://overview resource
        └── entities-map.js ← wiki://entities-map resource
```

## MCP Tools to Implement (5 tools)

### 1. `search_wiki`
**Purpose:** Search across all wiki pages by keyword, tag, or entity name.
**Parameters:**
- `query` (string, required) — Search terms
- `tags` (string[], optional) — Filter by tags from frontmatter
- `type` (string, optional) — Filter by page type: "concept", "module", "architecture", "operation"
- `max_results` (number, optional, default: 5) — Max pages returned

**Behavior:**
1. Search in page titles (highest weight)
2. Search in frontmatter tags and `related` entries (medium weight)
3. Search in page body text (lower weight)
4. Return results sorted by relevance score
5. Each result includes: title, path, type, summary (first paragraph), relevance score

**Implementation notes:**
- Build an in-memory inverted index at startup from all wiki pages
- Parse YAML frontmatter to extract title, type, tags, related, sources
- Index words from title, tags, headings (h2/h3), and body text with different weights
- Support partial matches and case-insensitive search
- The search index should be rebuilt if wiki files change (check mtime on page load, or just rebuild at startup since pages are static)

### 2. `get_wiki_page`
**Purpose:** Load the full content of a specific wiki page.
**Parameters:**
- `path` (string, required) — Page path relative to wiki/ (e.g., "concepts/container.md")

**Behavior:**
1. Read the file from wiki/{path}
2. Return full markdown content including frontmatter
3. If page not found, return a helpful error listing similar page names (fuzzy match)

**Implementation notes:**
- Simple file read — no transformation needed
- Add a "Related pages" footer with clickable links if the frontmatter has `related` entries
- Cache file contents in memory (pages don't change at runtime)

### 3. `list_wiki_sections`
**Purpose:** Return the complete wiki structure for navigation.
**Parameters:**
- `section` (string, optional) — Filter by section: "concepts", "modules", "architecture", "operations", or omit for all

**Behavior:**
1. Return a structured list of all pages grouped by section
2. Each entry includes: title, path, type, one-line summary
3. If section filter is provided, return only that section

**Implementation notes:**
- Built from the in-memory index (same data as search_wiki)
- This is the first tool Claude should call when it needs to orient itself

### 4. `get_glossary_term`
**Purpose:** Quick definition lookup for WMS-specific terms.
**Parameters:**
- `term` (string, required) — Term to look up (case-insensitive)

**Behavior:**
1. Parse glossary.md into a dictionary of term → definition
2. Search for exact match first, then partial match
3. Return the definition + link to the glossary page
4. If not found, suggest similar terms

**Implementation notes:**
- Parse glossary.md at startup into a Map<string, string>
- Support abbreviations (e.g., "PDL" → "Picking Dedicated Location")
- Fuzzy matching: Levenshtein distance or simple startsWith/includes

### 5. `get_related_pages`
**Purpose:** Find all pages related to a given entity, command, or concept.
**Parameters:**
- `name` (string, required) — Entity name, command name, or concept (e.g., "Container", "putaway", "ASN")

**Behavior:**
1. Search the `related` frontmatter field of all pages for the given name
2. Also search page body for mentions of the name
3. Return list of pages that reference this concept, with context (the sentence/heading where it's mentioned)

**Implementation notes:**
- Uses the same inverted index as search_wiki
- Additionally parses `related` frontmatter arrays
- Useful when Claude wants to understand all the places a concept appears

## MCP Resources to Implement (2 resources)

### `wiki://overview`
**Content:** A condensed overview of the EasyWMS wiki — what sections exist, how many pages, key concepts. This is automatically loaded into Claude's context when the MCP connects.

**Build from:** `wiki/_index.md` content + page counts per section

### `wiki://entities-map`
**Content:** The entities relationship map showing how WMS entities relate to each other.

**Build from:** `wiki/architecture/entities-map.md` content

## Implementation Guidelines

### Startup Sequence
1. Read `WIKI_PATH` from `.env` (default: `./wiki`)
2. Scan all `.md` files in wiki/
3. Parse frontmatter (YAML between `---` markers) for each file
4. Build in-memory index:
   - `pages[]` — array of {path, title, type, tags, related, summary, body, headings}
   - `invertedIndex{}` — word → [{page, weight, context}]
   - `glossary{}` — term → definition
5. Register MCP tools and resources
6. Start stdio transport

### Frontmatter Parsing
Every wiki page has this structure:
```markdown
---
title: "Page Title"
type: concept | module | architecture | operation
sources:
  - path/to/raw/source.md
related:
  - concepts/other-page.md
  - modules/some-module.md
last_compiled: "2026-04-10"
---

# Page Title

Page body content...
```

Parse the YAML between the `---` markers. Use a simple regex-based parser or `yaml` npm package.

### Search Relevance Scoring
```
title exact match:     100
title partial match:    50
tag exact match:        40
heading (h2/h3) match:  30
related entry match:    25
body text match:        10
```

### Error Handling
- All tools must return structured errors, never crash the server
- Use `console.error()` for logging (stdout reserved for MCP protocol)
- If wiki/ folder is missing or empty, return a clear error message

### Performance
- Wiki is small (~70 files, ~1-2MB total) — load everything into memory at startup
- No database needed
- No pagination needed for search results (max 10-20 results)
- File watching is optional (pages are static between syncs)

## .env Configuration

```env
# Path to the wiki folder (absolute or relative to project root)
WIKI_PATH=./wiki

# Optional: enable debug logging
DEBUG=false
```

## Claude Desktop Integration

After building, configure Claude Desktop to use both MCP servers:

```json
{
  "mcpServers": {
    "wms-wiki": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-wiki-server\\src\\index.js"]
    },
    "wms-api": {
      "command": "node",
      "args": ["C:\\path\\to\\wms-mcp-server\\src\\index.js"]
    }
  }
}
```

## Custom Instructions for Claude Desktop

When both MCPs are configured, add this to Claude Desktop's custom instructions:

```
You have access to two MCP servers for EasyWMS:

1. wms-wiki — Documentation and knowledge base. Use it to understand HOW the WMS works:
   - search_wiki: find relevant documentation pages
   - get_wiki_page: read full page content
   - list_wiki_sections: browse available documentation
   - get_glossary_term: look up WMS-specific terms
   - get_related_pages: find all pages mentioning a concept

2. wms-api — Live WMS data. Use it to see WHAT the WMS currently contains:
   - query_wms_entities: query live data via LINQ
   - search_workflows: find workflow definitions
   - search_ad_elements: search application dictionary
   - read_recent_logs: check recent log entries

WORKFLOW for diagnosing issues:
1. FIRST use wms-wiki to understand the feature/concept involved
2. THEN use wms-api to check the actual state of the WMS
3. Compare theory (wiki) vs reality (live data) to identify the problem
4. Use wiki error/troubleshooting sections for known solutions

WORKFLOW for answering "how does X work":
1. search_wiki or list_wiki_sections to find relevant pages
2. get_wiki_page to read the full documentation
3. If needed, get_glossary_term for specific terminology

Always consult the wiki BEFORE querying live data — it gives you the context to interpret what the API returns.
```

## Testing

After implementation, test these scenarios in Claude Desktop:

1. **"What is a container in EasyWMS?"**
   → Should call search_wiki("container") → get_wiki_page("concepts/container.md")

2. **"How does putaway work?"**
   → Should call get_wiki_page("concepts/putaway.md") → comprehensive answer

3. **"What's a PDL?"**
   → Should call get_glossary_term("PDL") → "Picking Dedicated Location" + link to replenishment.md

4. **"What ERP messages are involved in reception?"**
   → Should call search_wiki("reception ERP") → get_wiki_page("concepts/reception.md") → extract ERP section

5. **"Why are my putaway tasks failing?"** (with wms-api also connected)
   → Should call search_wiki("putaway errors") → read troubleshooting → then query live WMS data for comparison

6. **"List all available modules"**
   → Should call list_wiki_sections("modules") → return all module pages

## Development Commands

```bash
# Install dependencies
npm install

# Run locally for testing
node src/index.js

# Test with MCP inspector (if available)
npx @modelcontextprotocol/inspector node src/index.js
```

## Dependencies

```json
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "latest",
    "dotenv": "^16.0.0"
  }
}
```

Keep dependencies minimal. No YAML parser needed if you use regex for frontmatter. No search library needed — the wiki is small enough for a custom in-memory index.

## Key Technical Constraints

1. **stdout is reserved for MCP protocol** — use `console.error()` for all logging
2. **Windows paths** — use `path.join()` everywhere, never hardcode `/` or `\\`
3. **Encoding** — all wiki files are UTF-8
4. **No network** — everything is local file reads
5. **Startup speed** — loading ~70 MD files into memory should take < 1 second
6. **Memory** — wiki is ~1-2MB, index adds maybe 5MB — trivial for Node.js