màj wiki avec retour MES lot-5 AD

2026-05-20 09:41:27 +02:00
commit 23eb3f3c84
4106 changed files with 469381 additions and 0 deletions
@@ -0,0 +1,323 @@
+# 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