MCPedia

# MCPedia **Local codebase RAG + MCP server for your repositories.** MCPedia turns a local repository into a searchable knowledge base. It indexes source code and documentation into a local LanceDB store, retrieves with hybrid search, answers questions through local or cloud LLMs, and exposes the same repository knowledge as an MCP server for VS Code, Claude Code, MCP Inspector, and other MCP clients. The name **MCPedia** means **MCP + Encyclopedia**: a local, repository-scoped encyclopedia that AI assistants can query through the Model Context Protocol. --- ## Features - **Local repository index** stored under `.rag/store.lance`. - **Syntax-aware code chunks** with Tree-sitter for supported languages. - **Recursive token-aware splitting** for Markdown, prose, extracted PDF/Office text, unsupported files, and oversized code sections. - **PDF and Office/OpenDocument ingestion** for `.pdf`, `.docx`, `.pptx`, `.xlsx`, `.odt`, `.ods`, `.odp`, and `.rtf` files, with optional LibreOffice-powered fallback for legacy `.doc`, `.ppt`, and `.xls`. - **Hybrid retrieval** with vector search, full-text search, and reciprocal-rank reranking. - **Official AI SDKs** for Ollama, OpenAI, Anthropic, and Gemini where supported. - **MCP stdio server** with unique repository-specific tool names for clean traces. - **Multiple local MCPedia servers** on one machine, one per repository. - **Windows diagnostics and repair** for known Tree-sitter native-binding issues. MCPedia is not a cloud service. The index is local. Cloud providers are contacted only when you configure them for embeddings or answers. --- ## Requirements - Node.js **22 or newer** - npm - Ollama for the default fully local setup - Windows users: latest **Microsoft Visual C++ v14 Redistributable x64** for native Tree-sitter parsing Default local models: ```powershell ollama pull qwen3-embedding:8b ollama pull gemma4:12b ``` MCPedia works out of the box with **Ollama**. Install Ollama first, start it, and pull the two models above before running `mcpedia index` or `mcpedia ask` with the default configuration. OpenAI, Anthropic, and Gemini are optional alternatives you can enable later in `.rag/config.yaml`. `qwen3-embedding:8b` is accuracy-oriented and can be heavy. --- ## Install from npm After publishing, users should install MCPedia globally: ```powershell npm install -g mcpedia mcpedia --version ``` Update later: ```powershell npm update -g mcpedia ``` Uninstall: ```powershell npm uninstall -g mcpedia ``` --- ## Quick start First make sure Ollama is installed and the default models are available: ```powershell ollama pull qwen3-embedding:8b ollama pull gemma4:12b ``` Then index the repository you want to use as a knowledge base: ```powershell cd C:\Projects\MyKnowledgeBase mcpedia init mcpedia index mcpedia search "where is validation implemented?" mcpedia ask "explain the authentication flow" ``` Start the MCP server for the current repository: ```powershell mcpedia mcp ``` That command appears to wait. This is expected: an MCP client communicates with it over stdin/stdout. --- ## Project layout After `mcpedia init`: ```text MyKnowledgeBase/ ├── .rag/ │ ├── config.yaml # Per-project configuration │ └── store.lance/ # Local LanceDB index after mcpedia index └── ...your source files ``` Each repository owns its own `.rag` directory. This keeps indexes, provider settings, and MCP identity separate across many local projects. Do not commit `.rag/`. Recommended `.gitignore` entry: ```gitignore .rag/ ``` --- ## Which command should I use? | Task | Command | |---|---| | Create `.rag/config.yaml` | `mcpedia init` | | Diagnose Windows Tree-sitter/native issues | `mcpedia doctor` | | List, detect, or pre-download grammars | `mcpedia grammars` | | Build or rebuild the local index | `mcpedia index` | | Print the live repository tree | `mcpedia tree` | | Search indexed code/docs | `mcpedia search` | | Ask an LLM using retrieved context | `mcpedia ask` | | Start an MCP server | `mcpedia mcp` from the project folder, or `mcpedia mcp <path>` in client configs | Use verbose mode when diagnosing discovery, chunking, embeddings, or provider calls: ```powershell mcpedia --verbose index ``` --- ## Command reference ### `mcpedia init` **Why this command exists:** creates the per-project `.rag/config.yaml` file. MCPedia stores repository settings inside the repository, not globally. ```powershell mcpedia init ``` Notes: - Does not overwrite an existing config. - Generates one complete YAML file with all public options visible. - Edit `mcp.name`, `mcp.title`, `mcp.description`, and `mcp.instructions` before registering multiple MCP servers. Regenerate safely: ```powershell Copy-Item .rag\config.yaml .rag\config.backup.yaml Remove-Item .rag\config.yaml mcpedia init ``` --- ### `mcpedia doctor` **Why this command exists:** diagnoses and repairs Windows x64 Tree-sitter native-binding issues. ```powershell mcpedia doctor --check-only mcpedia doctor ``` Options: | Option | Meaning | |---|---| | `--check-only` | Inspect without modifying files | On affected Windows packages, `doctor` checks whether the Tree-sitter language-pack binary imports `node.dll` instead of `node.exe`. If needed, it creates a backup, patches only that exact PE import, validates in a fresh Node child process, and restores the original file if validation fails. Disable automatic native repair: ```powershell $env:MCPEDIA_DISABLE_NATIVE_REPAIR = "1" ``` --- ### `mcpedia grammars` **Why this command exists:** manages Tree-sitter grammars used for code-aware chunking. ```powershell mcpedia grammars --detect src\Program.cs mcpedia grammars csharp typescript python mcpedia grammars --list mcpedia grammars --all ``` Options: | Option | Meaning | |---|---| | `--detect <path>` | Show the canonical grammar for a file path | | `--list` | List canonical grammar names from the language pack | | `--all` | Download/verify the full grammar bundle | Examples: ```powershell mcpedia grammars --detect C:\Projects\MyKnowledgeBase\src\Application\Service.cs mcpedia grammars csharp ``` Expected detection: ```text C:\Projects\MyKnowledgeBase\src\Application\Service.cs: csharp ``` --- ### `mcpedia index` **Why this command exists:** builds or rebuilds the local searchable index. ```powershell mcpedia index mcpedia --verbose index ``` Pipeline: 1. discover files using `files.include`, `files.exclude`, and `.gitignore` rules; 2. skip binary, oversized, generated, secret, and low-signal files; 3. chunk source code structurally with Tree-sitter when possible; 4. fall back to recursive token-aware splitting when needed; 5. embed chunks with the configured embedding provider; 6. write chunks and vectors into LanceDB; 7. build full-text/vector indexes for hybrid search. Changing these settings requires a rebuild: - embedding provider/model/dimension; - file include/exclude rules; - chunk size or overlap; - language overrides; - store path or table name. Rebuild explicitly: ```powershell Remove-Item .rag\store.lance -Recurse -Force -ErrorAction SilentlyContinue mcpedia index ``` --- ### `mcpedia tree` **Why this command exists:** prints the live repository tree using the same discovery rules as indexing. It does not require an index. ```powershell mcpedia tree mcpedia tree src mcpedia tree src --max-depth 3 mcpedia tree "C:\Projects\MyKnowledgeBase\src" --max-depth 4 --absolute-paths ``` Options: | Option | Meaning | |---|---| | `<folderPath>` | Optional project-relative or absolute path inside the project | | `--max-depth <n>` | Optional depth limit; omitted means unlimited | | `--absolute-paths` | Print absolute paths for every entry | Tree output begins with the resolved locations, for example: ```text Project root: C:\Projects\MyKnowledgeBase Tree path: C:\Projects\MyKnowledgeBase\src ``` Absolute paths outside the project root are rejected to avoid exposing unrelated files. --- ### `mcpedia search` **Why this command exists:** retrieves relevant indexed chunks without calling an answer model. ```powershell mcpedia search "authentication middleware" mcpedia search "where is tenant validation?" --top-k 12 ``` Options: | Option | Meaning | |---|---| | `--top-k <n>` | Number of final results | Use `search` when you want citations, file paths, and source snippets without generation cost. --- ### `mcpedia ask` **Why this command exists:** retrieves context, sends it to the configured LLM, and prints a grounded answer with sources. ```powershell mcpedia ask "How does user authentication work?" ``` `ask` uses: - `embedding.*` for retrieval; - `llm.*` for answer generation. If you only need source snippets, use `mcpedia search` instead. --- ### `mcpedia mcp` **Why this command exists:** starts a stdio MCP server for one indexed repository. MCP clients launch this command and communicate with it over stdin/stdout. ```powershell # Use the current directory as the project root. mcpedia mcp # Recommended for VS Code, Claude Code, and multi-server configs: bind the server explicitly. # For MCP Inspector, prefer opening PowerShell inside the project and running plain `mcpedia mcp`. mcpedia mcp C:\Projects\MyKnowledgeBase # Equivalent terminal form. mcpedia mcp --root C:\Projects\MyKnowledgeBase ``` Arguments and options: | Form | Meaning | |---|---| | `mcpedia mcp` | Serve the current working directory. Good for quick local testing. | | `mcpedia mcp <path>` | Serve the project at `<path>`. Recommended in MCP client configs. | | `mcpedia mcp --root <path>` | Equivalent explicit flag. Useful in a normal terminal, but some launchers handle nested `--flags` less reliably. | Environment alternative: ```powershell $env:MCPEDIA_ROOT = "C:\Projects\MyKnowledgeBase" mcpedia mcp ``` Why the project path matters: if two MCPedia servers are registered as only `mcpedia mcp`, both can start from the same client working directory and appear to serve the same project. Give every MCPedia registration one explicit project path. Running this command manually is useful only to confirm that it stays alive. Stop it with `Ctrl+C`. --- ## Configuration essentials `mcpedia init` writes one complete config: ```text .rag/config.yaml ``` YAML values take priority. When `apiKey` or `baseUrl` is `null`, MCPedia checks environment variables and then provider defaults. ### API keys ```yaml embedding: provider: openai apiKey: null # null reads OPENAI_API_KEY llm: provider: anthropic apiKey: null # null reads ANTHROPIC_API_KEY ``` Inline keys also work, but should not be committed: ```yaml embedding: apiKey: "sk-your-key" ``` Supported variables: | Provider | API key | Base URL | |---|---|---| | Ollama | `OLLAMA_API_KEY` | `OLLAMA_HOST` | | OpenAI | `OPENAI_API_KEY` | `OPENAI_BASE_URL` | | Anthropic | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` | | Gemini | `GEMINI_API_KEY`, then `GOOGLE_API_KEY` | `GEMINI_BASE_URL` | ### Embeddings Default accuracy-first local setup: ```yaml embedding: provider: ollama model: qwen3-embedding:8b dimension: 4096 baseUrl: http://localhost:11434 apiKey: null batchSize: 8 timeoutMs: 180000 maxRetries: 3 ``` Lower-resource alternatives: ```yaml # Balanced model: qwen3-embedding:4b dimension: 2560 batchSize: 8 ``` ```yaml # Lightweight model: qwen3-embedding:0.6b dimension: 1024 batchSize: 16 ``` Changing the embedding model or dimension requires `mcpedia index`. ### LLM answers Default local answer model: ```yaml llm: provider: ollama model: gemma4:12b maxTokens: 8192 temperature: 0.2 timeoutMs: 120000 maxRetries: 3 ``` Cloud examples: ```yaml llm: provider: anthropic model: claude-sonnet-4-20250514 apiKey: null ``` ```yaml llm: provider: openai model: gpt-4.1 apiKey: null ``` ### File discovery ```yaml files: include: - "**/*" exclude: - "**/node_modules/**" - "**/dist/**" - "**/.gitignore" - "**/package-lock.json" - "**/.env" extensions: [] respectGitignore: true followSymlinks: false maxFileSizeBytes: 1000000 documentMaxFileSizeBytes: 50000000 ``` `extensions: []` indexes all detected text files plus supported document files. Supported document formats are extracted to plain text before chunking: `.pdf`, `.docx`, `.docm`, `.dotx`, `.dotm`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm`, `.potx`, `.potm`, `.xlsx`, `.xlsm`, `.xltx`, `.xltm`, `.odt`, `.ott`, `.ods`, `.ots`, `.odp`, `.otp`, and `.rtf`. Legacy binary Office files `.doc`, `.ppt`, and `.xls` are also detected and are extracted when LibreOffice or `soffice` is installed and available on `PATH`. Supported document files are still discovered when `files.extensions` contains a code/text allow-list, so an existing config like `[".cs", ".md"]` will not accidentally hide PowerPoint files. Use `files.exclude` to opt out of document folders or file patterns. ```yaml files: extensions: [".cs", ".csproj", ".md", ".json"] maxFileSizeBytes: 1000000 documentMaxFileSizeBytes: 50000000 ``` Why MCPedia excludes metadata and generated files by default: - `.gitignore`, lockfiles, build output, logs, source maps, and local secrets are usually low-signal for code understanding; - excluding them reduces embedding cost, index size, and noisy results; - `.env.example remains indexable` because it is often useful documentation; - PDF and Office files use `documentMaxFileSizeBytes`, so common multi-megabyte decks and manuals are not skipped by the smaller source-code size limit; - The `.gitignore` file itself is not embedded, but its rules are still applied when `respectGitignore: true`; - Every exclusion is visible in `.rag/config.yaml` and is removable. ### Chunking ```yaml chunking: chunkSize: 2024 chunkOverlap: 256 encoding: o200k_base codeAware: true separators: [] languageOverrides: {} ``` `separators: []` uses MCPedia's built-in semantic separator order. To customize, replace it with your own list: ```yaml chunking: separators: - "\n## " - "\n### " - "\n\n" - "\n" - ". " - " " - "" # individual characters as the final fallback ``` Language override example: ```yaml chunking: languageOverrides: ".foo": typescript "SpecialFile": python "src/generated/Legacy.cs": text ``` Use `text` to force recursive text splitting for one file or pattern. ### Search ```yaml search: topK: 8 overfetch: 4 createVectorIndexThreshold: 256 ``` Candidate count before reranking: ```text topK × overfetch ``` ### MCP identity Use meaningful names for every repository so traces clearly show which knowledge base was used: ```yaml mcp: name: my-knowledge-base title: MyKnowledgeBase description: Search and inspect this project's indexed code and documentation. instructions: Use this server only for questions about this project. Keep these results separate from other connected project servers. namespaceTools: true toolNamePrefix: auto tools: search: true tree: true maxResults: 10 ``` With namespacing enabled, tools appear as: ```text my_knowledge_base_search my_knowledge_base_tree ``` --- ## How splitting works ### Tree-sitter structural strategy For supported code files, MCPedia prefers syntax-aware chunks instead of arbitrary text cuts. Process: 1. Detect the language from the language-pack catalog. 2. Parse the file with Tree-sitter. 3. Walk named syntax nodes such as classes, methods, functions, imports, and declarations. 4. Measure each node with the configured tokenizer. 5. Pack adjacent sibling nodes together while staying under `chunkSize`. 6. Recurse into oversized nodes, such as a very large class. 7. Use recursive text splitting only for oversized leaves that cannot be split structurally. 8. Store file path, line range, language, strategy, and best-effort symbol name. This keeps functions, classes, and declarations together, which usually improves retrieval quality and trace readability. ### Recursive token-aware text strategy MCPedia uses this strategy for Markdown, prose, unsupported languages, parser failures, and oversized syntax leaves. Process: 1. Count tokens with Tiktoken. 2. Choose the first useful separator from the configured list. 3. Split the text by that separator. 4. Recurse only into pieces that are still too large. 5. Continue with finer separators such as headings, paragraphs, lines, punctuation, words, and finally individual characters as the final fallback. 6. Greedily merge small pieces until each chunk approaches `chunkSize`. 7. Carry overlap forward by keeping complete previous pieces up to roughly `chunkOverlap` tokens. 8. Remove empty chunks. Important details: - Overlap is approximate because MCPedia preserves meaningful pieces rather than cutting exact token windows. - A custom `separators` list replaces the built-in list. - Larger chunks improve broad context but may reduce pinpoint retrieval. - Smaller chunks improve precision but can split important context. --- ## Multiple MCP servers on one system MCPedia is designed for many local knowledge-base servers on the same machine. A good setup has **one MCPedia server per repository**. Each repository should have its own: ```text .rag/config.yaml .rag/store.lance ``` Example repositories: ```text C:\Projects\MyKnowledgeBase C:\Projects\BillingApi C:\Projects\ProductDocs ``` Each repository should also have a unique MCP identity in its own `.rag/config.yaml`: ```yaml mcp: name: my-knowledge-base title: MyKnowledgeBase description: Search and inspect this project's indexed code and documentation. instructions: Use this server only for questions about this project. namespaceTools: true toolNamePrefix: auto ``` With `namespaceTools: true`, traces and MCP UIs show project-specific tool names: ```text my_knowledge_base_search my_knowledge_base_tree ``` For another repository: ```yaml mcp: name: billing-api-knowledge title: Billing API Knowledge namespaceTools: true toolNamePrefix: auto ``` The tools become: ```text billing_api_knowledge_search billing_api_knowledge_tree ``` This makes it much easier to see which knowledge base the AI called. --- ## When to pass a project root `mcpedia mcp` must know which repository contains `.rag/config.yaml` and `.rag/store.lance`. MCPedia chooses the project root in this order: 1. Positional root: `mcpedia mcp C:\Projects\MyKnowledgeBase`. 2. Option root: `mcpedia mcp --root C:\Projects\MyKnowledgeBase`. 3. Environment variable: `MCPEDIA_ROOT`. 4. Current working directory. Recommended rule: ```text One MCPedia server = one unique client registration name + one explicit project root + one unique mcp.name. ``` ### Use an explicit root for multi-MCP setups Use a project path whenever one client registers more than one MCPedia server: ```powershell mcpedia mcp C:\Projects\MyKnowledgeBase mcpedia mcp C:\Projects\BillingApi ``` The positional root form is recommended for MCP client configs because it avoids nested command-line flag parsing problems in tools that already have their own flags. Do **not** register several servers as only `mcpedia mcp` unless each client entry also supplies a different working directory. Otherwise they may all resolve the same `.rag/config.yaml` and appear as duplicates. ### When root is optional Root is optional only when you intentionally serve the current directory: ```powershell cd C:\Projects\MyKnowledgeBase mcpedia mcp ``` That is fine for quick testing, but not recommended for global/user-wide MCP registrations. ### Equivalent forms All of these can serve the same project: ```powershell mcpedia mcp C:\Projects\MyKnowledgeBase mcpedia mcp --root C:\Projects\MyKnowledgeBase $env:MCPEDIA_ROOT = "C:\Projects\MyKnowledgeBase"; mcpedia mcp ``` For VS Code and Claude Code registrations, prefer an explicit root. For MCP Inspector, the most reliable workflow is to run Inspector from inside the project folder and start MCPedia without a root argument. ## VS Code MCP setup VS Code supports MCP servers through JSON configuration. Use a unique key in the `servers` object for every MCPedia knowledge base. Each entry should pass a different project root path. VS Code supports MCP server configuration in user settings and workspace files such as `.vscode/mcp.json`. User-level configuration is good for personal knowledge bases used across many workspaces. Workspace-level `.vscode/mcp.json` is good when the MCP belongs to that repository. ### Workspace-level `.vscode/mcp.json` Create this file inside a repository: ```text C:\Projects\MyKnowledgeBase\.vscode\mcp.json ``` Example: ```json { "servers": { "myKnowledgeBase": { "type": "stdio", "command": "mcpedia", "args": ["mcp", "C:\\Projects\\MyKnowledgeBase"], "cwd": "C:\\Projects\\MyKnowledgeBase" } } } ``` Notes: - `myKnowledgeBase` is the VS Code registration key. Make it unique and meaningful. - `args` starts MCPedia in server mode and passes the project root as a positional argument. - `cwd` is still useful for clients that display or inherit a working directory. - If this file is committed, teammates should either use paths that work on their machines or replace the absolute path after cloning. If your VS Code setup supports workspace variables, you can use: ```json { "servers": { "projectKnowledge": { "type": "stdio", "command": "mcpedia", "args": ["mcp", "${workspaceFolder}"], "cwd": "${workspaceFolder}" } } } ``` ### User-level multi-repository setup Use this when you want several personal knowledge bases available from VS Code: ```json { "servers": { "myKnowledgeBase": { "type": "stdio", "command": "mcpedia", "args": ["mcp", "C:\\Projects\\MyKnowledgeBase"], "cwd": "C:\\Projects\\MyKnowledgeBase" }, "billingApiKnowledge": { "type": "stdio", "command": "mcpedia", "args": ["mcp", "C:\\Projects\\BillingApi"], "cwd": "C:\\Projects\\BillingApi" }, "productDocsKnowledge": { "type": "stdio", "command": "mcpedia", "args": ["mcp", "C:\\Projects\\ProductDocs"], "cwd": "C:\\Projects\\ProductDocs" } } } ``` ### If the `mcpedia` command is not found Use the explicit Node entry point from your global npm install: ```json { "servers": { "myKnowledgeBase": { "type": "stdio", "command": "node", "args": [ "C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\mcpedia\\dist\\index.js", "mcp", "C:\Projects\\MyKnowledgeBase" ], "cwd": "C:\\Projects\\MyKnowledgeBase" } } } ``` Find the global install path with: ```powershell npm root -g ``` Official VS Code docs: https://code.visualstudio.com/docs/agents/reference/mcp-configuration --- ## Claude Code MCP setup Claude Code can register stdio MCP servers with `claude mcp add`. The double dash `--` is important: everything after it is the command Claude Code runs. Basic command shape: `claude mcp add --transport stdio <name> -- mcpedia mcp <project>`. Add `--scope local`, `--scope project`, or `--scope user` before the server name when you want a specific scope. For MCPedia, prefer the positional project root: ```powershell mcpedia mcp <project> ``` so every registration is bound to one repository without relying on the client working directory. ### Claude Code scopes Claude Code supports these MCP registration scopes: | Scope | Use when | Visibility | |---|---|---| | `local` | You want the server only for the current project and only for you. | Current project only. This is the default. | | `project` | You want the team/repository to share the MCP registration. | Stored with the project, typically via `.mcp.json`. | | `user` | You want the server available to you across all Claude Code projects. | User-wide/global for your account on the machine. | ### Local scope, current project only This is the default if you omit `--scope`: ```powershell cd C:\Projects\MyKnowledgeBase claude mcp add --scope local --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase ``` If you omit the project path here, it may still work because the registration is tied to the current project, but an explicit path is clearer and safer. ### User-wide scope, available everywhere Use this for your personal collection of many MCPedia knowledge bases: ```powershell claude mcp add --scope user --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase claude mcp add --scope user --transport stdio billingApiKnowledge -- mcpedia mcp C:\Projects\BillingApi claude mcp add --scope user --transport stdio productDocsKnowledge -- mcpedia mcp C:\Projects\ProductDocs ``` For `--scope user`, an explicit project path is strongly recommended. Without it, MCPedia may serve whichever directory Claude Code launches from. ### Project scope, shared with a repository Use this when the MCP registration should live with the project and be shared with teammates: ```powershell cd C:\Projects\MyKnowledgeBase claude mcp add --scope project --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase ``` Project scope is useful for teams, but be careful with absolute Windows paths. Teammates may need to edit the path after cloning. ### Replace incorrect local registrations If you previously registered several MCPedia servers as only `mcpedia mcp`, remove and re-add them with explicit roots and the scope you want: ```powershell claude mcp remove myKnowledgeBase claude mcp remove billingApiKnowledge claude mcp add --scope user --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase claude mcp add --scope user --transport stdio billingApiKnowledge -- mcpedia mcp C:\Projects\BillingApi ``` Manage Claude Code MCP servers: ```powershell claude mcp list claude mcp get myKnowledgeBase claude mcp remove myKnowledgeBase ``` Inside Claude Code: ```text /mcp ``` Use one Claude Code server name per repository, such as `myKnowledgeBase`, `billingApiKnowledge`, and `productDocsKnowledge`. The Claude Code server name helps you manage registrations; MCPedia's `mcp.name` and namespaced tool names help traces show which repository was actually called. Claude Code also supports JSON-based configuration with `.mcp.json`, user configuration, and `claude mcp add-json` for advanced workflows. Official Claude Code docs: https://code.claude.com/docs/en/mcp --- ## Testing with MCP Inspector MCP Inspector is the best way to debug one MCPedia server before adding it to VS Code or Claude Code. For Inspector, use the **local-folder workflow**. Open PowerShell in the repository that already contains `.rag/config.yaml` and `.rag/store.lance`, then start Inspector with MCPedia in plain server mode: ```powershell cd C:\Projects\MyKnowledgeBase npx -y @modelcontextprotocol/inspector mcpedia mcp ``` In the Inspector UI, use exactly: ```text Transport: STDIO Command: mcpedia Arguments: mcp ``` Do **not** pass a project path through Inspector. In practice, Windows path forwarding through Inspector can be inconsistent. MCPedia should receive the project root from the shell working directory for Inspector testing. Browserless CLI check: ```powershell cd C:\Projects\MyKnowledgeBase npx -y @modelcontextprotocol/inspector --cli mcpedia mcp --method tools/list ``` Expected tools are the configured namespaced names, for example: ```text my_knowledge_base_search my_knowledge_base_tree ``` If the Inspector UI keeps loading, first verify the server itself from the same folder: ```powershell cd C:\Projects\MyKnowledgeBase mcpedia mcp ``` It should stay running until you press `Ctrl+C`. Then run Inspector again from that same folder: ```powershell npx -y @modelcontextprotocol/inspector mcpedia mcp ``` Common Inspector mistakes: ```powershell # Wrong: missing the MCPedia server subcommand. npx -y @modelcontextprotocol/inspector mcpedia ``` For Inspector on Windows, do not pass a project path, do not pass `--root`, and do not rely on `MCPEDIA_ROOT`. Use only the local-folder command shown above. For VS Code and Claude Code, explicit project roots are still recommended because those clients may start servers from a different working directory. Inspector is the exception: run it from the indexed project folder and use `mcpedia mcp` only. ## Windows Tree-sitter troubleshooting Tree-sitter gives MCPedia better code chunks. On Windows, native module loading can fail for two common reasons. ### 1. Missing Microsoft Visual C++ runtime Install or repair the latest supported **Microsoft Visual C++ v14 Redistributable x64**. PowerShell as Administrator: ```powershell $installer = Join-Path $env:TEMP "vc_redist.x64.exe" Invoke-WebRequest "https://aka.ms/vc14/vc_redist.x64.exe" -OutFile $installer Start-Process -FilePath $installer -ArgumentList "/install", "/passive", "/norestart" -Verb RunAs -Wait ``` Verify: ```powershell Test-Path "$env:WINDIR\System32\VCRUNTIME140.dll" ``` Expected: ```text True ``` ### 2. `node.dll` import in the published Windows native binary Some Windows x64 builds of the Tree-sitter language pack may import `node.dll`, while official Node.js for Windows provides `node.exe`. MCPedia detects and repairs this safely. Check only: ```powershell mcpedia doctor --check-only ``` Apply repair and validate: ```powershell mcpedia doctor ``` Then verify a grammar: ```powershell mcpedia grammars csharp ``` Expected: ```text ✔ Tree-sitter grammar ready: csharp ``` If indexing previously fell back to text chunks, rebuild: ```powershell Remove-Item .rag\store.lance -Recurse -Force -ErrorAction SilentlyContinue mcpedia index ``` --- ## Troubleshooting ### `mcpedia: command not found` Check global npm binaries: ```powershell npm bin -g npm list -g --depth=0 ``` Reinstall: ```powershell npm install -g mcpedia ``` ### Ollama model not found ```powershell ollama pull qwen3-embedding:8b ollama pull gemma4:12b ollama list ``` ### Embedding dimension mismatch The `dimension` value must match the embedding model. Examples: ```yaml qwen3-embedding:8b -> 4096 qwen3-embedding:4b -> 2560 qwen3-embedding:0.6b -> 1024 ``` After changing model or dimension: ```powershell mcpedia index ``` ### MCP client cannot connect Make sure the command includes the `mcp` subcommand: ```text command: mcpedia args: ["mcp"] ``` Run from the repository root or set the client `cwd` to the repository root. ### Indexing is slow or memory-heavy Use a smaller embedding model or smaller batches: ```yaml embedding: model: qwen3-embedding:4b dimension: 2560 batchSize: 4 timeoutMs: 300000 ``` Or index fewer files: ```yaml files: extensions: [".cs", ".csproj", ".md", ".json", ".yaml"] ``` --- ## Security and privacy - The LanceDB index is local under `.rag/store.lance`. - Do not commit `.rag/`. - Do not commit real API keys in YAML. - `.env`, private keys, and local credentials are excluded by default. - Cloud providers receive only text sent for embeddings or generation according to your provider configuration, including text extracted from PDF or Office files when those files are indexed. - MCP clients can call tools, so register only repositories you are comfortable exposing to that client. --- ## License and support Created by **Hamed Fathi**. Released under the **MIT License**. If MCPedia is useful to you, please star the GitHub repository. Stars, issues, discussions, documentation improvements, and pull requests all help improve the project.