Project Explorer MCP Server provides tools for analyzing, searching, and managing project files, with safety restrictions.
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 and Dart files
š¦ Flutter/Dart dependency graph: resolves package: URIs, implicit-relative imports, and part/part of codegen links via pubspec.yaml (including local path: dependencies in monorepos)
š¦ pubspec.yaml summaries: package name, SDK constraints, dependency counts, path deps, declared assets
š« Automatically excludes build directories (node_modules, .git, dist, .vscode, .gradle, .idea, .dart_tool, Pods, ephemeral, 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, incl. Dart) |
| boolean |
| Skip string literals |
| boolean |
| Skip generated Dart parts ( |
| 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 and Dart it parses imports/exports/functions and resolves local import edges (including Dart package: URIs and pubspec.yaml path dependencies) to summarize dependency entanglement. Reports Dart/Flutter packages found via pubspec.yaml (name, SDK constraints, deps, assets). Also extracts import/export-like declarations for common languages (Python/Java/Kotlin/Go/Rust/C#). Excludes common build directories like node_modules, .git, dist, .dart_tool, 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?
With no annotations, the description must disclose behavioral traits itself. It does so richly: it lists files with sizes, parses imports/exports, resolves dependency edges, reports Dart packages, and declares exclusions for build directories. It does not mention permissions, side effects, or edge cases like symlinks, but the read-only, analytical nature is clearly conveyed.
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 a single, information-dense paragraph. It front-loads the primary function and then adds details about supported languages and exclusions. While every sentence contributes unique content, the structure could be more scannable with bullet points, so it earns a 4 rather than 5.
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 (language parsing, dependency resolution, package reporting), the description covers the major behaviors and inputs. There is no output schema and no annotations, so the description partially compensates by describing what is reported, but it does not detail the exact output structure or error handling, leaving some gaps for an agent.
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 schema descriptions already cover all four parameters (100% coverage), so the description is not required to explain them. The description adds little beyond the schema: it mentions directories generically but does not elaborate on path, subDirectory, or includeHidden semantics. 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 opens with a clear action and resource: 'Lists all files in a directory with their sizes.' It then enumerates additional analyses, making the tool's purpose concrete. It does not explicitly differentiate from siblings like search_files, but the core listing/analyzing behavior is clearly distinct.
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 a thorough explanation of what the tool does, which implies when it should be used (e.g., to get an overview of a project and its dependencies). However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions/alternatives, so guidance is only implied.
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) | |
| excludeGenerated | No | Whether to skip code-generated Dart part files (*.g.dart, *.freezed.dart, *.mocks.dart, *.gr.dart, *.i18n.dart) | |
| excludeExtensions | No | Array of file extensions to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It reveals a nuanced behaviorāsearching against original unmodified content, plus comment/string-aware suppression, result caps, and formatting optionsāwhich goes well beyond a generic read-only statement. It could be more explicit about non-mutating guarantees or permission requirements, but for a search tool this 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 efficiently structured with the core purpose first, then matching behavior, then output options. It is slightly promotional with 'Advanced' and 'comprehensive' but every sentence carries real information, and it remains compact given the tool's 25 parameters.
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 and lack of annotations or output schema, the description covers the essential behavioral and output context well. It does not explain the JSON result shape or how to discover allowed directories, but for a search tool the high-level completeness is adequate for correct selection and invocation.
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%, so the baseline is 3. The description adds cross-parameter semantics by grouping capabilities (file type filtering, size constraints, date filtering), clarifying that maxResults caps total matches, and indicating that output can be formatted as text or JSON. This helps an agent understand how parameters interact beyond individual schema descriptions.
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 identifies a specific verb ('searches'), a resource ('files within allowed directories'), and key capabilities (literal/regex, filtering, output formatting). It distinguishes from siblings like explore_project and rename_file because it is framed as a search, not a browse or mutate operation.
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 usage context is implied: use this when you need to find file/code matches. It states the search operates within allowed directories, but does not explicitly name alternatives or when not to use this tool, such as when exploring project structure (explore_project) or listing directories (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.9search_files1 field changedInput schema / properties / excludeGeneratedAdded value: +{
+ "default": false,
+ "description": "Whether to skip code-generated Dart part files (*.g.dart, *.freezed.dart, *.mocks.dart, *.gr.dart, *.i18n.dart)",
+ "type": "boolean"
+}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
Each tool serves a distinct purpose: listing allowed dirs, renaming/moving, project exploration with dependency analysis, content search, npm outdated check, and deletion. There is no overlap or ambiguity between them.
All tool names follow a consistent snake_case verb_noun pattern (e.g., list_allowed_directories, rename_file, explore_project). The naming is uniform and predictable.
With 6 tools, the server is well-scoped for a project exploration and file management utility. The count is within the ideal range and each tool contributes to the core functionality.
The tool set covers listing, searching, renaming, deleting, and dependency checks, but lacks basic file operations like creating or reading file content. This is a notable gap for a file-related server, though the exploration focus mitigates it partially.
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.
