# 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.