obsidian_list_files_in_dir
Read-onlyIdempotent
Explore and list files and directories within your Obsidian vault to navigate organized sections like Zettelkasten folders.
Instructions
List files and directories in a specific vault directory.
Use this tool to explore the contents of a specific folder, such as your
Zettelkasten directory or any other organized section of your vault.
Args:
params (ListFilesInput): Contains:
- dirpath (str): Relative path to directory (empty for root)
Returns:
str: Formatted list of directories and files in the specified path
Example:
For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- Handler function that executes the tool: constructs API endpoint, calls ObsidianClient.get(), extracts files/directories, formats output using helper, handles errors.
async def list_files_in_dir(params: ListFilesInput) -> str: """List files and directories in a specific vault directory. Use this tool to explore the contents of a specific folder, such as your Zettelkasten directory or any other organized section of your vault. Args: params (ListFilesInput): Contains: - dirpath (str): Relative path to directory (empty for root) Returns: str: Formatted list of directories and files in the specified path Example: For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder. """ try: endpoint = f"/vault/{params.dirpath}" if params.dirpath else "/vault/" result = await obsidian_client.get(endpoint) files = result.get("files", []) directories = result.get("directories", []) return format_file_list(files, directories) except ObsidianAPIError as e: return json.dumps({ "error": str(e), "success": False }, indent=2) - Pydantic model defining input schema: optional dirpath (str, default empty for root).
class ListFilesInput(BaseModel): """Input for listing files in a directory.""" model_config = ConfigDict(str_strip_whitespace=True, extra='forbid') dirpath: Optional[str] = Field( default="", description="Relative directory path to list (empty string for vault root)", max_length=500 ) - src/custom_obsidian_mcp/server.py:432-441 (registration)MCP tool registration decorator specifying name and annotations (read-only, idempotent).
@mcp.tool( name="obsidian_list_files_in_dir", annotations={ "title": "List Files in Directory", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": False } ) - Helper function formats lists of files and directories into markdown with emojis and sections.
def format_file_list(files: List[str], directories: List[str]) -> str: """Format file and directory lists for display.""" result = [] if directories: result.append("## Directories") for d in sorted(directories): result.append(f"- 📁 {d}/") result.append("") if files: result.append("## Files") for f in sorted(files): result.append(f"- 📄 {f}") return "\n".join(result) if result else "No files or directories found."