Uses git diff for incremental re-indexing, syncing only modified files after code changes.
Accepts GitHub repository URLs for cloning and ingestion, enabling analysis of remote codebases.
Generates an Obsidian vault with structured, linked markdown notes summarizing every file and directory in a codebase, enabling AI-powered navigation and exploration.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codelore-mcp how does authentication work in this repo?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Turn any code repository into a searchable Obsidian vault — then let Claude Code navigate it as a set of MCP tools.
codelore runs a two-phase pipeline:
Summarise — calls claude --print once per file and directory to produce structured markdown documentation
Index — chunks every file at the function/class level, generates developer questions for each chunk, and stores them in a ChromaDB vector index
The result is an Obsidian vault of linked markdown notes and a semantic search index that Claude Code can query as native tools.
your-repo/
src/auth/middleware.py → AI summary + import graph
src/db/pool.py → AI summary + import graph
...
↓ codelore ingest
your-repo_vault/
INDEX.md overview + wikilinks to all modules
src/auth/middleware.md structured summary of every function
src/db/pool.md ...
your-repo_chroma/ ChromaDB: chunks indexed by developer questionsClaude Code reads INDEX.md → directory notes → file notes via the explore_repo tool, and answers "how does X work?" questions via search_code which hits the semantic index.
Related MCP server: obsidian-mcp
Python 3.11+
uv — used to run the MCP server and manage dependencies
Claude Code CLI — claude.ai/download
claude --version # must be on PATHgit clone https://github.com/yourname/codelore
cd codelore
uv sync # creates .venv/ and installs all dependencies
source .venv/bin/activate # Windows: .venv\Scripts\activate# 1. Ingest a local repo (or pass a GitHub URL)
codelore ingest /path/to/your-repo
# Preview cost before running on a large repo
codelore ingest /path/to/your-repo --dry-run
# Re-use cached summaries from a previous run (skips claude calls)
codelore ingest /path/to/your-repo # prompted automatically if cache exists
# 2. Query from the terminal
codelore query "how does authentication work?" \
--chroma /path/to/your-repo_chroma
# 3. Print MCP setup instructions
codelore init --vault /path/to/your-repo_vault \
--chroma /path/to/your-repo_chroma \
--repo /path/to/your-repocodelore ingest <repo>Flag | Description |
| Override vault output directory (default: |
| Load a pre-generated |
| Print file count and estimated Claude calls without running |
| Write structural vault (file tree + imports) without any Claude calls |
codelore query <question>Flag | Description |
| ChromaDB directory (or set |
| Vault directory for summary snippets (or set |
| Number of results (default: 5) |
codelore initPrints step-by-step setup instructions and a ready-to-paste MCP config block.
Flag | Description |
| Pre-fill vault path in the generated config |
| Pre-fill ChromaDB path in the generated config |
| Pre-fill repo root path in the generated config |
After ingesting, add codelore as an MCP server so Claude Code can call it as tools.
If you cloned the repo, it already includes a .mcp.json at the project root that launches the server via uv. Just make sure uv is installed and run uv sync — the MCP server will start automatically when you open the project in Claude Code.
To set it up manually for a different project, create a .mcp.json in the project root:
{
"mcpServers": {
"codelore": {
"command": "uv",
"args": ["run", "codelore-mcp"],
"env": {
"VIRTUAL_ENV": ""
}
}
}
}The "VIRTUAL_ENV": "" clears any activated venv so uv uses its own .venv/ without conflicts.
All tools accept vault_root, chroma_path, and repo_root as per-call parameters. To avoid passing them every time, add them to the env block:
{
"env": {
"VIRTUAL_ENV": "",
"CODELORE_VAULT_ROOT": "/path/to/your-repo_vault",
"CODELORE_CHROMA_PATH": "/path/to/your-repo_chroma",
"CODELORE_REPO_ROOT": "/path/to/your-repo"
}
}codelore init will generate a ready-to-paste config with your actual paths filled in.
Tool | Triggers on |
| "how does X work?", "where is Y defined?" |
| "explain this codebase", "give me an overview" |
| debugging |
| "what's left to implement?", "show open tasks" |
| "add a note about X", "append my findings to the auth module" |
| architectural guidelines doc (optional) |
| "how many claude calls would this take?" |
| "ingest this repo" |
| rebuild vault from saved explanations |
| incremental re-index after code changes |
codelore generates an Obsidian-compatible vault, and several codelore tools are designed to hand off to the Obsidian Local REST API MCP for direct vault operations. Setting this up unlocks:
vault_read — read any vault note directly (the sole path for reading vault notes; codelore's read_vault_node is unregistered/disabled for now and can be restored if the Obsidian MCP proves unreliable)
vault_append — safely append notes to existing vault files without overwriting
search_simple — plain-text search across your vault as a fallback when semantic search returns no results
Install the Obsidian Local REST API plugin in Obsidian.
Enable the plugin and copy the API key from its settings.
Add the following to your .mcp.json alongside the codelore entry:
{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "http://127.0.0.1:27123/mcp/",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}Once both MCP servers are running, Claude will automatically use them together:
search_code (codelore) → falls back to search_simple (Obsidian MCP) → falls back to raw file grep
vault_append (codelore) resolves the right vault note, then calls vault_append (Obsidian MCP) to append safely
explore_repo and find_todos direct Claude to use vault_read (Obsidian MCP) for follow-up note reading
Note: The Obsidian MCP vault_write tool overwrites files entirely and is not used by codelore tools. It will only be called if you explicitly ask for it by name.
Language | Extensions | Chunking |
Python |
| AST (function + class level) |
JavaScript / TypeScript |
| tree-sitter |
Go |
| tree-sitter |
Java |
| tree-sitter |
Kotlin |
| tree-sitter |
Scala |
| tree-sitter |
C# |
| tree-sitter |
Haskell |
| tree-sitter |
Elixir |
| tree-sitter |
Lua |
| tree-sitter |
Shell |
| tree-sitter |
Dart |
| whole-file |
R |
| whole-file |
Non-code files (.md, .json, .yaml, .toml, .sql, .proto, .graphql) are also indexed for context.
After code changes, sync only the modified files instead of re-running the full pipeline:
# via MCP tool (in Claude Code):
"sync the vault for /path/to/repo" → calls sync_vault(dry_run=True) first
# or directly:
sync_vault(repo_path="/path/to/repo", explanations_json_path="..._explanations.json", dry_run=True)
sync_vault(repo_path="/path/to/repo", explanations_json_path="..._explanations.json", dry_run=False)Requires the repo to be a git repository (uses git diff against the SHA saved during ingestion).
codelore/
main.py CLI entry point (ingest / query / init subcommands)
ingest.py build file/directory graph, write vault markdown
explain.py collect files, call Claude CLI for summaries
llm.py Claude CLI wrapper, prompt templates
nodes.py FileNode / DirectoryNode / IndexNode → markdown
generate_questions.py chunk-level question generation + ChromaDB indexing
parsers/ language-specific import graph + chunk extraction
_treesitter.py shared tree-sitter helper
python.py stdlib ast
javascript.py tree-sitter-javascript / tree-sitter-typescript
go.py tree-sitter-go
jvm.py tree-sitter-java / tree-sitter-kotlin / tree-sitter-scala
csharp.py tree-sitter-c-sharp
haskell.py tree-sitter-haskell
elixir.py tree-sitter-elixir
lua.py tree-sitter-lua
shell.py tree-sitter-bash
...
query/
retrieval.py search_chunks, bfs_vault, grep_todos, git_file_log
mcp_server.py FastMCP server exposing 9 toolsMIT
Estimate how many Claude CLI calls ingesting a repo will require.
Use this BEFORE running ingest_repo on a large codebase to understand the scope. Reports file counts by language and the total number of 'claude --print' subprocess calls that will be made.
Does not call Claude or modify anything — safe to run at any time.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states it 'Does not call Claude or modify anything — safe to run at any time', which is critical behavioral information. Since no annotations are provided, this fulfills the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with three sentences, no redundancy, and the main purpose is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one required parameter) and the presence of an output schema, the description sufficiently covers the purpose and usage. No additional details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'repo_path' has no description in the input schema (0% coverage). The description does not clarify format or expected values, leaving the agent to infer from the tool name. More detail would improve usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Estimate' and the resource 'Claude CLI calls ingesting a repo'. It distinguishes from the sibling tool 'ingest_repo' by specifying it is a preliminary estimation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to 'Use this BEFORE running ingest_repo on a large codebase', and explains what it reports and that it is safe to run at any time, providing clear guidance on when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a structured overview of the repo by traversing the vault graph.
Use this for onboarding questions: 'explain the repo', 'where do I start', 'give me an overview of the codebase', or 'what are the main components'. Starts from the vault INDEX and traverses breadth-first, returning summaries at increasing depth so you can understand the repo from the top down.
To drill into a specific node after this overview, use the Obsidian MCP
vault_read tool.
GUARDRAIL: Never call the Obsidian MCP vault_write tool unless the user
explicitly requests it by name.
vault_root is optional — omit to use CODELORE_VAULT_ROOT, or pass it explicitly to explore a different repo's vault without reconfiguring. Resolves against the configured target repo (see server instructions) — not necessarily the current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| max_depth | No | ||
| vault_root | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: starts from vault INDEX, breadth-first traversal, returns summaries at increasing depth, and explains vault_root resolution (optional, defaults to CODELORE_VAULT_ROOT, resolves to configured repo). No destructive actions implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose sentence, use-case list, traversal behavior, alternatives, guardrail, parameter details. Every sentence serves a purpose. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (graph traversal, optional root, integration with other tools) and existence of output schema, the description covers all necessary aspects: usage, behavior, parameters, and context. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% property descriptions, but the description adds meaning: max_depth controls traversal depth (implied by 'increasing depth'), and vault_root is optional with explicit fallback behavior. Could explicitly mention default values but still adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a structured overview of the repo by traversing the vault graph.' It distinguishes from sibling tools like vault_read (drill down) and vault_write (modification) by specifying appropriate use cases and alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use: onboarding questions such as 'explain the repo' or 'give me an overview.' Provides explicit alternatives (vault_read for drilling) and a guardrail against using vault_write unless explicitly requested, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find TODO/FIXME comments and recent git activity for relevant files.
Use this for project progress or task management questions: 'what's left to do', 'what needs work in the parser', 'what files are incomplete', 'show me open tasks'. Searches for the most relevant files via semantic search, then scans them for TODO/FIXME/HACK comments and shows recent git commits.
After identifying open tasks, you may use the Obsidian MCP vault_append
tool to add notes or progress updates to the relevant vault files without
overwriting existing content. Use vault_read (Obsidian MCP) to read the
file before appending.
GUARDRAIL: Never call the Obsidian MCP vault_write tool unless the user
explicitly requests it by name.
vault_root, chroma_path, and repo_root are optional — omit to use env vars, or pass them explicitly to query a different repo. Resolves against the configured target repo (see server instructions) — not necessarily the current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| n_files | No | ||
| repo_root | No | ||
| vault_root | No | ||
| chroma_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It explains the behavior: semantic search for relevant files, scanning for comments, showing recent commits. It also describes optional parameters and guardrails. However, it does not detail the output format, but this is somewhat mitigated by the presence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy with multiple paragraphs. It is front-loaded with purpose and usage, but includes guardrails and alternatives that could be more concise. While structured, it could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 0% schema coverage, no annotations), the description covers purpose, usage, behavior, guardrails, and parameter explanations. It differentiates from siblings and mentions output schema existence. Almost complete, but parameter details are slightly lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains that vault_root, chroma_path, and repo_root are optional and can be omitted to use env vars. It also states query is required for semantic search. However, it does not describe n_files or chroma_path explicitly, and no parameter-level details are given. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds TODO/FIXME comments and recent git activity. It distinguishes from siblings like search_code by focusing on project progress and task management. The verb 'find' and resource 'todos' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use: for project progress/task management questions with example queries (e.g., 'what's left to do'). It also advises against using vault_write unless explicitly requested, and suggests vault_append and vault_read as alternatives. This is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which repo this codelore server is currently scoped to — useful to sanity-check before a multi-step task, or to debug a misconfigured .mcp.json. Not required before calling other tools: they already refuse to resolve to codelore's own source on their own.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_root | No | ||
| vault_root | No | ||
| chroma_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively communicates that the tool is a read-only report with no destructive side effects. It implies safe usage without altering state. However, it does not detail error behavior or edge cases (e.g., what happens if scope is not set), but for a simple informational tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding value. It front-loads the main purpose and immediately follows with usage guidance. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and usage well, it is incomplete because it fails to explain the three optional parameters. These parameters are likely used to specify paths for resolution, and their absence from the description leaves the agent uncertain about how to use them. Given the tool's simplicity, this omission significantly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (repo_root, vault_root, chroma_path) with 0% schema description coverage, meaning no descriptions in the schema. The tool description does not mention these parameters at all, failing to explain their purpose or how they influence the tool's behavior. This is a critical gap, as the description adds no value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Report') and resource ('which repo this codelore server is currently scoped to'). It also distinguishes from sibling tools by noting that other tools already refuse to resolve to codelore's source, making this tool useful for sanity-checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('useful to sanity-check before a multi-step task, or to debug a misconfigured .mcp.json') and when not ('Not required before calling other tools: they already refuse...'). This provides clear guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a code repository into codelore — generates the vault and search index.
Accepts either a local directory path or a GitHub URL (https://github.com/owner/repo). Runs the full pipeline:
Generates AI summaries for every file and directory via Claude CLI
Writes an Obsidian-compatible vault of markdown notes
Indexes code chunks as developer questions into ChromaDB
extra_frontmatter_json — optional JSON object of extra fields to add to every vault note's frontmatter, e.g. '{"project": "myapp", "status": "draft", "tags": ["backend", "python"]}'. Strings, numbers, booleans, and flat lists are all supported. These fields are merged after the built-in fields.
After ingestion, the tool prints the vault and chroma paths. Pass these as vault_root and chroma_path to the query tools, or set them as env vars.
WARNING: calls 'claude --print' once per file + directory + chunk. Run estimate_cost first on large repos.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path_or_url | Yes | ||
| vault_output_path | No | ||
| extra_frontmatter_json | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses all behavioral traits: runs AI summaries via Claude CLI, writes Obsidian vault, indexes into ChromaDB, and warns about cost. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: clear first sentence, then parameter details, post-ingestion steps, and warning. No redundant sentences. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects for a complex tool: inputs, pipeline steps, outputs, warnings, and links to other tools. Output schema exists, so return values need not be detailed. Complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains repo_path_or_url (local or URL) and extra_frontmatter_json in detail. vault_output_path is only implied in post-ingestion instructions, but overall adds significant meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool ingests a code repository into codelore, generating a vault and search index. It distinguishes from sibling tools like estimate_cost, explore_repo, etc., by specifying the full pipeline unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use: accepts local path or GitHub URL. Warns to run estimate_cost first on large repos, and directs to pass outputs to query tools. Provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the project's architectural guidelines and coding conventions.
Use this for questions about coding style, architectural patterns, conventions, how to structure new code, or what rules the project follows.
GUARDRAIL: Never call the Obsidian MCP vault_write tool unless the user
explicitly requests it by name.
guidelines_path is optional — omit to use CODELORE_GUIDELINES_PATH, or pass a path directly to read any guidelines document without reconfiguring.
| Name | Required | Description | Default |
|---|---|---|---|
| guidelines_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the optional guidelines_path and default behavior, but does not explicitly state that the tool is read-only or describe side effects. The guardrail about vault_write is a behavioral rule but relates to another tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four structured sentences: purpose, usage, guardrail, parameter explanation. It is front-loaded and each sentence adds value, though the guardrail could be considered extraneous to the tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter) and the existence of an output schema, the description adequately covers purpose, usage, and parameter semantics. The guardrail provides additional context for safe usage, making it informationally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains the parameter: 'guidelines_path is optional — omit to use CODELORE_GUIDELINES_PATH, or pass a path directly to read any guidelines document without reconfiguring.' This adds meaning beyond the schema's default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns architectural guidelines and coding conventions, with specific verb 'Return' and resource 'project's architectural guidelines'. It distinguishes from sibling tools (e.g., explore_repo, search_code) by focusing on guidelines and conventions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists explicit use cases: 'questions about coding style, architectural patterns, conventions, how to structure new code, or what rules the project follows.' It provides clear context for when to use, but does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild the vault and search index from an existing explanations file.
Use this to re-run vault generation WITHOUT making any Claude CLI calls for file summaries. Useful when you want to re-index after code changes but already have summaries, or to iterate on vault structure without LLM cost.
extra_frontmatter_json — optional JSON object of extra fields to add to every vault note's frontmatter, e.g. '{"project": "myapp", "status": "draft", "tags": ["backend", "python"]}'. Strings, numbers, booleans, and flat lists are all supported.
Note: ChromaDB question generation still calls Claude once per chunk — only the file/directory summaries are skipped (they're loaded from JSON).
The explanations.json is saved automatically by ingest_repo.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | ||
| vault_output_path | No | ||
| explanations_json_path | Yes | ||
| extra_frontmatter_json | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses that file/directory summaries are loaded from JSON (skipping Claude calls) while explaining that ChromaDB question generation still requires a Claude call per chunk. This provides valuable behavioral insight beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized and front-loaded with the main purpose. It is structured into clear paragraphs (purpose, usage, parameter detail, additional note). Every sentence adds value, though some parameter details could be more succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no annotations, and an output schema (not shown), the description covers usage context and one parameter well but omits details for other parameters and potential side effects (e.g., overwriting existing vault). It is sufficient but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides detailed semantics only for extra_frontmatter_json (type, example, supported data types) and explains explanations_json_path's origin. However, repo_path and vault_output_path lack any description beyond their names, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (rebuild) and resource (vault and search index) with specific context (from an existing explanations file). It distinguishes from siblings like ingest_repo and sync_vault by highlighting the avoidance of Claude CLI calls for file summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to re-run vault generation without making Claude CLI calls for file summaries, such as after code changes or to iterate on vault structure without LLM cost. It also notes that ChromaDB still calls Claude once per chunk, setting clear expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the codebase using semantic similarity.
Use this for functional questions: how something works, where a function is defined, what a module does, or any vague/underspecified question about code behaviour. Searches a question-indexed vector database and returns the most relevant code chunks together with their vault summary.
Each result is labeled Confidence: high or low based on whether its cosine distance is within max_distance (default 1.35 — tune it lower for stricter matching, higher to allow more speculative results through).
FALLBACK — if this tool returns no results or all results are labeled low
confidence, call the Obsidian MCP search_simple tool with the same query
for a plain-text search across vault notes; do not grep the repo's source
as a substitute for search — the vault is the source of truth for locating
relevant code.
Once you've located relevant code via a result's file_path (an absolute
path into the target repo, not the vault), reading that file directly
with Read/Grep is expected and normal when you need exact/current detail
the vault summary doesn't cover — the vault summarizes, it doesn't
replace the source.
After finding results, use the Obsidian MCP vault_read tool to read full
vault notes — try the vault-relative path first, and fall back to the
absolute path if the Obsidian MCP rejects it (path format depends on how
the Obsidian MCP server resolves paths against the vault root).
GUARDRAIL: Never call the Obsidian MCP vault_write tool unless the user
explicitly requests it by name.
vault_root and chroma_path are optional — if omitted, the server uses the CODELORE_VAULT_ROOT and CODELORE_CHROMA_PATH environment variables. Pass them explicitly to query a different repo without reconfiguring the server. Resolves against the configured target repo (see server instructions) — not necessarily the current working directory.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| n_results | No | ||
| vault_root | No | ||
| chroma_path | No | ||
| max_distance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the vector search mechanism, confidence labeling based on cosine distance, max_distance tuning, fallback logic, and integration with Obsidian MCP tools. Fully transparent about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Information-dense and structured with clear sections, but somewhat lengthy. Every sentence adds value, yet could be more concise without losing clarity. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists (so return values need not be described), the description covers all relevant aspects: behavior, parameters, fallback, guardrails, and integration with sibling tools. Complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description compensates thoroughly: explains query as natural language, n_results default, vault_root/chroma_path as optional env-var overrides, and max_distance as similarity threshold. Adds meaningful context beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the codebase using semantic similarity for functional questions, and distinguishes it from sibling tools like search_simple and grep through explicit fallback and avoidance instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (functional questions), when-not-to-use (avoid grep, vault_write only on user request), and fallback behavior (call search_simple on low confidence results). Includes detailed post-processing steps (read file directly, use vault_read).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect and apply repo changes since the last ingest.
Use this to keep the vault and search index in sync after code changes without re-processing the entire repo. Uses git diff against the commit SHA saved during the last ingest_repo run.
dry_run=True (default): reports changed, new, and deleted files — no changes made. dry_run=False: for each modified file, regenerates its summary and asks Claude whether it's a REAL conflict vs. the existing vault note (not just phrasing/ comment/formatting drift). Only real conflicts replace the note and reindex that file's ChromaDB questions — everything else is left as-is. Either way, the vault note gets a Sync Log entry noting the commit that was checked. New files are ingested for the first time; deleted files are removed.
Always run with dry_run=True first to review the change set, then call again with dry_run=False to apply. Requires the repo to be a git repository.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| repo_path | Yes | ||
| vault_root | No | ||
| chroma_path | No | ||
| explanations_json_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It thoroughly explains behavior: dry_run modes, conflict detection logic, handling of new/deleted files, and sync log entries. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but front-loaded with the core purpose. Every sentence earns its place, but some consolidation could improve conciseness without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (5 params, 0% schema coverage, output schema present), the description is complete. It covers behavior, usage prerequisites, and dry_run workflow. No gaps with the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the dry_run parameter in detail and mentions repo_path implicitly. Other parameters like vault_root are standard paths; the description adds value beyond the schema but stops short of explicitly documenting every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Detect and apply repo changes since the last ingest,' specifying the verb (sync) and resource (vault). It distinguishes from siblings like ingest_repo and rebuild_vault by focusing on incremental updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises when to use ('after code changes') and recommends a dry_run first. It also notes the requirement for a git repository. Explicit alternatives are not named, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the most relevant vault note for a user's annotation query and return
its path so the Obsidian MCP vault_append tool can safely append to it.
Use this when the user wants to add notes, progress updates, or observations to a vault file based on what they're currently doing — for example: 'add a note about the parser edge case', 'mark this TODO as resolved', 'append my findings on the auth module'.
WORKFLOW:
This tool resolves the target vault note path via semantic search.
Use the Obsidian MCP vault_read tool to read the current content of
that file before appending.
Use the Obsidian MCP vault_append tool to add the new content to the
end of the file. vault_append never overwrites existing content.
GUARDRAIL: Use vault_append (Obsidian MCP) for all note additions.
Never call the Obsidian MCP vault_write tool unless the user explicitly
requests it by name — vault_write overwrites the entire file.
Returns the resolved vault note path (both relative and absolute forms —
try the relative one first, and fall back to the absolute one if the
Obsidian MCP rejects it) so you can craft a contextual append. Use the
Obsidian MCP vault_read tool on that path first to see the note's
existing content before appending.
vault_root and chroma_path are optional — omit to use env vars.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| vault_root | No | ||
| chroma_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full disclosure burden. It explains the tool is read-only (resolves path, does not modify), returns relative and absolute paths, and that vault_root/chroma_path are optional. It does not mention authentication or rate limits, but these are not relevant for a resolver tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, workflow, guardrail, return info), but it is verbose and contains some repetition (e.g., the workflow is described twice). A tighter version could be more efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a coordinator that resolves a path for appending, the description covers all necessary context: the workflow, interaction with sibling tools (vault_read, vault_append), fallback path logic, and environment variable defaults. No gaps remain for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains that 'query' is the annotation text for semantic search, and that 'vault_root' and 'chroma_path' are optional (omit to use env vars). This adds meaning, but lacks details on query format or value constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find the most relevant vault note... and return its path' for appending. It distinguishes this from the actual append tool. However, the tool name 'vault_append' is misleading because the tool itself does not append, which may cause initial confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use examples ('add a note', 'mark TODO as resolved'), a detailed 3-step workflow, and a guardrail against using vault_write. This gives the agent clear context and exclusions for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0estimate_costexplore_repofind_todosget_active_scopeingest_reporead_guidelinesrebuild_vaultsearch_codesync_vaultvault_appendEach tool targets a distinct operation: estimation, exploration, search, ingestion, syncing, etc. There is no overlap or ambiguity in their purposes.
All tool names follow the verb_noun snake_case pattern consistently (e.g., estimate_cost, explore_repo, find_todos). Even informal terms like 'todos' fit the pattern.
10 tools cover the full lifecycle of repository ingestion and querying without being excessive or thin. The count is well-scoped for the server's purpose.
The tool set covers estimation, ingestion, exploration, search, syncing, and annotation assistance. Missing a delete tool, but the core workflows are complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Claude Code / MCP skills for the dev pipeline: discover, spec, design, build, ship, operate.
AI code review for GitHub PRs with an MCP autofix loop for Claude Code and Cursor
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ayush-Sadekar/codelore-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
