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, unsupported files, and oversized code sections.

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

Related MCP server: code-index-mcp

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:

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:

npm install -g mcpedia
mcpedia --version

Update later:

npm update -g mcpedia

Uninstall:

npm uninstall -g mcpedia

Quick start

First make sure Ollama is installed and the default models are available:

ollama pull qwen3-embedding:8b
ollama pull gemma4:12b

Then index the repository you want to use as a knowledge base:

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:

mcpedia mcp

That command appears to wait. This is expected: an MCP client communicates with it over stdin/stdout.

Project layout

After mcpedia init:

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:

.rag/

Which command should I use?

Use verbose mode when diagnosing discovery, chunking, embeddings, or provider calls:

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.

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:

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.

mcpedia doctor --check-only
mcpedia doctor

Options:

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:

$env:MCPEDIA_DISABLE_NATIVE_REPAIR = "1"

mcpedia grammars

Why this command exists: manages Tree-sitter grammars used for code-aware chunking.

mcpedia grammars --detect src\Program.cs
mcpedia grammars csharp typescript python
mcpedia grammars --list
mcpedia grammars --all

Options:

Examples:

mcpedia grammars --detect C:\Projects\MyKnowledgeBase\src\Application\Service.cs
mcpedia grammars csharp

Expected detection:

C:\Projects\MyKnowledgeBase\src\Application\Service.cs: csharp

mcpedia index

Why this command exists: builds or rebuilds the local searchable index.

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:

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.

mcpedia tree
mcpedia tree src
mcpedia tree src --max-depth 3
mcpedia tree "C:\Projects\MyKnowledgeBase\src" --max-depth 4 --absolute-paths

Options:

Tree output begins with the resolved locations, for example:

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.

mcpedia search "authentication middleware"
mcpedia search "where is tenant validation?" --top-k 12

Options:

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.

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.

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

Environment alternative:

$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:

.rag/config.yaml

YAML values take priority. When apiKey or baseUrl is null, MCPedia checks environment variables and then provider defaults.

API keys

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:

embedding:
  apiKey: "sk-your-key"

Supported variables:

Embeddings

Default accuracy-first local setup:

embedding:
  provider: ollama
  model: qwen3-embedding:8b
  dimension: 4096
  baseUrl: http://localhost:11434
  apiKey: null
  batchSize: 8
  timeoutMs: 180000
  maxRetries: 3

Lower-resource alternatives:

# Balanced
model: qwen3-embedding:4b
dimension: 2560
batchSize: 8

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

llm:
  provider: ollama
  model: gemma4:12b
  maxTokens: 8192
  temperature: 0.2
  timeoutMs: 120000
  maxRetries: 3

Cloud examples:

llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  apiKey: null

llm:
  provider: openai
  model: gpt-4.1
  apiKey: null

File discovery

files:
  include:
    - "**/*"
  exclude:
    - "**/node_modules/**"
    - "**/dist/**"
    - "**/.gitignore"
    - "**/package-lock.json"
    - "**/.env"
  extensions: []
  respectGitignore: true
  followSymlinks: false
  maxFileSizeBytes: 1000000

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;

• 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

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:

chunking:
  separators:
    - "\n## "
    - "\n### "
    - "\n\n"
    - "\n"
    - ". "
    - " "
    - "" # individual characters as the final fallback

Language override example:

chunking:
  languageOverrides:
    ".foo": typescript
    "SpecialFile": python
    "src/generated/Legacy.cs": text

Use text to force recursive text splitting for one file or pattern.

Search

search:
  topK: 8
  overfetch: 4
  createVectorIndexThreshold: 256

Candidate count before reranking:

topK × overfetch

MCP identity

Use meaningful names for every repository so traces clearly show which knowledge base was used:

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:

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:

.rag/config.yaml
.rag/store.lance

Example repositories:

C:\Projects\MyKnowledgeBase
C:\Projects\BillingApi
C:\Projects\ProductDocs

Each repository should also have a unique MCP identity in its own .rag/config.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:

my_knowledge_base_search
my_knowledge_base_tree

For another repository:

mcp:
  name: billing-api-knowledge
  title: Billing API Knowledge
  namespaceTools: true
  toolNamePrefix: auto

The tools become:

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:

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:

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:

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:

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:

C:\Projects\MyKnowledgeBase\.vscode\mcp.json

Example:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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:

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:

Local scope, current project only

This is the default if you omit --scope:

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:

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:

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:

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:

claude mcp list
claude mcp get myKnowledgeBase
claude mcp remove myKnowledgeBase

Inside Claude Code:

/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:

cd C:\Projects\MyKnowledgeBase
npx -y @modelcontextprotocol/inspector mcpedia mcp

In the Inspector UI, use exactly:

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:

cd C:\Projects\MyKnowledgeBase
npx -y @modelcontextprotocol/inspector --cli mcpedia mcp --method tools/list

Expected tools are the configured namespaced names, for example:

my_knowledge_base_search
my_knowledge_base_tree

If the Inspector UI keeps loading, first verify the server itself from the same folder:

cd C:\Projects\MyKnowledgeBase
mcpedia mcp

It should stay running until you press Ctrl+C. Then run Inspector again from that same folder:

npx -y @modelcontextprotocol/inspector mcpedia mcp

Common Inspector mistakes:

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

$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:

Test-Path "$env:WINDIR\System32\VCRUNTIME140.dll"

Expected:

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:

mcpedia doctor --check-only

Apply repair and validate:

mcpedia doctor

Then verify a grammar:

mcpedia grammars csharp

Expected:

✔ Tree-sitter grammar ready: csharp

If indexing previously fell back to text chunks, rebuild:

Remove-Item .rag\store.lance -Recurse -Force -ErrorAction SilentlyContinue
mcpedia index

Troubleshooting

mcpedia: command not found

Check global npm binaries:

npm bin -g
npm list -g --depth=0

Reinstall:

npm install -g mcpedia

Ollama model not found

ollama pull qwen3-embedding:8b
ollama pull gemma4:12b
ollama list

Embedding dimension mismatch

The dimension value must match the embedding model.

Examples:

qwen3-embedding:8b  -> 4096
qwen3-embedding:4b  -> 2560
qwen3-embedding:0.6b -> 1024

After changing model or dimension:

mcpedia index

MCP client cannot connect

Make sure the command includes the mcp subcommand:

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:

embedding:
  model: qwen3-embedding:4b
  dimension: 2560
  batchSize: 4
  timeoutMs: 300000

Or index fewer files:

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.

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