@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/src-details/mcp-server.md

@@ -1,410 +1,170 @@
 # MCP Docs Server: Deep Dive
 
-This document provides a detailed look into the architecture, features, and internal workings of the IGNIS Documentation MCP Server. For a guide on how to use the server, see the [MCP Docs Server Quickstart](/guides/reference/mcp-docs-server).
+The IGNIS Documentation MCP server exposes the wiki, and the GitHub repository, as ten MCP tools. An AI assistant calls them to answer questions about IGNIS with real content, instead of guessing. For setup, see the [MCP Docs Server Quickstart](/guides/reference/mcp-docs-server).
 
----
+## Architecture
 
-## Architecture Overview
-
-### System Architecture
+Two tool groups sit behind one server. Documentation tools read local markdown files. Code tools call the GitHub API.
 
 ```mermaid
 graph TB
     AI[AI Assistant / MCP Client]
     MCP[MCPServer Entry Point]
-    
+
     subgraph ToolLayer [Tools Layer]
         DocsTools[Documentation Tools]
         CodeTools[Code & Project Tools]
     end
-    
+
     subgraph LogicLayer [Business Logic Layer]
-        DocsHelper[Docs Helper]
-        GitHubHelper[GitHub Helper]
+        DocsHelper[DocsHelper]
+        GitHubHelper[GithubHelper]
     end
-    
+
     subgraph DataLayer [Data Sources]
-        FS[File System / Wiki Docs]
+        FS[Local wiki markdown]
         GitHubAPI[GitHub API]
     end
 
     AI -->|MCP Protocol| MCP
     MCP --> DocsTools
     MCP --> CodeTools
-    
+
     DocsTools --> DocsHelper
     CodeTools --> GitHubHelper
-    
+
     DocsHelper --> FS
     GitHubHelper --> GitHubAPI
-
-    style AI fill:#e1f5ff
-    style MCP fill:#fff4e1
-    style DocsTools fill:#f0f0f0
-    style CodeTools fill:#f0f0f0
-    style DocsHelper fill:#e8f5e9
-    style GitHubHelper fill:#e8f5e9
-    style FS fill:#f3e5f5
-    style GitHubAPI fill:#e3f2fd
 ```
 
-### Component Responsibilities
-
-| Component | Responsibility | Key Features |
-|-----------|---------------|--------------|
-| **MCP Server** | Protocol handling, request routing | Stdio transport, tool registration |
-| **Docs Tools** | Wiki documentation access | Search, content retrieval, metadata |
-| **Code Tools** | Source code analysis | Code search, file listing, dependency check |
-| **DocsHelper** | Docs logic, search, caching | Fuse.js search, memory cache |
-| **GitHubHelper** | GitHub API integration | Repository search, content fetching |
-
----
+Documentation tools read files that ship with the server - your local checkout. Code tools fetch from GitHub at a chosen branch (`main` by default), not from your local working tree. A local edit you haven't pushed won't show up in `searchCode` or `viewSourceFile`.
 
-## Data Flow
+At startup, `main()` loads every wiki document into memory once, before the server starts accepting requests. `DocsHelper.load()` is idempotent - later calls return the cached list instead of re-reading disk.
 
-### Documentation Search Flow
-
-```mermaid
-sequenceDiagram
-    participant AI as AI Assistant
-    participant MCP as MCP Server
-    participant Tool as SearchDocsTool
-    participant Helper as DocsHelper
-    participant FS as File System
-
-    AI->>MCP: searchDocs("dependency injection")
-    MCP->>Tool: Route to tool handler
-    Tool->>Helper: DocsHelper.searchDocuments()
-
-    alt Cache Empty (First Call)
-        Helper->>FS: Load all .md files
-        FS-->>Helper: Raw markdown files
-        Helper->>Helper: Build Fuse.js index
-    end
-
-    Helper->>Helper: Query Fuse.js index
-    Helper-->>Tool: Search results
-    Tool-->>MCP: Formatted response
-    MCP-->>AI: JSON results
-```
-
-### Code Search Flow (GitHub)
-
-```mermaid
-sequenceDiagram
-    participant AI as AI Assistant
-    participant MCP as MCP Server
-    participant Tool as SearchCodeTool
-    participant Helper as GitHubHelper
-    participant API as GitHub API
-
-    AI->>MCP: searchCode("BaseRestController")
-    MCP->>Tool: Route to tool handler
-    Tool->>Helper: GitHubHelper.searchCode()
-    Helper->>API: GET /search/code
-    API-->>Helper: JSON results
-    Helper->>Helper: Process & Format
-    Helper-->>Tool: Code matches
-    Tool-->>MCP: Formatted response
-    MCP-->>AI: JSON results
-```
+## Tools reference
 
+### Documentation tools
 
-## Tools Reference
+Read the wiki. Backed by `DocsHelper`, which loads every `.md` file under `content/` and builds a [Fuse.js](https://www.fusejs.io/) search index over it.
 
-### 1. Documentation Tools
+| Tool | Input | Purpose |
+|------|-------|---------|
+| `searchDocs` | `{ query, limit? }` | Fuzzy search titles and content |
+| `getDocContent` | `{ id }` | Full markdown content of one document |
+| `listDocs` | `{ category? }` | List documents, optionally filtered by category |
+| `listCategories` | `{}` | List every category, alphabetically |
+| `getDocMetadata` | `{ id }` | Word count, character count, last-modified date |
+| `getPackageOverview` | `{ packageName? }` | Package summaries, sourced from `extensions/src-details/` |
 
-Tools for accessing the IGNIS Framework wiki and guide documentation.
+`id` is the document's path relative to the wiki root, for example `extensions/helpers/redis/index.md`. Get one from a `searchDocs` or `listDocs` result.
 
-| Tool | Purpose | Use Case |
-|------|---------|----------|
-| `searchDocs` | Find docs by keyword | "How do I use Redis?" |
-| `getDocContent` | Get full document content | "Show me the Redis guide" |
-| `listDocs` | Browse available docs | "What guides are available?" |
-| `listCategories` | List doc categories | "Show me doc topics" |
-| `getDocMetadata` | Get doc statistics | "Is this guide long?" |
-| `getPackageOverview` | Get package summaries | "What does the core package do?" |
+> [!NOTE]
+> `getPackageOverview` matches `extensions/src-details/{packageName}.md` exactly. Today that directory holds only this page (`mcp-server.md`). Until sibling pages exist, every other name - `core`, `helpers`, `inversion`, `dev-configs`, `docs` - returns a "not found" error.
 
-#### `searchDocs`
-Fuzzy searches across all documentation titles and content.
-- **Input:** `{ query: string, limit?: number }`
-- **Returns:** List of matching documents with snippets and relevance scores.
+### Code & project tools
 
-#### `getDocContent`
-Retrieves the full markdown content of a specific document.
-- **Input:** `{ id: string }`
-- **Returns:** Full document content.
+Explore the IGNIS repository on GitHub. Backed by `GithubHelper`, which reads via the GitHub REST API and `raw.githubusercontent.com`.
 
-#### `listDocs`
-Lists all documentation files, optionally filtered by category.
-- **Input:** `{ category?: string }`
-- **Returns:** List of document metadata (id, title, category).
+| Tool | Input | Purpose |
+|------|-------|---------|
+| `searchCode` | `{ query, limit? }` | GitHub code search across the repo |
+| `listProjectFiles` | `{ directoryPath? }` | List files and subdirectories at a path (default: repo root) |
+| `viewSourceFile` | `{ filePath }` | Full content of one source file |
+| `verifyDependencies` | `{ packagePath }` | Compare a package's `package.json` deps against the npm registry |
 
-#### `listCategories`
-Lists all unique documentation categories.
-- **Input:** `{}`
-- **Returns:** List of category names.
-
-#### `getDocMetadata`
-Retrieves statistics about a document without loading full content.
-- **Input:** `{ id: string }`
-- **Returns:** Word count, character count, last modified date.
-
-#### `getPackageOverview`
-Retrieves high-level information about specific framework packages.
-- **Input:** `{ packageName?: string }`
-- **Returns:** Package description, version, and purpose.
-
-
-### 2. Code & Project Tools
-
-Tools for exploring the IGNIS codebase, searching source code, and verifying dependencies via GitHub.
-
-| Tool | Purpose | Use Case |
-|------|---------|----------|
-| `searchCode` | Search source code | "Find usages of BaseRestController" |
-| `listProjectFiles` | List repo files | "Show me files in packages/core" |
-| `viewSourceFile` | Read source code | "Read packages/core/src/index.ts" |
-| `verifyDependencies` | Check package.json | "Check dependencies for @venizia/core" |
-
-#### `searchCode`
-Searches the codebase using GitHub's code search API.
-- **Input:** `{ query: string, limit?: number, extension?: string }`
-- **Returns:** List of code matches with file paths and snippets.
-
-#### `listProjectFiles`
-Lists files and directories in the repository.
-- **Input:** `{ path?: string, recursive?: boolean }`
-- **Returns:** File tree structure.
-
-#### `viewSourceFile`
-Retrieves the raw content of a source code file.
-- **Input:** `{ path: string }`
-- **Returns:** Raw file content.
-
-#### `verifyDependencies`
-Checks the `package.json` of a specific package or the root project.
-- **Input:** `{ package?: string }`
-- **Returns:** List of dependencies and their versions.
+`searchCode` uses GitHub's native query syntax. Qualifiers like `extension:ts` or `path:packages/core-server` go inside the `query` string itself - there is no separate `extension` parameter.
 
+Every tool returns an `error` string field on failure, instead of throwing. Check for it before trusting the rest of the response.
 
 ## Resources
 
-The server exposes documentation as MCP resources for direct access:
+The server also exposes each document as an MCP resource, for clients that read resources directly instead of calling `searchDocs`.
 
 | Property | Value |
 |----------|-------|
-| **URI Format** | `ignis://docs/{document-id}` |
-| **MIME Type** | `text/markdown` |
-| **Metadata** | Category and word count in description |
-
-**Example Resource:**
-
-```json
-{
-  "uri": "ignis://docs/guides/intro.md",
-  "name": "Introduction",
-  "description": "Getting Started - 450 words",
-  "mimeType": "text/markdown"
-}
-```
-
+| URI format | `ignis://docs/{document-id}` |
+| MIME type | `text/markdown` |
+| Description | `{category} - {wordCount} words` |
 
-## Search Configuration
+## Search configuration
 
-### Fuse.js Settings
+`searchDocs` and `searchCode` are tuned independently.
 
-The search engine uses optimized Fuse.js configuration:
-
-| Setting | Value | Explanation |
-|---------|-------|-------------|
-| **threshold** | 0.4 | Balance between strict and fuzzy matching |
-| **ignoreLocation** | true | Match anywhere in document, not just at start |
-| **findAllMatches** | true | Return all relevant matches, not just first |
-| **minMatchCharLength** | 2 | Minimum characters to trigger a match |
-
-### Search Weights
-
-```mermaid
-pie
-    title Search Weight Distribution
-    "Title" : 70
-    "Content" : 30
-```
+| Setting | Docs (`searchDocs`) | Code (`searchCode`) |
+|---|---|---|
+| Default result limit | 10 | 10 |
+| Max result limit | 50 | 30 |
+| Minimum query length | 2 chars | 2 chars |
 
-| Field | Weight | Rationale |
-|-------|--------|-----------|
-| Title | 70% | Document titles are highly relevant |
-| Content | 30% | Body content provides context |
+`searchDocs` also ranks by a weighted Fuse.js index:
 
-**Why this matters:** When you search for "dependency injection", documents with that phrase in the title will rank higher than those with it only in the content.
+| Field | Weight |
+|---|---|
+| Title | 70% |
+| Content | 30% |
 
+`threshold: 0.4` tolerates typos and partial matches, without matching everything.
 
-## Project Structure
+## Project structure
 
 ```
 mcp-server/
 ├── common/
-│   ├── config.ts           # Configuration constants (MCPConfigs class)
-│   ├── logger.ts           # Logging infrastructure
-│   ├── paths.ts            # Path resolution
-│   └── index.ts            # Common exports
+│   ├── config.ts           # MCPConfigs - server, GitHub, search settings
+│   ├── guards.ts           # isNonEmptyString - truthiness check for external data
+│   ├── paths.ts            # Paths - wiki directory resolution
+│   └── index.ts
 ├── helpers/
-│   ├── docs.helper.ts      # Documentation loading and searching
-│   ├── github.helper.ts    # GitHub API integration
-│   ├── logger.helper.ts    # Logging utilities
-│   └── index.ts            # Helper exports
-├── tools/
-│   ├── base.tool.ts        # Abstract base class for tools
-│   ├── docs/               # Documentation tools
-│   │   ├── get-document-content.tool.ts
-│   │   ├── get-document-metadata.tool.ts
-│   │   ├── get-package-overview.tool.ts
-│   │   ├── list-categories.tool.ts
-│   │   ├── list-documents.tool.ts
-│   │   ├── search-documents.tool.ts
-│   │   └── index.ts
-│   ├── github/             # GitHub/Code tools
-│   │   ├── list-project-files.tool.ts
-│   │   ├── search-code.tool.ts
-│   │   ├── verify-dependencies.tool.ts
-│   │   ├── view-source-file.tool.ts
-│   │   └── index.ts
+│   ├── docs.helper.ts      # DocsHelper - load, search, cache
+│   ├── github.helper.ts    # GithubHelper - GitHub API + raw content
+│   ├── logger.helper.ts    # Logger - console logging
 │   └── index.ts
-├── index.ts                # Server entry point
+├── tools/
+│   ├── base.tool.ts        # BaseTool - abstract base every tool extends
+│   ├── docs/                # 6 documentation tools
+│   └── github/               # 4 code/project tools
+├── index.ts                # Server entry point, tool registration, main()
 └── README.md
 ```
 
-### File Responsibilities
-
-| File | Purpose | Key Exports |
-|------|---------|-------------|
-| `index.ts` | Server initialization, tool registration | `main()`, `mcpServer` |
-| `tools/base.tool.ts` | Abstract tool class, singleton pattern | `BaseTool`, `createTool` |
-| `helpers/docs.helper.ts` | Documentation loading, search, cache | `DocsHelper` class |
-| `helpers/github.helper.ts` | GitHub API integration | `GithubHelper` class |
-| `common/config.ts` | Centralized configuration | `MCPConfigs` class |
-| `common/logger.ts` | Structured logging | `Logger` class |
-| `common/paths.ts` | Path resolution | `Paths` object |
-
-
-## Performance Characteristics
-
-### Caching Strategy
-
-```mermaid
-graph LR
-    A[First Request] --> B{Cache Empty?}
-    B -->|Yes| C[Load from FS]
-    C --> D[Parse Frontmatter]
-    D --> E[Build Fuse Index]
-    E --> F[Store in Memory]
-    F --> G[Return Results]
-    B -->|No| G
-
-    style C fill:#ffcdd2
-    style F fill:#c8e6c9
-    style G fill:#bbdefb
-```
-
-### Performance Metrics
-
-| Operation | First Call | Subsequent Calls | Notes |
-|-----------|-----------|------------------|-------|
-| **Load Docs** | ~50-200ms | 0ms | Cached in memory |
-| **Search** | ~100-300ms | ~5-20ms | Includes initial load |
-| **Get Content** | ~50-200ms | ~1-5ms | Fast lookup by ID |
-| **List Docs** | ~50-200ms | ~1-3ms | Pre-cached metadata |
-| **Memory Usage** | ~5-10MB | ~5-10MB | Scales with doc count |
-
-**Optimization Tips:**
+`common/guards.ts` exists because everything this server reads is external and untyped - frontmatter, GitHub error bodies, npm registry responses. A key can be present but empty, which needs the same fallback as a missing key. `isNonEmptyString` makes that a deliberate truthiness check, not `??`.
 
-- First search is slower (loads all docs)
-- Subsequent searches are cached (very fast)
-- Memory usage is constant after first load
-- No disk I/O after initialization
+## Configuration
 
+`MCPConfigs`, in `common/config.ts`, is a static class - not a config file. Change the constants, and rebuild.
 
-## Error Handling
+| Field | Default | Notes |
+|---|---|---|
+| `server.name` | `'ignis-docs'` | Reported to MCP clients |
+| `github.branch` | `'main'` | Set at runtime via the CLI arg: `ignis-docs-mcp <branch>` |
+| `github.repoOwner` / `repoName` | `VENIZIA-AI` / `ignis` | The repository code tools read from |
+| `search.snippetLength` | `320` | Max characters in a `searchDocs` snippet |
+| `fuse.threshold` | `0.4` | `0.0` = exact match only, `1.0` = match anything |
 
-### Error Response Format
-
-All tools return consistent error responses:
-
-```json
-{
-  "error": "Document not found",
-  "id": "requested-id"
-}
-```
+## Error handling
 
-### Common Errors
+A tool never throws to the MCP client. Each `execute()` catches its own failures and returns `{ error: string, ...partial fields }`, matching that tool's output schema. `searchCode` also returns `rateLimitWarning` when GitHub's rate limit is running low - unauthenticated requests are capped at 10 per minute.
 
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Document not found" | Invalid document ID | Use `listDocs` to find valid IDs |
-| "Query too short" | Query < 2 characters | Use longer search query |
-| "Limit out of range" | Limit > 50 or < 1 | Use default (10) or valid range |
-| "Failed to load documentation" | File system error | Check wiki directory exists |
-
-### Logging Levels
-
-| Level | Usage | Example |
-|-------|-------|---------|
-| **info** | General information | "Server started", "Docs loaded" |
-| **warn** | Non-critical issues | "Document not found" |
-| **error** | Critical errors | "Failed to load docs" |
-| **debug** | Development details | Search queries, cache hits |
+## Debugging
 
-**Enable debug logging:**
+Set `DEBUG=1` to see `Logger.debug()` output - cache loads, search queries, and GitHub request URLs.
 
 ```bash
 DEBUG=1 ignis-docs-mcp
 ```
 
+## Extending the server
 
-## Development Guide
-
-### Tool Architecture Pattern
-
-All tools extend the `BaseTool` abstract class:
-
-```typescript
-import type { Tool } from '@mastra/core/tools';
-import type { z } from 'zod';
-
-export abstract class BaseTool<TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType> {
-  abstract readonly id: string;
-  abstract readonly description: string;
-  abstract readonly inputSchema: TInputSchema;
-  abstract readonly outputSchema: TOutputSchema;
-
-  abstract execute(opts: z.infer<TInputSchema>): Promise<z.infer<TOutputSchema>>;
-  abstract getTool(): Tool<z.input<TInputSchema>, z.infer<TOutputSchema>>;
-}
-```
-
-### Adding a New Tool
-
-**Step 1: Create Tool File**
-
-Create `tools/my-new-tool.tool.ts`:
+Every tool extends `BaseTool<TInputSchema, TOutputSchema>` and implements `id`, `description`, `inputSchema`, `outputSchema`, `execute()`, and `getTool()`.
 
 ```typescript
 import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 import { BaseTool } from '../base.tool';
 
-// Define schemas
-const InputSchema = z.object({
-  param: z.string().describe('Parameter description'),
-});
-
-const OutputSchema = z.object({
-  result: z.string().describe('Result description'),
-});
+const InputSchema = z.object({ param: z.string().describe('Parameter description') });
+const OutputSchema = z.object({ result: z.string().describe('Result description') });
 
-// Implement tool class
 export class MyNewTool extends BaseTool<typeof InputSchema, typeof OutputSchema> {
   readonly id = 'myNewTool';
   readonly description = 'What this tool does';
@@ -412,7 +172,6 @@ export class MyNewTool extends BaseTool<typeof InputSchema, typeof OutputSchema>
   readonly outputSchema = OutputSchema;
 
   async execute(opts: z.infer<typeof InputSchema>) {
-    // Your logic here
     return { result: 'output' };
   }
 
@@ -428,232 +187,21 @@ export class MyNewTool extends BaseTool<typeof InputSchema, typeof OutputSchema>
 }
 ```
 
-**Step 2: Export from Index**
-
-Add to `tools/index.ts`:
-
-```typescript
-export { MyNewTool } from './my-new-tool.tool';
-```
-
-**Step 3: Register in Server**
-
-Add to `index.ts`:
-
-```typescript
-import { MyNewTool } from './tools';
-
-const mcpServer = new MCPServer({
-  tools: {
-    myNewTool: new MyNewTool().getTool(),
-    // ... other tools
-  },
-});
-```
-
-### Configuration Updates
-
-Modify `common/config.ts` to adjust global settings. The configuration is now a class with static properties:
+Export the class from `tools/index.ts`, then register it in `index.ts`:
 
 ```typescript
-export class MCPConfigs {
-  // Server identification
-  static readonly server = { name: 'ignis-docs', version: '0.0.1' } as const;
-
-  // GitHub configuration (branch is runtime-configurable)
-  static readonly github = {
-    apiBase: 'https://api.github.com',
-    rawContentBase: 'https://raw.githubusercontent.com',
-    repoOwner: 'VENIZIA-AI',
-    repoName: 'ignis',
-    get branch(): string { return MCPConfigs._branch; },
-  };
-
-  // Set branch at runtime via CLI argument
-  static setBranch(opts: { branch: string }) {
-    MCPConfigs._branch = opts.branch;
-  }
-
-  // Documentation search settings
-  static readonly search = {
-    snippetLength: 320,   // Max characters for content snippet
-    defaultLimit: 10,     // Default results per search
-    maxLimit: 50,         // Maximum allowed results
-    minQueryLength: 2,    // Minimum query length
-  };
-
-  // Code search settings (GitHub API)
-  static readonly codeSearch = {
-    defaultLimit: 10,
-    maxLimit: 30,         // GitHub API limit
-    minQueryLength: 2,
-  };
-
-  // Fuse.js search engine settings
-  static readonly fuse = {
-    includeScore: true,
-    threshold: 0.4,       // 0.0 = exact, 1.0 = match anything
-    minMatchCharLength: 2,
-    findAllMatches: true,
-    ignoreLocation: true,
-    keys: [
-      { name: 'title', weight: 0.7 },
-      { name: 'content', weight: 0.3 },
-    ],
-  };
-}
-```
-
-**Configuration Impact:**
-
-| Setting | Low Value | High Value |
-|---------|-----------|------------|
-| `threshold` | Stricter matches | More fuzzy matches |
-| `title weight` | Less title importance | More title importance |
-| `snippetLength` | Shorter previews | Longer previews |
-
-
-## Best Practices
-
-### For AI Assistants
-
-1. **Search First**: Use `searchDocs` to find relevant documentation before fetching full content
-2. **Filter Smart**: Use `listCategories` → `listDocs(category)` for category-specific browsing
-3. **Check Size**: Use `getDocMetadata` before `getDocContent` for large documents
-4. **Batch Queries**: If you need multiple docs, fetch IDs first then retrieve content
-5. **Handle Errors**: Always check for error field in responses
-
-### For Developers
-
-1. **Document IDs**: Always use relative paths from wiki root (e.g., "guides/intro.md")
-2. **Frontmatter**: Ensure all markdown files have `title` and `category` in frontmatter
-3. **Search Queries**: Use descriptive queries for better results (minimum 2 characters)
-4. **Result Limits**: Adjust limit parameter based on needs (default: 10, max: 50)
-5. **Logging**: Enable DEBUG mode during development for detailed logs
-
-### Workflow Examples
-
-**Example 1: Answer "How do I use Redis?"**
-
-```
-1. searchDocs("Redis") → Find relevant docs
-2. Review snippets → Identify best match (e.g., "helpers/redis.md")
-3. getDocContent("helpers/redis.md") → Retrieve full guide
-4. Extract and format answer for user
-```
-
-**Example 2: Browse helpers documentation**
-
-```
-1. listCategories() → Get all categories
-2. listDocs({ category: "Helpers" }) → Get all helper docs
-3. Present list to user → Let them choose
-4. getDocContent(selectedId) → Show full documentation
-```
-
-**Example 3: Check document before reading**
-
-```
-1. getDocMetadata("references/api.md") → Check length
-2. If wordCount > 5000 → Warn user it's long
-3. getDocContent("references/api.md") → Fetch full content
-```
-
-
-## Debugging
-
-### Enable Debug Mode
-
-```bash
-# Show all debug logs
-DEBUG=1 ignis-docs-mcp
-
-# Show specific component logs
-DEBUG=docs:search ignis-docs-mcp
-DEBUG=docs:cache ignis-docs-mcp
-```
-
-### Debug Output Examples
-
-```
-[debug] Loading documentation from: /path/to/wiki
-[debug] Found 45 markdown files
-[debug] Building Fuse.js search index
-[debug] Cache populated with 45 documents
-[debug] Search query: "dependency injection"
-[debug] Found 3 matches in 12ms
-```
-
-### Common Debug Tasks
-
-| Task | Command | Expected Output |
-|------|---------|----------------|
-| Verify docs load | `DEBUG=1 ignis-docs-mcp` | "Cache populated with N documents" |
-| Check search | Use searchDocs tool | "Found N matches in Xms" |
-| Inspect cache | Check memory usage | ~5-10MB after first load |
-
-
-## Roadmap
-
-### Planned Features
-
-- [ ] **Prompts Support** - When @mastra/mcp library adds support
-- [ ] **Incremental Search** - Real-time search as user types
-- [ ] **Semantic Search** - AI-powered semantic matching
-- [ ] **Document Versioning** - Track documentation changes
-- [ ] **Multi-language Support** - i18n documentation support
-
-### Contributing
-
-Want to add features or fix bugs? See the main IGNIS repository:
-
-- **Repository**: https://github.com/venizia-ai/ignis
-- **Issues**: Report bugs or request features
-- **Pull Requests**: Submit improvements
-
-
-## FAQ
-
-### How does caching work?
-
-Documentation is loaded into memory on the first request and stays cached for the lifetime of the server process. This means:
-- First search: ~100-300ms (loads all docs)
-- Subsequent searches: ~5-20ms (cached)
-- Memory usage: ~5-10MB (constant)
-
-### Can I use this with other frameworks?
-
-Yes! The MCP server architecture is framework-agnostic. You can fork this repo and adapt it to serve documentation for any project by:
-1. Replacing the wiki directory
-2. Updating the server name/version
-3. Adjusting configuration as needed
-
-### How do I update the documentation?
-
-If you installed via npm:
-```bash
-npm update -g @venizia/ignis-docs
-```
-
-The package includes bundled documentation that updates with each release.
-
-### What if a document isn't found?
-
-The tool returns an error object:
-```json
-{
-  "error": "Document not found",
-  "id": "invalid-id"
-}
+const mcpTools = {
+  // ...existing tools
+  myNewTool: new MyNewTool().getTool(),
+};
 ```
 
-Use `listDocs()` to get valid document IDs.
+> [!NOTE]
+> The key you register the tool under - `myNewTool` here - is the name MCP clients see, not `this.id`. `MCPServer` overwrites the tool's `id` with its object key at registration time, so keep them identical to avoid confusing yourself later.
 
-### How accurate is the fuzzy search?
+## See also
 
-The search uses a threshold of 0.4, which balances between strict and fuzzy matching:
-- Exact matches: Always ranked first
-- Close matches: Tolerate 1-2 character typos
-- Partial matches: Find substrings anywhere in title/content
+- [MCP Docs Server Quickstart](/guides/reference/mcp-docs-server) - install and connect a client
+- [Helpers Overview](/extensions/helpers/) - a directory `searchDocs` and `listDocs` can browse
 
-Adjust `MCPConfigs.fuse.threshold` to make it stricter (lower) or fuzzier (higher).
+**Files:** [`docs/wiki/mcp-server`](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/mcp-server)