The Project Explorer MCP Server is a tool for exploring, analyzing, searching, and managing project files and dependencies within defined directories. Here's what you can do with it:
Analyze project structures — view detailed file information, sizes, and import/export relationships for JavaScript/TypeScript files.
List allowed directories — see all directories the server is explicitly permitted to access.
Advanced search — search files and code using regex patterns, with filters for file type, size, modification date, and options to exclude comments or string literals.
Rename/move files and directories between specified paths.
Delete files or directories, with safety features like explicit confirmation required for recursive deletion.
Check outdated npm packages — including dev dependencies, with output in detailed, summary, or raw formats.
Secure sandboxed operation — all file operations stay within pre-configured directories and defined access permissions.
Configurable tools — disable specific tools like delete_file or rename_file for enhanced security.
Concurrent processing of multiple project directories.
Recognizes and automatically excludes Git directories (.git) during project exploration and file searches.
Provides reference to the project's GitHub repository, enabling users to find the source code and contribute to development.
Enables searching and analyzing Node.js projects, including checking for outdated npm packages and analyzing import/export statements in JavaScript files.
Provides tools for analyzing npm dependencies, checking for outdated packages, and offering detailed update recommendations with version information.
Supports analysis of TypeScript projects with specialized features for detecting import/export statements and searching through TypeScript files.
Click on "Deploy 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., "@Project Explorer MCP Server search for all async functions in the src directory"
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.
A powerful Model Context Protocol server for exploring, analyzing, and managing project files with advanced search capabilities
📦 Available on npm:
@team-jd/mcp-project-explorer
{
"mcpServers": {
"project-explorer": {
"command": "npx",
"args": ["-y", "@team-jd/mcp-project-explorer", "/your/project/path"]
}
}
}With disabled tools:
{
"mcpServers": {
"project-explorer": {
"command": "npx",
"args": [
"-y",
"@team-jd/mcp-project-explorer",
"/your/project/path",
"--disable-tool=delete_file"
]
}
}
}Related MCP server: Codebase MCP Server
▶ Watch the full demo on YouTube
Every line of raw file content your agent reads is context it never gets back. Project Explorer is built to answer structural questions without dumping files into the conversation:
🧠 explore_project returns a compact file listing plus an import/export dependency graph — no need to open files to understand a codebase
🎯 search_files trims output with snippetLength, maxResults, extensions, excludePatterns, excludeComments and excludeStrings, so you get only the lines that matter
🚫 Build and vendor noise (node_modules, dist, .git, .next, …) is always skipped
✂️ --disable-tool removes tools you don't use from the tool list entirely, shrinking the schema payload sent with every request
The Project Explorer MCP Server provides comprehensive tools for analyzing project structures, searching through codebases, managing dependencies, and performing file operations. Perfect for developers who need intelligent project navigation and analysis capabilities.
Add this server to your MCP settings configuration:
{
"mcpServers": {
"project-explorer": {
"command": "npx",
"args": [
"-y",
"@team-jd/mcp-project-explorer",
"/path/to/your/project"
]
}
}
}📁 Multiple Directory Access:
{
"mcpServers": {
"project-explorer": {
"command": "npx",
"args": [
"-y",
"@team-jd/mcp-project-explorer",
"/path/to/project1",
"/path/to/project2",
"/path/to/project3"
]
}
}
}🚫 Disabling Specific Tools:
Use --disable-tool=tool_name or --disable-tool tool_name to disable tools you don't want available. Disabled tools won't appear in the tools list and can't be called.
{
"mcpServers": {
"project-explorer": {
"command": "npx",
"args": [
"-y",
"@team-jd/mcp-project-explorer",
"/path/to/project",
"--disable-tool=delete_file",
"--disable-tool", "rename_file"
]
}
}
}📦 Available tools you can disable:
explore_project
list_allowed_directories
search_files
rename_file
delete_file
check_outdated
# Clone and setup for development
git clone https://github.com/MausRundung/mcp-explorer.git
cd mcp-explorer
# Install dependencies
npm install
# Build the project
npm run build
# Run the MCP inspector for testing
npm run inspectorexplore_projectAnalyzes project structure with detailed file information and import/export analysis
// Basic usage
explore_project({
directory: "/path/to/project"
})
// Advanced usage
explore_project({
directory: "/path/to/project",
subDirectory: "src", // Optional: focus on specific subdirectory
includeHidden: false // Optional: include hidden files (default: false)
})✨ Features:
📊 File size analysis with human-readable formatting
🔍 Import/export statement detection for JS/TS files
🚫 Automatically excludes build directories (node_modules, .git, dist, .vscode, .gradle, .idea, etc.)
📁 Recursive directory traversal
🎯 Support for subdirectory analysis
search_filesAdvanced file and code search with comprehensive filtering capabilities
// Simple text search
search_files({
pattern: "your search term",
searchPath: "/path/to/search"
})
// Advanced search with filters
search_files({
pattern: "function.*async", // Regex pattern
searchPath: "/path/to/search",
regexMode: true, // Enable regex
caseSensitive: false, // Case sensitivity
extensions: [".js", ".ts"], // File types to include
excludeExtensions: [".min.js"], // File types to exclude
excludeComments: true, // Skip comments
excludeStrings: true, // Skip string literals
maxResults: 50, // Limit results
sortBy: "relevance" // Sort method
})🎛️ Search Options:
Parameter | Type | Default | Description |
| string | required | Search pattern (text or regex). No default |
| string | first allowed dir | Directory to search in |
| string[] | all | Include only these file types |
| string[] |
| Exclude these file types |
| string[] |
| Exclude filename patterns |
| boolean |
| Treat pattern as regex |
| boolean |
| Case-sensitive search |
| boolean |
| Match whole words only |
| boolean |
| Multiline regex matching |
| number | unlimited | Directory recursion depth |
| boolean |
| Follow symbolic links |
| boolean |
| Search in binary files |
| number | none | Minimum file size (bytes) |
| number | none | Maximum file size (bytes) |
| string | none | Files modified after date (ISO 8601) |
| string | none | Files modified before date (ISO 8601) |
| number |
| Text snippet length around matches |
| number |
| Maximum number of results |
| string |
| Sort by: relevance, file, lineNumber, modified, size |
| boolean |
| Group results by file |
| boolean |
| Skip comments (language-aware) |
| boolean |
| Skip string literals |
| string |
| Output format: text or json |
🎯 Use Cases:
🔍 Find all TODO comments: pattern: "TODO.*", excludeStrings: true
🐛 Search for potential bugs: pattern: "console\\.log", regexMode: true
📦 Find import statements: pattern: "import.*from", regexMode: true
🔧 Recent changes: modifiedAfter: "2024-01-01", extensions: [".js", ".ts"]
check_outdatedChecks for outdated npm packages with detailed analysis
// Basic check
check_outdated({
projectPath: "/path/to/project"
})
// Detailed analysis
check_outdated({
projectPath: "/path/to/project",
includeDevDependencies: true, // Include dev dependencies
outputFormat: "detailed" // detailed, summary, or raw
})📋 Output Formats:
detailed - Full package info with versions and update commands
summary - Count of outdated packages by type
raw - Raw npm outdated JSON output
🔧 Requirements:
Node.js and npm must be installed
Valid package.json in the specified directory
delete_fileSafely delete files or directories with protection mechanisms
// Delete a file
delete_file({
path: "/path/to/file.txt"
})
// Delete a directory (requires recursive flag)
delete_file({
path: "/path/to/directory",
recursive: true, // Required for directories
force: false // Force deletion of read-only files
})⚠️ Safety Features:
🔒 Only works within allowed directories
📁 Requires recursive: true for non-empty directories
🛡️ Protection against accidental deletions
⚡ Optional force deletion for read-only files
rename_fileRename or move files and directories
// Simple rename
rename_file({
oldPath: "/path/to/old-name.txt",
newPath: "/path/to/new-name.txt"
})
// Move to different directory
rename_file({
oldPath: "/path/to/file.txt",
newPath: "/different/path/file.txt"
})✨ Features:
📁 Works with both files and directories
🔄 Can move between directories
🚫 Fails if destination already exists
🔒 Both paths must be within allowed directories
list_allowed_directoriesShows which directories the server can access
list_allowed_directories()🔧 Use Cases:
🔍 Check access permissions before operations
🛡️ Security validation
📂 Directory discovery
// 1. Check what directories you can access
list_allowed_directories()
// 2. Explore the project structure
explore_project({
directory: "/your/project/path",
includeHidden: false
})
// 3. Search for specific patterns
search_files({
pattern: "useState",
searchPath: "/your/project/path",
extensions: [".jsx", ".tsx"],
excludeComments: true
})
// 4. Check for outdated dependencies
check_outdated({
projectPath: "/your/project/path",
outputFormat: "detailed"
})// Find all async functions
search_files({
pattern: "async\\s+function",
regexMode: true,
extensions: [".js", ".ts"]
})
// Find large files modified recently
search_files({
pattern: ".*",
minSize: 1000000, // 1MB+
modifiedAfter: "2024-01-01",
sortBy: "size"
})
// Find TODO comments excluding test files
search_files({
pattern: "TODO|FIXME|BUG",
regexMode: true,
excludePatterns: ["*test*", "*spec*"],
excludeStrings: true
})The server operates within allowed directories only, providing:
🔒 Sandboxed access - Cannot access files outside allowed paths
🛡️ Safe operations - Built-in protections against dangerous operations
📂 Path validation - All paths are normalized and validated
⚠️ Error handling - Clear error messages for permission issues
src/
├── index.ts # Main server entry point
├── explore-project.ts # Project analysis tool
├── search.ts # Advanced search functionality
├── check-outdated.ts # NPM dependency checker
├── delete-file.ts # File deletion tool
├── rename-file.ts # File rename/move tool
└── list-allowed.ts # Directory permission checkernpm run build # Compile TypeScript
npm run watch # Watch mode for development
npm run inspector # Test with MCP inspector🍴 Fork the repository
🌟 Create a feature branch
💻 Make your changes
✅ Test thoroughly
🚀 Submit a pull request
See LICENSE file for details. 💚 Qoder
Check for outdated npm packages in package.json using 'npm outdated'. Analyzes the current project's dependencies and shows which packages have newer versions available. Requires npm to be installed and accessible from the command line.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Alias for projectPath | |
| projectPath | No | Path to the directory containing package.json. Defaults to the first allowed directory if not specified. | |
| outputFormat | No | Format of the output: detailed (full info), summary (counts only), or raw (npm command output) | detailed |
| includeDevDependencies | No | Whether to include dev dependencies in the check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It notes the tool uses 'npm outdated' and requires npm, but does not disclose what happens if package.json is missing, if the directory is invalid, or any side effects (e.g., no modifications made). The behavioral impact is not fully detailed.
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 three clear sentences: purpose, action, and prerequisite. Every sentence adds value without redundancy or fluff. It is well-structured for quick scanning by an AI agent.
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 moderate complexity (4 parameters, no output schema), the description provides sufficient high-level context to understand and invoke the tool correctly. It covers the core functionality and requirements, though a bit more detail on return values or error scenarios would push it to 5.
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 100%, so parameters are well-documented in the schema itself. The description adds context by linking the tool's operation to the underlying npm command, which helps understand the 'raw' output option. However, it does not elaborate on parameter usage beyond the schema, so a 4 is appropriate.
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 checks for outdated npm packages using 'npm outdated' and analyzes dependencies for newer versions. It distinguishes itself from sibling tools like explore_project or list_allowed_directories by focusing specifically on npm dependency 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 provides clear when-to-use context: for checking outdated npm packages in a project. It mentions a prerequisite (npm installed and accessible). However, it does not explicitly exclude alternatives when a user might want other dependency checks or provide guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file or directory. Use with extreme caution as this operation cannot be undone. When deleting directories, all contents will be permanently removed. The recursive option must be explicitly set to true to delete non-empty directories. Only works within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file or directory to delete | |
| force | No | Set to true to force deletion even if file is read-only. Use with caution. | |
| recursive | No | Set to true to delete directories and their contents recursively. Required for non-empty directories. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the operation cannot be undone, recursive requirement for directories, force option for read-only files. Does not detail return values or error conditions, but covers key behavioral traits.
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?
Four sentences, each informative: purpose, caution, recursive condition, scope. No filler words, efficient and well-structured.
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?
Does not describe return values (e.g., success confirmation) or error handling (path not found, permission denied). Given no output schema, this gap is notable for a destructive tool.
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?
Parameter schema coverage is 100% with descriptions. The tool description adds context like 'Use with extreme caution' for the entire action, and clarifies 'recursive must be explicitly set to true' and 'force deletion even if read-only', supplementing 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 'Delete a file or directory' with the verb 'Delete' and resource 'file or directory'. It distinguishes from siblings like rename_file and search_files by emphasizing irreversibility.
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 warnings about caution and irreversibility, explains when recursive is needed, and mentions scope restrictions ('Only works within allowed directories'). Does not explicitly name alternatives but implies checking list_allowed_directories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all files in a directory with their sizes. For JS/TS/TSX/JSX it parses imports/exports/functions and resolves local import edges to summarize dependency entanglement. Also extracts import/export-like declarations for common languages (Python/Java/Kotlin/Go/Rust/C#). Excludes common build directories like node_modules, .git, dist, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Alias for directory | |
| directory | No | The directory path to analyze | |
| subDirectory | No | Optional subdirectory within the main directory to analyze | |
| includeHidden | No | Whether to include hidden files and directories (starting with .) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: it always excludes build directories (node_modules, .git, dist), parses imports for JS/TS/TSX/JSX, and extracts declarations for common languages. No annotations exist, so the description carries the full burden. It does not mention error handling, performance implications, or authentication needs, but for a read-only exploration tool, the provided transparency is strong.
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, consisting of four sentences that each add distinct information. It is front-loaded with the primary action ('Lists all files...') and then expands on parsing and exclusions. No filler words or redundant statements. It could be slightly tighter by merging the parsing sentences, but overall it is 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?
The tool is moderately complex (parsing multiple languages, dependency analysis) with 4 optional parameters and no output schema. The description omits the return format entirely—it does not specify whether the output is a list of file objects with size, imports, dependencies, or a summary. Without an output schema, the description should at least hint at the structure of the results. This is a significant gap that reduces the agent's ability to use the tool 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 100% (all 4 parameters have descriptions). The description adds value by clarifying that build directories are always excluded and that the tool lists files with sizes, but it does not elaborate on the 'subDirectory' parameter or the 'includeHidden' impact beyond the schema. The description supplements the schema moderately but does not significantly enhance understanding beyond what the parameter descriptions already provide.
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 primary action: 'Lists all files in a directory with their sizes' and extends to parsing imports/exports for JS/TS/TSX/JSX, resolving dependency edges, and extracting similar declarations for other languages. This specific verb+resource combination distinguishes it from sibling tools like 'search_files' (searching) and 'list_allowed_directories' (listing directories only).
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 implies the tool is for exploring project structure and dependency analysis, but it does not explicitly state when to use it versus alternatives like 'search_files' or 'rename_file'. With five sibling tools, explicit guidance on exclusions (e.g., 'Use this when you need both file listing and dependency analysis, not just file search') would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the list of directories that this MCP server is allowed to access. If empty, the server is running without an allow-list (unrestricted filesystem access).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 transparently discloses the return value (list of allowed directories) and the interpretation of an empty result. The tool has no side effects or destructive behavior, and the description covers the essential behavioral trait.
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 two sentences, very concise, and front-loaded with the primary action. Every sentence earns its place with no wasted words.
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 (no parameters, no output schema, no annotations), the description is complete. It clearly states what is returned and the meaning of the empty list, covering all necessary information for an agent to use the tool 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?
The tool has zero parameters and the input schema has 100% coverage (empty). The description adds no parameter information because none is needed. Per the rubric, zero parameters earns a baseline of 4, and the description does not need to compensate.
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 'Returns' and the resource 'list of directories that this MCP server is allowed to access.' It is specific and distinguishes from sibling tools (explore_project, search_files, etc.) which perform different operations.
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 explains the meaning of an empty list (unrestricted access) but does not explicitly state when to use this tool versus alternatives. While the context makes it self-evident, there is no direct guidance on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename or move a file or directory. Can move files between directories and rename them in a single operation. If the destination exists, the operation will fail. Works across different directories and can be used for simple renaming within the same directory. Both source and destination must be within allowed directories.
| Name | Required | Description | Default |
|---|---|---|---|
| newPath | Yes | New path for the file or directory | |
| oldPath | Yes | Current path of the file or directory to rename |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that the operation fails if destination exists, works across directories, and requires paths within allowed directories, providing good behavioral insight.
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?
Description is 5 sentences, front-loads the main action, and every sentence contributes value. No redundant or extraneous text.
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 purpose, constraints, and behavior. Lacks mention of return values (no output schema) but sufficient for a file rename tool. Sibling tools provide context.
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 100% with parameter descriptions. The description adds context such as the constraint 'Both source and destination must be within allowed directories' and failure condition, enhancing understanding 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 the tool renames/moves files or directories, specifying it can move between directories and rename in one operation. It distinguishes from siblings like delete_file and search_files by focusing on renaming/moving.
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 implies usage for renaming or moving files/directories and mentions failure if destination exists and path constraints, but does not explicitly state when not to use or suggest alternative tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advanced file and code search tool with comprehensive filtering and matching capabilities. Searches files within allowed directories for a required literal or regex pattern, with file type filtering, size constraints, date filtering, and comment/string-aware match suppression (search always runs against the original, unmodified file content). Results can be formatted as text or JSON with configurable sorting and grouping. maxResults caps the total number of returned matches.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Alias for searchPath | |
| sortBy | No | How to sort the results | relevance |
| maxSize | No | Maximum file size in bytes | |
| minSize | No | Minimum file size in bytes | |
| pattern | Yes | Search pattern - literal text or regex depending on regexMode. Required. | |
| maxDepth | No | Maximum directory recursion depth. Unlimited if not specified | |
| multiline | No | Whether to enable multiline regex matching | |
| regexMode | No | Whether to treat pattern as a regular expression | |
| extensions | No | Array of file extensions to include (e.g., ['.js', '.ts', '.py']). Include the dot prefix | |
| maxResults | No | Maximum total number of matches to return (across all files) | |
| searchPath | No | Directory path to search in. Must be within allowed directories. Defaults to first allowed directory if not specified | |
| groupByFile | No | Whether to group results by file | |
| outputFormat | No | Output format for results | text |
| wordBoundary | No | Whether to match whole words only | |
| caseSensitive | No | Whether search should be case sensitive | |
| includeBinary | No | Whether to search in binary files | |
| modifiedAfter | No | Only include files modified after this date (ISO 8601 format) | |
| snippetLength | No | Length of text snippet around matches | |
| excludeStrings | No | Whether to exclude string literals from search | |
| followSymlinks | No | Whether to follow symbolic links | |
| modifiedBefore | No | Only include files modified before this date (ISO 8601 format) | |
| excludeComments | No | Whether to exclude comments from search (language-aware) | |
| excludePatterns | No | Array of filename patterns to exclude (supports simple wildcards) | |
| excludeExtensions | No | Array of file extensions to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does meaningful work: it discloses that match suppression (comments/strings) still "runs against the original, unmodified file content," that the search is confined to allowed directories, and that maxResults caps total returned matches across files. It stops short of stating read-only guarantees/permissions or performance behavior on large trees.
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?
Three sentences, front-loaded with the purpose and followed by filtering behavior and result-shaping behavior. The opening clause "comprehensive filtering and matching capabilities" is mild filler, but otherwise the text is dense and earns its place.
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?
For a 24-parameter, annotation-free, no-output-schema search tool, the description covers scope, pattern semantics, suppression semantics, output formatting, and result capping. What is missing is the safety/permission profile (read-only confirmation) that annotations would normally supply.
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 100% across 24 parameters, so the schema already documents each option thoroughly. The description only adds the semantic that maxResults caps matches across all files and that comment/string exclusion is suppression rather than modification; otherwise it restates what the schema provides, so the baseline 3 applies.
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 gives a specific verb and resource ("Searches files within allowed directories for a required literal or regex pattern") plus the scope of what is searched. It is clear about what the tool does, though it never names or distinguishes itself from the overlapping sibling explore_project.
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?
Usage is implied by the pattern-matching framing — you use this to locate text/regex matches in files — but there is no explicit when-to-use, when-not-to-use, or alternative named against siblings like explore_project or list_allowed_directories.
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.
v0.1.8search_files5 fields changedInput schema / properties / maxResults / descriptionPrevious value: -"Maximum number of match results to return"New value: +"Maximum total number of matches to return (across all files)"Input schema / properties / outputFormat / enumPrevious value: -[
- "text",
- "json",
- "structured"
-]New value: +[
+ "text",
+ "json"
+]Input schema / properties / pattern / defaultRemoved value: -".*"Input schema / properties / pattern / descriptionPrevious value: -"Search pattern - can be literal text or regex depending on regexMode. Defaults to searching for common file types if not specified"New value: +"Search pattern - literal text or regex depending on regexMode. Required."Input schema / requiredPrevious value: -[]New value: +[
+ "pattern"
+]v0.1.2check_outdated1 field changedInput schema / properties / pathAdded value: +{
+ "description": "Alias for projectPath",
+ "type": "string"
+}explore_project2 fields changedInput schema / properties / pathAdded value: +{
+ "description": "Alias for directory",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "directory"
-]New value: +[]search_files1 field changedInput schema / properties / pathAdded value: +{
+ "description": "Alias for searchPath",
+ "type": "string"
+}check_outdateddelete_fileexplore_projectlist_allowed_directoriesrename_filesearch_filesScored across 6 tools
Most tools have clearly distinct purposes: delete_file, rename_file, list_allowed_directories, and check_outdated are unambiguous. The only mild overlap is between search_files (pattern-based search) and explore_project (full directory listing with dependency parsing), which both surface file information and could occasionally be confused.
All six tool names follow a clean snake_case verb_noun pattern (search_files, check_outdated, delete_file, explore_project, list_allowed_directories, rename_file). The convention is applied predictably throughout with no deviations.
Six tools is a slightly lean but reasonable scope for a focused project-exploration server. Each tool earns its place, though the surface leans minimal for the breadth implied by the name.
The set covers search, list, rename, and delete, but there is no tool to read or write file contents—a notable gap for a project explorer where create/copy/read are common needs. check_outdated is also oddly specific and npm-bound, sitting awkwardly beside the generic filesystem operations.
Generate SBOMs, scan vulnerabilities, and analyze dependencies from local projects or Git repos.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
