filesystem-mcp

Instructions

Implementation Reference

• src/tools/roots.ts:49-58 (handler)

  The handler function that executes the logic to fetch and return the allowed workspace directories.

  function handleListAllowedDirectories(): ToolResponse<
    z.infer<typeof ListAllowedDirectoriesOutputSchema>
  > {
    const dirs = getAllowedDirectories();
    const structured = {
      ok: true,
      directories: dirs,
    } as const;
    return buildToolResponse(buildTextRoots(dirs), structured);
  }

• src/tools/roots.ts:28-37 (schema)

  The tool definition (schema) for the "roots" tool.

  export const LIST_ALLOWED_DIRECTORIES_TOOL: ToolContract = {
    name: 'roots',
    title: 'Workspace Roots',
    description:
      'List allowed workspace roots. Call first \u2014 all other tools are scoped to these directories.',
    inputSchema: ListAllowedDirectoriesInputSchema,
    outputSchema: ListAllowedDirectoriesOutputSchema,
    annotations: READ_ONLY_TOOL_ANNOTATIONS,
    taskSupport: 'forbidden',
  } as const;

• src/tools/roots.ts:60-108 (registration)

  The registration function that registers the "roots" tool with the MCP server.

  export function registerListAllowedDirectoriesTool(
    server: McpServer,
    options: ToolRegistrationOptions = {}
  ): void {
    const handler = (
      _args: z.infer<typeof ListAllowedDirectoriesInputSchema>,
      extra: ToolExtra
    ): Promise<ToolResult<z.infer<typeof ListAllowedDirectoriesOutputSchema>>> =>
      executeToolWithDiagnostics({
        toolName: 'roots',
        extra,
        outputSchema: ListAllowedDirectoriesOutputSchema,
        run: () => handleListAllowedDirectories(),
        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
      });
  
    const wrappedHandler = wrapToolHandler(handler, {
      guard: options.isInitialized,
      progressMessage: () => '≣ roots',
      completionMessage: (_args, result) => {
        if (result.isError) return `≣ roots • failed`;
        const sc = result.structuredContent;
        const count = sc.directories?.length ?? 0;
        return `≣ roots • ${count} ${count === 1 ? 'root' : 'roots'}`;
      },
    });
  
    const validatedHandler = withValidatedArgs(
      ListAllowedDirectoriesInputSchema,
      wrappedHandler
    );
  
    if (
      registerToolTaskIfAvailable(
        server,
        'roots',
        LIST_ALLOWED_DIRECTORIES_TOOL,
        validatedHandler,
        options.iconInfo,
        options.isInitialized
      )
    )
      return;
    server.registerTool(
      'roots',
      withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo),
      validatedHandler
    );
  }