| set_project_rootA | Sets the target project root directory.
Call this FIRST when working with a project that is not auto-detected.
Args:
path: Absolute path to the project root directory.
Returns:
Confirmation message with the new project root.
|
| healthA | Lightweight readiness check for the ProjectMind MCP server.
Reports: server version, active project root, memory file status, index status,
and whether the configured project is the MCP server's own directory.
Does NOT initialize the vector store or embeddings model.
Returns:
Markdown-formatted health report.
|
| session_initA | Single-call session bootstrap. Call this FIRST in every AI session.
Performs:
1. Sets project root (if `project_path` is provided).
2. Warns if the chosen root is the MCP server's own directory.
3. Reads `.ai/memory.md` (only the index/headings — full text on demand).
4. Refreshes the lightweight L0 manifest.
5. Reports vector-index status (without loading it).
6. Starts the self-healing maintenance daemon.
The heavy vector store / embedding model is NEVER loaded here — it is
lazily loaded only when a semantic query needs it. This keeps
`session_init` well under the MCP 30s tool timeout even on multi-GB
repositories.
Args:
project_path: Absolute path to the target project. Leave empty to use
auto-detection (CWD + project markers).
Returns:
Consolidated Markdown brief summarising project root, memory, and index state.
|
| get_project_overviewA | Returns a fast, lightweight overview of the project.
Does NOT require vector store or indexing.
Use this FIRST to understand the project before diving deeper.
Returns:
Project name, tech stack, root directories, file type counts, config files.
|
| explore_directoryA | Lists files and subdirectories at the given path. Very fast, no indexing needed.
Use this to navigate the project tree level by level.
Args:
path: Directory path relative to project root (use "." for root).
depth: How many levels deep to show (1-3). Default 1.
max_items: Maximum items to return. Default 100.
Returns:
Tree-like listing of the directory contents.
|
| get_file_summaryA | Returns a lightweight summary of a file: size, imports, top-level definitions,
and the first N lines. Does NOT require indexing.
Args:
path: File path relative to project root.
max_lines: Max lines of content to include (default 50).
Returns:
File metadata, structure, and preview.
|
| detect_project_conventionsA | Auto-detects project conventions: naming style, test patterns, frameworks,
linting/formatting tools, error handling, logging, architecture.
Does NOT require indexing. Results can be saved to memory for future reference.
Returns:
Formatted conventions report.
|
| get_context_briefA | Deterministic CONTEXT BRIEF for a coding task — the scout pyramid, layer 0.
Combines hybrid retrieval (vector/BM25), one-hop import-graph expansion,
file skeletons from the manifest and git recency into a ranked, budget-
packed markdown brief. Zero LLM calls, typically <500ms.
Args:
task: The coding task in natural language.
budget_tokens: Approximate token budget for the brief (default 4000).
hint_files: File paths explicitly mentioned in the task (client-extracted).
hint_symbols: Identifiers/symbols mentioned in the task (client-extracted).
Returns:
Markdown brief: ranked files with symbols, import relations and
top excerpts. Empty string when nothing relevant is indexed yet.
|
| get_file_relationsA | Shows import relationships for a file: what it imports, what imports it,
and related test files. Built from static analysis (no indexing needed).
Args:
path: File path relative to project root.
Returns:
Import graph and impact assessment for the file.
|
| find_todosA | Scans the codebase for TODO, FIXME, HACK, BUG, XXX comments.
Does NOT require indexing.
Args:
tag: Optional filter by tag (e.g. "TODO", "FIXME"). None = all tags.
Returns:
Summary and list of all TODO-like comments with file locations.
|
| check_dependenciesA | Analyzes project dependencies: versions, pinning strategy, duplicates, lock files.
Supports Python (pyproject.toml, requirements.txt), JS (package.json),
Go (go.mod), and Rust (Cargo.toml). No indexing required.
Returns:
Dependency health report with version analysis.
|
| analyze_change_impactA | Predicts what breaks if you change a file. Uses import graph to find
direct dependents, transitive impact, and related tests to run.
Args:
path: File path relative to project root.
Returns:
Impact analysis with risk assessment and test recommendations.
|
| get_dependencies_with_depthA | Gets file dependencies up to specified depth in the import graph.
Args:
file_path: File path relative to project root
depth: How many levels deep to traverse (1-5, default 2)
direction: "downstream" (what it imports) or "upstream" (what imports it)
Returns:
List of files with their distance from the target file
|
| find_dependency_pathB | Finds the shortest dependency path between two files.
Args:
from_file: Source file path (relative to project root)
to_file: Target file path (relative to project root)
max_depth: Maximum search depth (default 10)
Returns:
Dependency chain from source to target, or message if no path found
|
| get_module_clusterA | Finds files closely related to the target based on shared dependencies.
Uses Jaccard similarity to identify modules that work together.
Args:
file_path: File path relative to project root
similarity_threshold: Minimum similarity score 0.0-1.0 (default 0.3)
max_cluster_size: Maximum number of related files (default 20)
Returns:
List of related files sorted by similarity score
|
| search_with_dependenciesA | Searches codebase and optionally includes dependencies of matching files.
Combines semantic search with structural dependency analysis.
Args:
query: Search query
n_results: Number of semantic search results (default 5)
include_deps: Whether to include dependencies (default True)
depth: Dependency depth to include if include_deps=True (default 1)
Returns:
Search results with optional dependency context
|
| search_for_errorsA | Specialized search for debugging errors. Automatically searches in:
- Error handlers and exception code
- Test files
- Similar error patterns
- Related git commits (if error recently introduced)
Args:
error_text: The error message or exception type
stacktrace: Optional stacktrace for better context
n_results: Number of results per category (default 5)
Returns:
Organized results focusing on debugging context
|
| search_for_featureB | Specialized search for understanding a feature. Automatically finds:
- Entry points and main implementations
- Configuration files
- Related tests
- Documentation
Args:
feature_name: Name or description of the feature
n_results: Number of results per category (default 10)
Returns:
Organized results showing feature implementation structure
|
| search_architectureB | Specialized search for understanding architecture. Finds:
- Core modules and entry points
- Module dependencies
- Configuration and setup
- Architectural patterns
Args:
component: Component or module name (e.g., "auth", "database", "api")
n_results: Number of results (default 10)
Returns:
Architectural overview with dependency relationships
|
| find_symbolA | Finds where a function/class/method is defined using the AST symbol graph.
Works without the vector index (no embedding model needed).
Args:
name: Symbol name — exact or partial (case-insensitive).
n_results: Max results (default 8).
Returns:
Definitions with file:line plus caller/callee counts.
|
| get_symbol_relationsA | Returns AST-level relations of a symbol from the symbol graph.
Args:
symbol: Function/class/method name (bare, e.g. "UserService").
relation: One of "usages" (default), "callers", "callees",
"implementors", "subclasses", "bases", "info".
Returns:
Related symbols with file:line, or full info for relation="info".
|
| save_annotationA | Saves an AI-authored annotation (summary + keywords) for a source file.
Annotations make keyword search semantic WITHOUT embeddings: your summary
is indexed into BM25, so natural-language queries like "where is auth
handled" match it. Write annotations for files you have just read or
changed — 1-2 sentences on what the file does and why it exists.
Args:
path: File path relative to project root (or absolute inside it).
summary: 1-3 sentences: purpose, key responsibilities, notable design.
keywords: Comma-separated search terms a developer might query
(synonyms, domain words not present in identifiers).
Returns:
Confirmation with annotation coverage stats.
|
| get_annotationsA | Reads file annotations.
Args:
path: Specific file to read the annotation for. Empty = coverage
overview with all annotated files.
Returns:
The annotation (or coverage summary) in Markdown.
|
| list_unannotated_filesA | Lists code files that have no annotation (or a stale one), so you can
annotate them with save_annotation().
Recommended workflow: after finishing work on a file, save/refresh its
annotation; periodically run this tool and annotate the backlog — that is
what makes natural-language search over this project accurate.
Args:
limit: Max files per category (default 20).
Returns:
Missing and stale annotation lists + coverage stats.
|
| save_conventions_to_memoryB | Detects project conventions and saves them to memory.md automatically.
This persists conventions so AI assistants have context without re-scanning.
Returns:
Confirmation with summary of what was saved.
|
| project_onboardingA | One-command full project briefing. Runs overview + conventions + dependencies +
TODOs and compiles a comprehensive brief for onboarding a new developer or AI.
Results are saved to memory for future reference.
Returns:
Complete project brief.
|
| read_memoryB | Read project memory.
Args:
max_lines: Maximum number of lines to return (default: 100).
Set to None for full content. Use smaller values for quick summaries.
Returns:
Memory content (possibly truncated)
|
| search_memoryA | Relevance-ranked memory retrieval. Returns the memory blocks most relevant
to `query` (scored by keyword overlap) instead of the head of memory.md.
Use this to pull targeted prior decisions/conventions/notes for the current
task without loading the whole memory file.
Args:
query: Free-form text describing what you're looking for.
n_results: Maximum number of memory blocks to return (default 5).
Returns:
Markdown with the top matching memory blocks, or a hint if none match.
|
| update_memoryD | – |
| clear_memoryD | – |
| delete_memory_sectionD | – |
| index_codebaseA | Indexes the entire codebase for semantic search.
Limited to 5000 files per operation. For large codebases use index_changed_files() instead.
By default runs in **background** mode: returns immediately with a project
structure overview while the heavy embedding work continues in a daemon thread.
Call `get_index_progress()` to poll completion status.
Args:
force: If True, clears existing index before indexing.
background: If True (default), runs indexing in a background thread and
returns immediately with a project overview. If False, blocks
until indexing is fully complete (old behaviour — may timeout
on large codebases).
Returns:
- background=True: instant project structure overview + status line
- background=False: final indexing stats string
|
| get_index_progressA | Returns the current status of a background indexing operation started by
`index_codebase()` (with background=True, which is the default).
Statuses:
- **idle** — no indexing job has been run yet
- **scanning** — discovering indexable files (fast, ~1 s)
- **initializing_model**— loading SentenceTransformer model (30–60 s first run)
- **indexing** — embedding and storing file chunks
- **finalizing** — flushing buffers and rebuilding BM25 index
- **done** — indexing complete, search tools are ready
- **error** — indexing failed (see `last_error` field)
Returns:
Markdown-formatted progress report with file counts, percentage, and ETA.
|
| search_codebaseD | – |
| ingest_git_historyD | – |
| get_index_statsA | Returns statistics about the current vector store (number of chunks).
This operation is very fast and doesn't trigger vector store initialization. |
| generate_project_summaryD | – |
| extract_tech_stackD | – |
| analyze_project_structureD | – |
| get_recent_changes_summaryD | – |
| index_changed_filesA | Incrementally indexes only changed files since last indexing.
By default runs in background mode (non-blocking): detects changed files and
offloads embedding work to a background daemon thread, returning immediately.
Call `get_index_progress()` to monitor completion.
Args:
background: If True (default), runs indexing in background and returns
immediately. If False, blocks until complete (old behaviour).
Returns:
Status message with indexing info
|
| search_codebase_advancedD | – |
| auto_update_memory_from_commitsD | – |
| analyze_code_complexityB | Analyze cyclomatic complexity. mode='quick' (100 files) or 'deep' (1000). |
| analyze_code_qualityC | Pylint-based quality scan. mode='deep' raises max_files cap to 100. |
| get_test_coverage_infoD | – |
| save_memory_versionD | – |
| list_memory_versionsD | – |
| restore_memory_versionD | – |
| get_cache_statsB | Returns performance statistics for all caches.
Returns:
Formatted string with cache statistics
|
| queryA | Tier-aware project query. Cheaper than `search_codebase`.
Routes through L0 (manifest), then L1 (BM25), then L2 (vector embeddings),
escalating only when the previous tier yields a weak signal.
Args:
text: Free-form query.
intent: "overview" | "lookup" | "semantic" | "deep".
- overview: L0 only — paths and symbols. Always sub-second.
- lookup: L0 + L1 — keyword/lexical search.
- semantic: L0 + L1 + L2 — pulls in embeddings if signal is weak.
- deep: L0 + L1 + L2 — relaxed thresholds, more results.
n_results: Final number of merged hits to return (1-50).
|
| read_memory_indexA | Returns just the section headings from `.ai/memory.md` plus a short tip.
Use this for an initial cheap scan; then call `read_memory_section(name)`
to expand only the section you actually need.
|
| read_memory_sectionA | Returns the contents of a single `## Heading` section from memory.md.
Args:
section_name: Case-insensitive section heading (without leading `#`).
max_lines: Max lines of body to return (truncated with a tip).
|
| maintenance_statusA | Reports the self-healing daemon's status, schedule, and recent history. |
| maintenance_runA | Synchronously run every self-healing task once. Returns a per-task report. |
| prune_indexA | Aggressively prunes the vector index: drops orphan chunks and runs VACUUM.
Pass `force=True` to delete and rebuild the entire collection from scratch.
|
