MCP Notes

list_directory

Browse and view the contents of directories in your notes system to locate files and folders. Specify a relative path to explore specific note collections.

Instructions

List the contents of a directory in your notes. Shows all files and directories with clear labels. Specify path relative to your notes directory (e.g., 'Log' or 'Rollups').

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No	Directory path relative to notes directory (defaults to root notes directory if not provided)

Implementation Reference

src/tools/filesystem.ts:289-323 (handler)

The handler function that implements the list_directory tool logic: reads the directory using fs.readdir, formats entries with [DIR]/[FILE] prefixes, ensures path security, and returns formatted content.

export async function handleListDirectory(notesPath: string, args: ListDirectoryArgs): Promise<ToolCallResult> {
  try {
    // Use provided path or default to NOTES_PATH root
    const dirPath = args.path ? path.join(notesPath, args.path) : notesPath;
    
    // Ensure the path is within allowed directory
    if (!dirPath.startsWith(notesPath)) {
      throw new Error("Access denied - path outside notes directory");
    }
    
    try {
      const entries = await fs.readdir(dirPath, { withFileTypes: true });
      const formatted = entries
        .map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`)
        .join("\n");
        
      const relativePath = path.relative(notesPath, dirPath) || '.';
      
      return {
        content: [{ 
          type: "text", 
          text: `Contents of ${relativePath}:\n\n${formatted || "No files or directories found."}` 
        }]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      throw new Error(`Error reading directory: ${errorMessage}`);
    }
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    return {
      content: [{ type: "text", text: `Error listing directory: ${errorMessage}` }],
      isError: true
    };
  }

src/tools/filesystem.ts:101-116 (schema)

Tool definition including name, description, and input schema (optional 'path' parameter) for the list_directory tool, exported via getFilesystemToolDefinitions().

{
  name: "list_directory",
  description: "List the contents of a directory in your notes. " +
    "Shows all files and directories with clear labels. " +
    "Specify path relative to your notes directory (e.g., 'Log' or 'Rollups').",
  inputSchema: {
    type: "object",
    properties: {
      path: { 
        type: "string",
        description: "Directory path relative to notes directory (defaults to root notes directory if not provided)",
        default: ""
      }
    }
  },
},

src/tools/filesystem.ts:35-37 (schema)
TypeScript interface defining the input arguments for the list_directory handler.
```
interface ListDirectoryArgs {
  path?: string;
}
```
src/tools/index.ts:357-358 (registration)
Registration in the main handleToolCall switch statement, dispatching list_directory calls to the handler.
```
case "list_directory":
  return await handleListDirectory(notesPath, args);
```
src/tools/index.ts:204-204 (registration)
Includes filesystem tools (containing list_directory definition) in the main getToolDefinitions() array for tool registration.
```
...filesystemTools
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 15, 2025

TDQS

A4/5.0

Behavior3/5

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 discloses that the tool 'Shows all files and directories with clear labels,' which adds useful behavioral context about the output format. However, it does not mention potential errors (e.g., if the path doesn't exist), permissions, or pagination, leaving gaps for a mutation-free tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by additional details in a second sentence. Every sentence earns its place by clarifying scope and usage, with zero wasted words, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single optional parameter, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and parameter context adequately. A 5 would require addressing minor gaps like error handling or output details, but it's sufficient for basic directory listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the 'path' parameter thoroughly. The description adds marginal value by reinforcing the path specification ('Specify path relative to your notes directory') and providing an example ('e.g., 'Log' or 'Rollups''), but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List the contents of a directory') and resource ('in your notes'), distinguishing it from siblings like read_note (read file content) or search_files (search across files). It specifies the scope ('Shows all files and directories with clear labels'), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('List the contents of a directory in your notes') and includes a usage example ('Specify path relative to your notes directory'). However, it does not explicitly state when not to use it or name alternatives like search_files for filtered searches, which would have earned a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server