obsidian-mcp-server
Version:
MCP server for Obsidian vaults — read, write, search, and surgically edit notes, tags, and frontmatter via the Local REST API plugin. STDIO or Streamable HTTP.
68 lines • 3.41 kB
TypeScript
/**
* @fileoverview obsidian_list_notes — recursive vault listing with bounded depth.
* Walks the vault tree DFS up to `depth` levels (default 2 — top-level + their
* immediate children, the structural-overview sweet spot), applying optional
* extension and nameRegex filters across the walk, and renders both a flat
* `entries[]` array (for programmatic consumption) and a box-drawing tree view
* in `format()` (for LLM consumption — tree views are easier to scan than flat
* paths). Hard cap at {@link ENTRY_CAP} entries protects against runaway HTTP
* fan-out on large vaults; per-directory `truncated: true` flags signal where
* the depth limit cut off recursion. Drill deeper by passing a higher `depth`,
* narrowing with `path`, or filtering with `extension`/`nameRegex`.
*
* Named `_notes` rather than `_files` to disambiguate from agents' generic
* file-system tools (Read, Glob, LS) — a `_files` tool surface tempts agents
* to fish for non-vault paths through it.
* @module mcp-server/tools/definitions/obsidian-list-notes.tool
*/
import { z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
export declare const obsidianListNotes: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
path: z.ZodOptional<z.ZodString>;
extension: z.ZodOptional<z.ZodString>;
nameRegex: z.ZodOptional<z.ZodString>;
depth: z.ZodDefault<z.ZodNumber>;
}, z.core.$strip>, z.ZodObject<{
path: z.ZodString;
entries: z.ZodArray<z.ZodObject<{
path: z.ZodString;
type: z.ZodEnum<{
file: "file";
directory: "directory";
}>;
truncated: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>>;
totals: z.ZodObject<{
entries: z.ZodNumber;
files: z.ZodNumber;
directories: z.ZodNumber;
}, z.core.$strip>;
appliedFilters: z.ZodObject<{
extension: z.ZodOptional<z.ZodString>;
nameRegex: z.ZodOptional<z.ZodString>;
depth: z.ZodNumber;
}, z.core.$strip>;
excluded: z.ZodOptional<z.ZodObject<{
reason: z.ZodLiteral<"entry_cap">;
cap: z.ZodNumber;
hint: z.ZodString;
}, z.core.$strip>>;
}, z.core.$strip>, readonly [{
readonly reason: "regex_invalid";
readonly code: JsonRpcErrorCode.ValidationError;
readonly when: "The supplied `nameRegex` is not a valid ECMAScript regex.";
readonly recovery: "Use a valid ECMAScript regex (e.g. `^Project.*\\.md$`), or omit nameRegex to disable filtering.";
}, {
readonly reason: "path_forbidden";
readonly code: JsonRpcErrorCode.Forbidden;
readonly when: "The supplied `path` is outside OBSIDIAN_READ_PATHS (root listings always pass; specific subdirectories must be readable).";
readonly recovery: "List a directory inside the configured read scope, or omit `path` to list from the vault root. The error data echoes the active scope.";
}, {
readonly reason: "note_missing";
readonly code: JsonRpcErrorCode.NotFound;
readonly when: "The supplied `path` does not exist in the vault. Sub-directories that disappear mid-walk are silently skipped — only the root path surfaces this error.";
readonly recovery: "List a parent directory to find the correct casing or check the spelling.";
}], {
readonly notice: z.ZodOptional<z.ZodString>;
}>;
//# sourceMappingURL=obsidian-list-notes.tool.d.ts.map