switch_directory

Instructions

Implementation Reference

• src/tools/directory-tools.ts:104-178 (handler)

  The makeSwitchDirectoryTool function creates the switch_directory ToolHandler. It validates the path is absolute, checks the directory exists via fs.stat, then calls rebuildServices to rebuild all services for the new root path. On success, returns { root, switched: true }.

  function makeSwitchDirectoryTool(
    container: ServiceContainer,
    rebuildServices: RebuildServices,
  ): ToolHandler {
    return {
      name: "switch_directory",
      description:
        "Accepts `{ path }` (absolute path). Rebuilds all services for the new root directory. Returns `{ root, switched: true }` on success. Call `get_stats` after switching to verify.",
      inputSchema: SwitchDirectorySchema,
      async handler(args): Promise<ToolResponse> {
        try {
          const { path: dirPath } = SwitchDirectorySchema.parse(args);
          log.info({ path: dirPath }, "switch_directory called");
  
          if (!path.isAbsolute(dirPath)) {
            return {
              content: [{ type: "text", text: JSON.stringify({
                root: getRoot(container),
                error: `Path must be absolute. Received: ${dirPath}`,
                possibleSolutions: ["Provide a full absolute path (e.g. /home/user/notes or C:\\Users\\user\\notes)"],
              }) }],
              isError: true,
            };
          }
  
          // Validate directory exists
          try {
            const stat = await fs.stat(dirPath);
            if (!stat.isDirectory()) {
              return {
                content: [{ type: "text", text: JSON.stringify({
                  root: getRoot(container),
                  error: `Path is not a directory: ${dirPath}`,
                  possibleSolutions: ["Check the path points to a directory, not a file"],
                }) }],
                isError: true,
              };
            }
          } catch {
            return {
              content: [{ type: "text", text: JSON.stringify({
                root: getRoot(container),
                error: `Directory does not exist: ${dirPath}`,
                possibleSolutions: ["Verify the directory path is correct and the directory exists"],
              }) }],
              isError: true,
            };
          }
  
          const resolvedPath = path.resolve(dirPath);
          container.services = await rebuildServices(resolvedPath);
  
          log.info({ path: resolvedPath }, "switch_directory complete");
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({ root: resolvedPath, switched: true }),
              },
            ],
          };
        } catch (err) {
          log.error({ err }, "switch_directory failed");
          return {
            content: [{ type: "text", text: JSON.stringify({
              root: getRoot(container),
              error: err instanceof Error ? err.message : String(err),
              possibleSolutions: ["Verify the directory path is correct", "Check that the directory exists and is accessible"],
            }) }],
            isError: true,
          };
        }
      },
    };
  }

• src/tools/directory-tools.ts:97-102 (schema)

  SwitchDirectorySchema: Zod schema requiring a 'path' string (min 1 char) described as 'Absolute path to the new root directory'.

  const SwitchDirectorySchema = z.object({
    path: z
      .string()
      .min(1)
      .describe("Absolute path to the new root directory."),
  });

• src/tools/directory-tools.ts:184-198 (registration)

  registerDirectoryTools creates the tool via makeSwitchDirectoryTool(container, rebuildServices) and registers it in the registry Map by name.

  export function registerDirectoryTools(
    registry: Map<string, ToolHandler>,
    container: ServiceContainer,
    rebuildServices: RebuildServices,
  ): void {
    const tools = [
      makeListDirectoryTool(container),
      makeGetStatsTool(container),
      makeSwitchDirectoryTool(container, rebuildServices),
    ];
  
    for (const tool of tools) {
      registry.set(tool.name, tool);
    }
  }

• src/tools/index.ts:67-86 (registration)

  registerTools calls registerDirectoryTools which registers switch_directory. The name is also in LITE_TOOL_NAMES set so it survives --lite mode filtering.

  export function registerTools(
    registry: Map<string, ToolHandler>,
    container: ServiceContainer,
    rebuildServices: RebuildServices,
    options: RegisterToolsOptions = {},
  ): void {
    registerNoteTools(registry, container);
    registerDirectoryTools(registry, container, rebuildServices);
    registerFrontmatterTools(registry, container);
    registerSearchTools(registry, container);
    registerSchemaTools(registry, container);
    registerCreateNoteTool(registry, container);
    registerLinkTools(registry, container);
  
    if (options.lite) {
      for (const name of registry.keys()) {
        if (!LITE_TOOL_NAMES.has(name)) registry.delete(name);
      }
    }
  }

• src/tools/index.ts:14-21 (helper)

  requireServices throws an error mentioning switch_directory: 'Pass --root <path> when starting the server, or call switch_directory to set one.' This is a helper used by the handler.

  export function requireServices(container: ServiceContainer): Services {
    if (!container.services) {
      throw new Error(
        "No directory is active. Pass --root <path> when starting the server, or call switch_directory to set one.",
      );
    }
    return container.services;
  }